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.
60 Note that there is NO LOCKING. If you run more than one of either
61 adt-xenlvm-with-testbed or adt-xenlvm-setup (or one of each)
62 simultaneously, the behaviour is not defined, except that the host
63 will definitely not be trashed, and just two or more copies of
64 adt-xenlvm-with-testbed at once has no bad effects that
65 adt-xenlvm-cleanup won't fix.
68 ========== Configuration ==========
70 The configuration is read as follows:
71 1. set all variables whose defaults are fixed strings to
72 those built-in default values
73 2. process the command line arguments
74 3. read the user configuration file (sourced by bash)
75 this file must not use fds 10 onwards, which may have been used
76 for other purposes by other adtxenlvm machinery
77 4. process the command line arguments again, so they
78 can easily be made to override the user configuration file
79 5. calculate the values for variables which haven't been set
80 and whose default values depend on circumstances (including
83 ---------- Items which definitely need attention ----------
85 adt_guests_domain .<domain-of-host_hostname>
86 adt_guest_hostname <distro>.[<nominum>.]<domain>
87 adt_guest_ipaddr from looking hostname up in the DNS
88 Hostname and IP address for the testbed.
89 If the configuration specifies one of the address and hostname
90 but not the other, the missing information will be found with
91 a DNS lookup. If neither is specified, adt_guests_domain is
92 used; if it starts with `.' then <distro>.<nominum> is
93 prepended; otherwise just <distro>. is prepended. NOTE: some
94 effort by the local network administrator to allocate an IP
95 address (and ideally create DNS entries) is essential. It is
96 not possible to use DHCP for IP address allocation for the
99 ---------- Firewall policy items ----------
101 adt_fw_localmirrors <none>
102 List of IP addresses of local mirrors, to which the
103 testbed should allowed to make HTTP requests.
105 adt_fw_testbedclients <host_ipaddr>
106 List of IP addresses of hosts which will be allowed to make
107 connections into the testbed system.
109 adt_fw_prohibnets 192.168.0.0/24 172.16.0.0/12 10.0.0.0/8
110 List of network ranges with which the testbed will be
111 prohibited from communicating, notwithstanding
114 adt_fw_allowglobalports <none>
115 List of ports to which the testbed will be allowed to make
116 outgoing connections.
118 adt_fw_hook <config> with _config replaced with _fwhook
119 or none if <config> doesn't end in _config
120 bash fragment to source during firewall setup
122 adt_sshauthkeys_hook <config> with _config replaced with _sshauthkeys
123 or none if <config> doesn't end in _config
124 list of authorized keys to append to testbed's
125 /root/.ssh/authorized_keys.
127 ---------- Items that are likely to need attention ----------
129 adt_kernel Xen kernel matching /boot/xen*`uname -r`
130 Kernel to boot in the testbed image
132 adt_ramdisk initrd.img-* where <kernel> is vmlinuz-*
133 Initial ramdisk to provide to the testbid image.
134 "none" means do not provide an initial ramdisk.
136 adt_modules /lib/modules/`uname -r`
137 Directory with modules to be copied into the testbed.
138 If this directory does not exist, no modules will be copied.
140 adt_lvm_vg the system's LVM volume group if there is only one
141 LVM volume group to create base filesystem image in.
143 adt_distro host system's distribution
144 Distribution name (eg, `edgy', `feisty', `sarge', `etch').
146 adt_pbuilder_args <none>
147 Extra arguments to pass to pbuilder.
149 adt_lvm_erasebase true
150 Whether the base filesystem image needs to be filled with
151 zeroes. If you are going to be using the image only locally
152 and so don't care whether the base image contains bits of
153 previous data from the disk, you may set this to `no'.
155 adt_debootstrap_includemore <empty>
156 adt_debootstrap_include libc6-xen,openssh-server,ed
157 Comma-separated lists of packages for --include option to
158 debootstrap. It is best to set includemore.
160 adt_debootstrap_components *
161 Components of the distribution to consider. (Eg, `main'.)
163 adt_debootstrap_mirrors <empty string>
164 adt_debootstrap_script <empty string>
165 Third and fourth arguments to debootstrap.
167 adt_setup_hook <config> with _config replaced with
168 _setuphook, as for adt_fw_hook
169 Program to run at last moment before we freeze the image.
170 Will be invoked with one argument: the directory containing
171 the root of the testbed. In the future more arguments may be
172 defined, so the hook script should not fail if more are
173 supplied. The supplied hook value will be split at
174 whitespace before execution as if
175 $adt_setup_hook /path/to/root
176 was run from within a shellscript.
178 ---------- Tuning parameters ----------
181 adt_fs_mkfs_args <none>
182 Filesystem type and any additional arguments to mkfs. If
183 _args contains whitespace, it results in multiple arguments;
184 it is not possible to pass whitespace-containing arguments to
187 adt_testbed_ram 256 [Mby]
188 Physical RAM allocated for each testbed instance while
189 creating and running.
191 adt_freeze_ram 32 [Mby]
192 Physical RAM size for frozen image; we reduce the testbed
193 to this before freezing it and grow it again when we resume
197 Size of base filesystem image. Should be big enough to
198 contain all of the software under test and all of its working
199 space, as no running testbed can ever use more than this
200 (despite copy-on-write).
203 Space to allocate for copy-on-write snapshot data. This is
204 the maximum amount of data that a running testbed can use.
205 This value should be less than the adt_fs_size.
207 adt_fs_cowchunk 8 [Mby]
208 Copy-on-write chunk size.
210 adt_vm_reduce_retries 10 [seconds]
211 Time to wait for VM to reduce its memory following
214 ---------- Configuration for advanced uses ----------
216 adt_config /etc/autopkgtest/xenlvm_<nominum>_conf
219 adt_ssh_privkey /root/.ssh/id_<ssh_keytype>_<nominum>
220 adt_ssh_pubkey <ssh_privkey>.pub
221 adt_ssh_keyident_args -i <ssh_privkey>
222 adt_ssh_keygen_args -t <ssh_keytype>
223 SSH keypair to use for authentication to the testbed.
224 If the pubkey file and privkey file do not exist and
225 correspond to each other, a new key will be generated.
226 The best combinations of these variables to set are:
227 keytype [& keygen_args] - just change the key type
228 privkey [& keygen_args] - generate/use a different keypair
229 pubkey, keyident_args - use an existing key via agent etc.,
230 privkey is ignored if pubkey and keyident_args
231 are set and pubkey file exists
234 Namespace prefix for Xen domains, LVM volumes, devmapper
235 devices, entries in /dev, files in /var, and so on. You may
236 run several instances of the adt virtualisation system with
237 different nominums and they won't interact. It is best for
238 this to be a legal DNS label (using alphanumerics and hyphens
239 only); normally it when it is used to construct an identifier
240 it will be separated by other parts by underscores `_', so
241 they should be avoided.
243 adt_guest_macaddr 00:16:3e:7c:aa:7f
244 adt_net_vifscript /etc/xen/scripts/vif-route-adt
246 adt_normaluser adtxenu
247 Create a normal user account of this name, with disabled
250 ---------- Items which should not usually need to be changed ----------
252 adt_host_hostname `hostname -f`
253 adt_host_ipaddr from looking hostname up in the DNS
254 Hostname and IP address for the host, ie the Xen dom0 system.
255 If the configuration specifies one of the address and hostname
256 but not the other, the missing information will be found with
257 a DNS lookup. Note that if the host system uses a dynamically
258 allocated DHCP address, things will go wrong when the address
261 adt_playbase /var/lib/autopkgtest/xenlvm
262 Base of filesystem playground areas.
264 adt_play <playbase>/<nominum>_<distro>
265 Playground area for this particular testbed construction and
268 adt_xmconfig <play>/xmconfig
269 Xen virtual machine creation configuration for xm create.
270 This file will be (over)written during testbed setup.
272 adt_lvm_baselv <nominum>_<distro>_base
273 adt_lvm_cowdatalv <nominum>_<distro>_cowdata
274 LVM volume for base filesystem image, and copy-on-write
275 buffer. Will be created during testbed setup, destroying any
276 previous volume if necessary. This is the logical volume name
277 not including /dev/<lvm_vg>.
279 adt_devmapper_cowdev <nominum>_<distro>_snap
280 devmapper device for copy-on-write image used by testbed when
281 running. This is the device name in the devmapper namespace,
282 ie not including /dev/mapper.
284 adt_fslink_dir adt-xenlvm
285 adt_fslink_name <nominum>_<distro>_fs
286 Directory in /dev, and filename in that directory, where the
287 scripts put the symlink used to trick Xen into using a
288 different block device on resume than was used for creation.
290 adt_xmname <nominum>_<distro>
291 Xen virtual machine name, as passed to xm create.