========== 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. - 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 [] 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 [] [ []] Starts the testbed and runs _on the HOST_. When finishes, the testbed state will be discarded. While is running, you can interact with the testbed. If is not specified, you get an interactive shell. adt-xenlvm-on-testbed [] [] Runs on the running testbed. A 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 are passed to ssh verbatim and are therefore subject to ssh's unpleasant mangling. adt-xenlvm-cleanup [] 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 [] Deletes all of the data for the testbed. Ie, undoes the effects of adt-xenlvm-setup. In each case [] is zero or more arguments of the form --= where 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 and whose default values depend on circumstances (including on other variables) ---------- Items which definitely need attention ---------- adt_guests_domain . adt_guest_hostname .[.] adt_guest_ipaddr from looking hostname up in the DNS Hostname and IP address for the testbed. If the configuration specifies one of the address and hostname but not the other, the missing information will be found with a DNS lookup. If neither is specified, adt_guests_domain is used; if it starts with `.' then . is prepended; otherwise just . is prepended. NOTE: some effort by the local network administrator to allocate an IP address (and ideally create DNS entries) is essential. It is not possible to use DHCP for IP address allocation for the testbed. ---------- Firewall policy items ---------- adt_fw_localmirrors List of IP addresses of local mirrors, to which the testbed should allowed to make HTTP requests. adt_fw_testbedclients List of IP addresses of hosts which will be allowed to make connections into the testbed system. adt_fw_prohibnets 192.168.0.0/24 172.16.0.0/12 10.0.0.0/8 List of network ranges with which the testbed will be prohibited from communicating, notwithstanding allowglobalports. adt_fw_allowglobalports List of ports to which the testbed will be allowed to make outgoing connections. adt_fw_hook with _config replaced with _fwhook or none if doesn't end in _config bash fragment to source during firewall setup adt_sshauthkeys_hook with _config replaced with _sshauthkeys or none if 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 Xen kernel matching /boot/xen*`uname -r` Kernel to boot in the testbed image adt_ramdisk initrd.img-* where 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_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 Extra options to pass to debootstrap. adt_debootstrap_includemore 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 adt_debootstrap_script Third and fourth arguments to debootstrap. adt_setup_hook 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 ---------- adt_fs_type ext3 adt_fs_mkfs_args Filesystem type and any additional arguments to mkfs. If _args contains whitespace, it results in multiple arguments; it is not possible to pass whitespace-containing arguments to mkfs. adt_testbed_ram 256 [Mby] Physical RAM allocated for each testbed instance while creating and running. adt_freeze_ram 32 [Mby] Physical RAM size for frozen image; we reduce the testbed to this before freezing it and grow it again when we resume it. 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 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 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. ---------- Configuration for advanced uses ---------- adt_config /etc/autopkgtest/xenlvm__conf adt_ssh_keytype dsa adt_ssh_privkey /root/.ssh/id__ adt_ssh_pubkey .pub adt_ssh_keyident_args -i adt_ssh_keygen_args -t SSH keypair to use for authentication to the testbed. If the pubkey file and privkey file do not exist and correspond to each other, a new key will be generated. The best combinations of these variables to set are: keytype [& keygen_args] - just change the key type privkey [& keygen_args] - generate/use a different keypair pubkey, keyident_args - use an existing key via agent etc., privkey is ignored if pubkey and keyident_args are set and pubkey file exists adt_nominum adt Namespace prefix for Xen domains, LVM volumes, devmapper devices, entries in /dev, files in /var, and so on. You may run several instances of the adt virtualisation system with different nominums and they won't interact. It is best for this to be a legal DNS label (using alphanumerics and hyphens only); normally it when it is used to construct an identifier it will be separated by other parts by underscores `_', so they should be avoided. adt_lvm_swapvg VG to use for guest's swap. adt_lvm_eraseswap Whether the base swap image needs to be filled with zeroes. adt_lvm_pv_fsbase adt_lvm_pv_fssnap adt_lvm_pv_swapbase adt_lvm_pv_swapsnap 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` adt_host_ipaddr from looking hostname up in the DNS Hostname and IP address for the host, ie the Xen dom0 system. If the configuration specifies one of the address and hostname but not the other, the missing information will be found with a DNS lookup. Note that if the host system uses a dynamically allocated DHCP address, things will go wrong when the address changes. adt_playbase /var/lib/autopkgtest/xenlvm Base of filesystem playground areas. adt_play /_ Playground area for this particular testbed construction and data. adt_lock .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 because the setup process erases the whole of but ought to hold the lock continuously. adt_xmconfig /xmconfig Xen virtual machine creation configuration for xm create. This file will be (over)written during testbed setup. adt_lvm_baselv __base adt_lvm_cowdatalv __cowdata adt_lvm_snapbaselv __swapbase adt_lvm_snapcowdatalv __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/. adt_devmapper_cowdev __snap adt_devmapper_swapcowdev __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 __fs adt_swaplink_name __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 _ Xen virtual machine name, as passed to xm create. adt_xmhook_disk adt_xmhook_vif adt_xmhook_extra adt_xmhook_config 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).