----------- Introduction ----------
+========== Introduction ==========
+
+Basic approach:
+ 1. Get yourself a working Xen dom0 setup, eg according to
+ https://wiki.ubuntu.com/XenOnEdgy
+ 2. Configure adtxenlvm:
+ - assign a fixed IP address for the host and the testbed
+ - create DNS entries (forward and reverse)
+ for the testbed hostname edgy.adt.<your.domain.here>
+ - read below about settings you might want to set
+ creating /etc/autopkgtest/xenlvm_adt_config if needed
+ 3. adt-xenlvm-setup
+ 4. adt-xenlvm-with-testbed
+ 5. adt-xenlvm-on-testbed
+
+In some more detail, there are four main programs provided:
+
+ adt-xenlvm-setup [<config settings>]
+ Creates the snapshot. Broadly speaking, does the following:
+ - deletes any existing snapshot, virtual machine, etc.
+ - creates a new lvm volume and filesystem for the snapshot base
+ - runs debootstrap to install a system into the new filesystem
+ - makes necessary config changes to the testbed and the host
+ - boots the testbed and waits for it to start
+ - freezes the testbed into a snapshot file
+ After this, you can run with-testbed.
+
+ adt-xenlvm-with-testbed [<config settings>] [<master> [<args...>]]
+ Starts the testbed and runs <master> _on the HOST_. When
+ <master> finishes, the testbed state will be discarded. While
+ <master> is running, you can interact with the testbed. If
+ <master> is not specified, you get an interactive shell.
+
+ adt-xenlvm-on-testbed [<config settings>] [<command and args>]
+ Runs <command and args> on the running testbed. A <master>
+ child of adt-xenlvm-with-testbed must be running, or the
+ behaviour is not defined. However, adt-xenlvm-on-testbed does
+ not need to be a descendent of adt-xenlvm-with-testbed.
+ The arguments <command and args> are passed to ssh verbatim
+ and are therefore subject to ssh's unpleasant mangling.
+
+ adt-xenlvm-cleanup [<config settings>]
+ Cleans up any running testbed state. This is not normally
+ needed, as adt-xenlvm-with-testbed and adt-xenlvm-setup run it
+ at appropriate moments. However, if one of these should fail
+ and it is desirable to reclaim any resources used by the
+ testbed, cleanup will do this job.
+
+ adt-xenlvm-purge [<config settings>]
+ Deletes all of the data for the testbed. Ie, undoes
+ the effects of adt-xenlvm-setup.
+
+In each case [<config settings>] is zero or more arguments of the form
+ --<config-var>=<value>
+where <config-var> is one of the configuration items listed below.
+(On the command line, the configuration item name may be spelled with
+either hyphens or underscores.) Also, `--' may be used to indicate the
+end of the config vars.
+
+
+
+========== Configuration ==========
The configuration is read as follows:
1. set all variables whose defaults are fixed strings to
those built-in default values
2. process the command line arguments
3. read the user configuration file (sourced by bash)
+ this file must not use fds 10 onwards, which may have been used
+ for other purposes by other adtxenlvm machinery
4. process the command line arguments again, so they
can easily be made to override the user configuration file
5. calculate the values for variables which haven't been set
prohibited from communicating, notwithstanding
allowglobalports.
-adt_fw_allowglobalports 80
+adt_fw_allowglobalports <none>
List of ports to which the testbed will be allowed to make
outgoing connections.
+adt_fw_hook <config> with _config replaced with _fwhook
+ or none if <config> doesn't end in _config
+ bash fragment to source during firewall setup
+
+adt_sshauthkeys_hook <config> with _config replaced with _sshauthkeys
+ or none if <config> doesn't end in _config
+ list of authorized keys to append to testbed's
+ /root/.ssh/authorized_keys.
+
---------- Items that are likely to need attention ----------
-adt_kernel the booted kernel file /boot/xen*`uname -r`
+adt_kernel Xen kernel matching /boot/xen*`uname -r`
Kernel to boot in the testbed image
-adt_ramdisk <kernel>.initrd.img
+adt_ramdisk initrd.img-* where <kernel> is vmlinuz-*
Initial ramdisk to provide to the testbid image.
"none" means do not provide an initial ramdisk.
adt_modules /lib/modules/`uname -r`
Directory with modules to be copied into the testbed.
+ If this directory does not exist, no modules will be copied.
adt_lvm_vg the system's LVM volume group if there is only one
LVM volume group to create base filesystem image in.
-adt_pbuilder_args <none>
- Extra arguments to pass to pbuilder.
+adt_distro host system's distribution
+ Distribution name (eg, `edgy', `feisty', `sarge', `etch').
+
+adt_lvm_erasebase true
+ Whether the base filesystem image needs to be filled with
+ zeroes. If you are going to be using the image only locally
+ and so don't care whether the base image contains bits of
+ previous data from the disk, you may set this to `no'.
+
+adt_debootstrap_opts <none>
+ Extra options to pass to debootstrap.
+
+adt_debootstrap_includemore <empty>
+adt_debootstrap_include libc6-xen,openssh-server,ed
+ Comma-separated lists of packages for --include option to
+ debootstrap. It is best to set includemore.
+
+adt_debootstrap_components *
+ Components of the distribution to consider. (Eg, `main'.)
+
+adt_debootstrap_mirrors <empty string>
+adt_debootstrap_script <empty string>
+ Third and fourth arguments to debootstrap.
+
+adt_setup_hook <config> with _config replaced with
+ _setuphook, as for adt_fw_hook
+ Program to run at last moment before we freeze the image.
+ Will be invoked with one argument: the directory containing
+ the root of the testbed. In the future more arguments may be
+ defined, so the hook script should not fail if more are
+ supplied. The supplied hook value will be split at
+ whitespace before execution as if
+ $adt_setup_hook /path/to/root
+ was run from within a shellscript.
---------- Tuning parameters ----------
to this before freezing it and grow it again when we resume
it.
-adt_fs_size 1G
+adt_fs_size 6144M
Size of base filesystem image. Should be big enough to
contain all of the software under test and all of its working
space, as no running testbed can ever use more than this
(despite copy-on-write).
-adt_fs_snapsize 500M
+adt_fs_snapsize 5120M
Space to allocate for copy-on-write snapshot data. This is
the maximum amount of data that a running testbed can use.
This value should be less than the adt_fs_size.
adt_fs_cowchunk 8 [Mby]
Copy-on-write chunk size.
+adt_swap_size 5120M
+ Swapspace to provide to guests. This is done with
+ copy-on-write just as for the filesystems. The snapshot area
+ is (necessarily) the same size as the swapspace itself.
+
+adt_swap_cowchunk <fs_cowchunk>
+ Copy-on-write chunk size for swap area.
+
adt_vm_reduce_retries 10 [seconds]
Time to wait for VM to reduce its memory following
xm mem-set.
it will be separated by other parts by underscores `_', so
they should be avoided.
+adt_lvm_swapvg <lvm_vg>
+ VG to use for guest's swap.
+
+adt_lvm_eraseswap <lvm_erasebase>
+ Whether the base swap image needs to be filled with zeroes.
+
+adt_lvm_pv_fsbase <none>
+adt_lvm_pv_fssnap <none>
+adt_lvm_pv_swapbase <none>
+adt_lvm_pv_swapsnap <none>
+ Specifies specific LVM PVs to use. The default is to leave it
+ up to lvcreate.
+
adt_guest_macaddr 00:16:3e:7c:aa:7f
adt_net_vifscript /etc/xen/scripts/vif-route-adt
+adt_normaluser adtxenu
+ Create a normal user account of this name, with disabled
+ password.
+
---------- Items which should not usually need to be changed ----------
adt_host_hostname `hostname -f`
Playground area for this particular testbed construction and
data.
+adt_lock <playbase>.lock
+ Lockfile. Used to prevent multiple simultaneous runs of
+ setup, purge, clean, with-testbed, etc. The lock is held
+ according to the rules for with-lock-ex from chiark-utils-bin.
+ Set adt_lock to "none" to disable locking. Note that the
+ lockfile ought not to be in <playbase> because the setup
+ process erases the whole of <playbase> but ought to hold the
+ lock continuously.
+
adt_xmconfig <play>/xmconfig
Xen virtual machine creation configuration for xm create.
This file will be (over)written during testbed setup.
adt_lvm_baselv <nominum>_<distro>_base
adt_lvm_cowdatalv <nominum>_<distro>_cowdata
+adt_lvm_snapbaselv <nominum>_<distro>_swapbase
+adt_lvm_snapcowdatalv <nominum>_<distro>_swapcowdata
LVM volume for base filesystem image, and copy-on-write
buffer. Will be created during testbed setup, destroying any
previous volume if necessary. This is the logical volume name
not including /dev/<lvm_vg>.
-adt_devmapper_cowdev <nominum>_<distro>_snap
+adt_devmapper_cowdev <nominum>_<distro>_snap
+adt_devmapper_swapcowdev <nominum>_<distro>_swapsnap
devmapper device for copy-on-write image used by testbed when
running. This is the device name in the devmapper namespace,
ie not including /dev/mapper.
adt_fslink_dir adt-xenlvm
+adt_swaplink_dir adt-xenlvm
adt_fslink_name <nominum>_<distro>_fs
+adt_swaplink_name <nominum>_<distro>_swap
Directory in /dev, and filename in that directory, where the
scripts put the symlink used to trick Xen into using a
different block device on resume than was used for creation.
adt_xmname <nominum>_<distro>
Xen virtual machine name, as passed to xm create.
+
+adt_xmhook_disk <empty>
+adt_xmhook_vif <empty>
+adt_xmhook_extra <empty>
+adt_xmhook_config <empty>
+ The values of these variables are inserted into the Xen domU
+ configuration file. _disk and _vif should contain zero or
+ more comma-prefixed double-quoted stanzas - they are
+ substituted inside the [ ] after the primary filesystem and
+ network devices set up by the adt-xenlvm tools. _extra
+ contains additional space-separated kernel command-line
+ options and is substituted inside the double-quotes. _config
+ should contain whole configuration lines. See
+ xmdomain.cfg(5).
~ianmdlvl / autopkgtest.git / blobdiff