1 ========== Introduction ==========
4 1. Get yourself a working Xen dom0 setup, eg according to
5 https://wiki.ubuntu.com/XenOnEdgy
6 2. Configure adtxenlvm:
7 - assign a fixed IP address for the host and the testbed
8 - create DNS entries (forward and reverse)
9 for the testbed hostname edgy.adt.<your.domain.here>
10 - read below about settings you might want to set
11 creating /etc/autopkgtest/xenlvm_adt_config if needed
13 4. adt-xenlvm-with-testbed
14 5. adt-xenlvm-on-testbed
16 In some more detail, there are four main programs provided:
18 adt-xenlvm-setup [<config settings>]
19 Creates the snapshot. Broadly speaking, does the following:
20 - deletes any existing snapshot, virtual machine, etc.
21 - creates a new lvm volume and filesystem for the snapshot base
22 - runs debootstrap to install a system into the new filesystem
23 - makes necessary config changes to the testbed and the host
24 - boots the testbed and waits for it to start
25 - freezes the testbed into a snapshot file
26 After this, you can run with-testbed.
28 adt-xenlvm-with-testbed [<config settings>] [<master> [<args...>]]
29 Starts the testbed and runs <master> _on the HOST_. When
30 <master> finishes, the testbed state will be discarded. While
31 <master> is running, you can interact with the testbed. If
32 <master> is not specified, you get an interactive shell.
34 adt-xenlvm-on-testbed [<config settings>] [<command and args>]
35 Runs <command and args> on the running testbed. A <master>
36 child of adt-xenlvm-with-testbed must be running, or the
37 behaviour is not defined. However, adt-xenlvm-on-testbed does
38 not need to be a descendent of adt-xenlvm-with-testbed.
39 The arguments <command and args> are passed to ssh verbatim
40 and are therefore subject to ssh's unpleasant mangling.
42 adt-xenlvm-cleanup [<config settings>]
43 Cleans up any running testbed state. This is not normally
44 needed, as adt-xenlvm-with-testbed and adt-xenlvm-setup run it
45 at appropriate moments. However, if one of these should fail
46 and it is desirable to reclaim any resources used by the
47 testbed, cleanup will do this job.
49 adt-xenlvm-purge [<config settings>]
50 Deletes all of the data for the testbed. Ie, undoes
51 the effects of adt-xenlvm-setup.
53 In each case [<config settings>] is zero or more arguments of the form
54 --<config-var>=<value>
55 where <config-var> is one of the configuration items listed below.
56 (On the command line, the configuration item name may be spelled with
57 either hyphens or underscores.) Also, `--' may be used to indicate the
58 end of the config vars.
62 ========== Configuration ==========
64 The configuration is read as follows:
65 1. set all variables whose defaults are fixed strings to
66 those built-in default values
67 2. process the command line arguments
68 3. read the user configuration file (sourced by bash)
69 this file must not use fds 10 onwards, which may have been used
70 for other purposes by other adtxenlvm machinery
71 4. process the command line arguments again, so they
72 can easily be made to override the user configuration file
73 5. calculate the values for variables which haven't been set
74 and whose default values depend on circumstances (including
77 ---------- Items which definitely need attention ----------
79 adt_guests_domain .<domain-of-host_hostname>
80 adt_guest_hostname <distro>.[<nominum>.]<domain>
81 adt_guest_ipaddr from looking hostname up in the DNS
82 Hostname and IP address for the testbed.
83 If the configuration specifies one of the address and hostname
84 but not the other, the missing information will be found with
85 a DNS lookup. If neither is specified, adt_guests_domain is
86 used; if it starts with `.' then <distro>.<nominum> is
87 prepended; otherwise just <distro>. is prepended. NOTE: some
88 effort by the local network administrator to allocate an IP
89 address (and ideally create DNS entries) is essential. It is
90 not possible to use DHCP for IP address allocation for the
93 ---------- Firewall policy items ----------
95 adt_fw_localmirrors <none>
96 List of IP addresses of local mirrors, to which the
97 testbed should allowed to make HTTP requests.
99 adt_fw_testbedclients <host_ipaddr>
100 List of IP addresses of hosts which will be allowed to make
101 connections into the testbed system.
103 adt_fw_prohibnets 192.168.0.0/24 172.16.0.0/12 10.0.0.0/8
104 List of network ranges with which the testbed will be
105 prohibited from communicating, notwithstanding
108 adt_fw_allowglobalports <none>
109 List of ports to which the testbed will be allowed to make
110 outgoing connections.
112 adt_fw_hook <config> with _config replaced with _fwhook
113 or none if <config> doesn't end in _config
114 bash fragment to source during firewall setup
116 adt_sshauthkeys_hook <config> with _config replaced with _sshauthkeys
117 or none if <config> doesn't end in _config
118 list of authorized keys to append to testbed's
119 /root/.ssh/authorized_keys.
121 ---------- Items that are likely to need attention ----------
123 adt_kernel Xen kernel matching /boot/xen*`uname -r`
124 Kernel to boot in the testbed image
126 adt_ramdisk initrd.img-* where <kernel> is vmlinuz-*
127 Initial ramdisk to provide to the testbid image.
128 "none" means do not provide an initial ramdisk.
130 adt_modules /lib/modules/`uname -r`
131 Directory with modules to be copied into the testbed.
132 If this directory does not exist, no modules will be copied.
134 adt_lvm_vg the system's LVM volume group if there is only one
135 LVM volume group to create base filesystem image in.
137 adt_distro host system's distribution
138 Distribution name (eg, `edgy', `feisty', `sarge', `etch').
140 adt_lvm_erasebase true
141 Whether the base filesystem image needs to be filled with
142 zeroes. If you are going to be using the image only locally
143 and so don't care whether the base image contains bits of
144 previous data from the disk, you may set this to `no'.
146 adt_debootstrap_opts <none>
147 Extra options to pass to debootstrap.
149 adt_debootstrap_includemore <empty>
150 adt_debootstrap_include libc6-xen,openssh-server,ed
151 Comma-separated lists of packages for --include option to
152 debootstrap. It is best to set includemore.
154 adt_debootstrap_components *
155 Components of the distribution to consider. (Eg, `main'.)
157 adt_debootstrap_mirrors <empty string>
158 adt_debootstrap_script <empty string>
159 Third and fourth arguments to debootstrap.
161 adt_setup_hook <config> with _config replaced with
162 _setuphook, as for adt_fw_hook
163 Program to run at last moment before we freeze the image.
164 Will be invoked with one argument: the directory containing
165 the root of the testbed. In the future more arguments may be
166 defined, so the hook script should not fail if more are
167 supplied. The supplied hook value will be split at
168 whitespace before execution as if
169 $adt_setup_hook /path/to/root
170 was run from within a shellscript.
172 ---------- Tuning parameters ----------
175 adt_fs_mkfs_args <none>
176 Filesystem type and any additional arguments to mkfs. If
177 _args contains whitespace, it results in multiple arguments;
178 it is not possible to pass whitespace-containing arguments to
181 adt_testbed_ram 256 [Mby]
182 Physical RAM allocated for each testbed instance while
183 creating and running.
185 adt_freeze_ram 32 [Mby]
186 Physical RAM size for frozen image; we reduce the testbed
187 to this before freezing it and grow it again when we resume
191 Size of base filesystem image. Should be big enough to
192 contain all of the software under test and all of its working
193 space, as no running testbed can ever use more than this
194 (despite copy-on-write).
196 adt_fs_snapsize 5120M
197 Space to allocate for copy-on-write snapshot data. This is
198 the maximum amount of data that a running testbed can use.
199 This value should be less than the adt_fs_size.
201 adt_fs_cowchunk 8 [Mby]
202 Copy-on-write chunk size.
205 Swapspace to provide to guests. This is done with
206 copy-on-write just as for the filesystems. The snapshot area
207 is (necessarily) the same size as the swapspace itself.
209 adt_swap_cowchunk <fs_cowchunk>
210 Copy-on-write chunk size for swap area.
212 adt_vm_reduce_retries 10 [seconds]
213 Time to wait for VM to reduce its memory following
216 ---------- Configuration for advanced uses ----------
218 adt_config /etc/autopkgtest/xenlvm_<nominum>_conf
221 adt_ssh_privkey /root/.ssh/id_<ssh_keytype>_<nominum>
222 adt_ssh_pubkey <ssh_privkey>.pub
223 adt_ssh_keyident_args -i <ssh_privkey>
224 adt_ssh_keygen_args -t <ssh_keytype>
225 SSH keypair to use for authentication to the testbed.
226 If the pubkey file and privkey file do not exist and
227 correspond to each other, a new key will be generated.
228 The best combinations of these variables to set are:
229 keytype [& keygen_args] - just change the key type
230 privkey [& keygen_args] - generate/use a different keypair
231 pubkey, keyident_args - use an existing key via agent etc.,
232 privkey is ignored if pubkey and keyident_args
233 are set and pubkey file exists
236 Namespace prefix for Xen domains, LVM volumes, devmapper
237 devices, entries in /dev, files in /var, and so on. You may
238 run several instances of the adt virtualisation system with
239 different nominums and they won't interact. It is best for
240 this to be a legal DNS label (using alphanumerics and hyphens
241 only); normally it when it is used to construct an identifier
242 it will be separated by other parts by underscores `_', so
243 they should be avoided.
245 adt_lvm_swapvg <lvm_vg>
246 VG to use for guest's swap.
248 adt_lvm_eraseswap <lvm_erasebase>
249 Whether the base swap image needs to be filled with zeroes.
251 adt_lvm_pv_fsbase <none>
252 adt_lvm_pv_fssnap <none>
253 adt_lvm_pv_swapbase <none>
254 adt_lvm_pv_swapsnap <none>
255 Specifies specific LVM PVs to use. The default is to leave it
258 adt_guest_macaddr 00:16:3e:7c:aa:7f
259 adt_net_vifscript /etc/xen/scripts/vif-route-adt
261 adt_normaluser adtxenu
262 Create a normal user account of this name, with disabled
265 ---------- Items which should not usually need to be changed ----------
267 adt_host_hostname `hostname -f`
268 adt_host_ipaddr from looking hostname up in the DNS
269 Hostname and IP address for the host, ie the Xen dom0 system.
270 If the configuration specifies one of the address and hostname
271 but not the other, the missing information will be found with
272 a DNS lookup. Note that if the host system uses a dynamically
273 allocated DHCP address, things will go wrong when the address
276 adt_playbase /var/lib/autopkgtest/xenlvm
277 Base of filesystem playground areas.
279 adt_play <playbase>/<nominum>_<distro>
280 Playground area for this particular testbed construction and
283 adt_lock <playbase>.lock
284 Lockfile. Used to prevent multiple simultaneous runs of
285 setup, purge, clean, with-testbed, etc. The lock is held
286 according to the rules for with-lock-ex from chiark-utils-bin.
287 Set adt_lock to "none" to disable locking. Note that the
288 lockfile ought not to be in <playbase> because the setup
289 process erases the whole of <playbase> but ought to hold the
292 adt_xmconfig <play>/xmconfig
293 Xen virtual machine creation configuration for xm create.
294 This file will be (over)written during testbed setup.
296 adt_lvm_baselv <nominum>_<distro>_base
297 adt_lvm_cowdatalv <nominum>_<distro>_cowdata
298 adt_lvm_snapbaselv <nominum>_<distro>_swapbase
299 adt_lvm_snapcowdatalv <nominum>_<distro>_swapcowdata
300 LVM volume for base filesystem image, and copy-on-write
301 buffer. Will be created during testbed setup, destroying any
302 previous volume if necessary. This is the logical volume name
303 not including /dev/<lvm_vg>.
305 adt_devmapper_cowdev <nominum>_<distro>_snap
306 adt_devmapper_swapcowdev <nominum>_<distro>_swapsnap
307 devmapper device for copy-on-write image used by testbed when
308 running. This is the device name in the devmapper namespace,
309 ie not including /dev/mapper.
311 adt_fslink_dir adt-xenlvm
312 adt_swaplink_dir adt-xenlvm
313 adt_fslink_name <nominum>_<distro>_fs
314 adt_swaplink_name <nominum>_<distro>_swap
315 Directory in /dev, and filename in that directory, where the
316 scripts put the symlink used to trick Xen into using a
317 different block device on resume than was used for creation.
319 adt_xmname <nominum>_<distro>
320 Xen virtual machine name, as passed to xm create.
322 adt_xmhook_disk <empty>
323 adt_xmhook_vif <empty>
324 adt_xmhook_extra <empty>
325 adt_xmhook_config <empty>
326 The values of these variables are inserted into the Xen domU
327 configuration file. _disk and _vif should contain zero or
328 more comma-prefixed double-quoted stanzas - they are
329 substituted inside the [ ] after the primary filesystem and
330 network devices set up by the adt-xenlvm tools. _extra
331 contains additional space-separated kernel command-line
332 options and is substituted inside the double-quotes. _config
333 should contain whole configuration lines. See