xen/README

   1 ========== Introduction ==========
   2
   3 Basic approach:
   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
  12     3. adt-xenlvm-setup
  13     4. adt-xenlvm-with-testbed
  14     5. adt-xenlvm-on-testbed
  15
  16 In some more detail, there are four main programs provided:
  17
  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.
  27
  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.
  33
  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.
  41
  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.
  48
  49   adt-xenlvm-purge [<config settings>]
  50         Deletes all of the data for the testbed.  Ie, undoes
  51         the effects of adt-xenlvm-setup.
  52
  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.
  59
  60
  61
  62 ========== Configuration ==========
  63
  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
  75      on other variables)
  76
  77 ---------- Items which definitely need attention ----------
  78
  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
  91         testbed.
  92
  93 ---------- Firewall policy items ----------
  94
  95 adt_fw_localmirrors     <none>
  96         List of IP addresses of local mirrors, to which the
  97         testbed should allowed to make HTTP requests.
  98
  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.
 102
 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
 106         allowglobalports.
 107
 108 adt_fw_allowglobalports <none>
 109         List of ports to which the testbed will be allowed to make
 110         outgoing connections.
 111
 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
 115
 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.
 120
 121 ---------- Items that are likely to need attention ----------
 122
 123 adt_kernel              Xen kernel matching /boot/xen*`uname -r`
 124         Kernel to boot in the testbed image
 125
 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.
 129
 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.
 133
 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.
 136
 137 adt_distro              host system's distribution
 138         Distribution name (eg, `edgy', `feisty', `sarge', `etch').
 139
 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'.
 145
 146 adt_debootstrap_opts    <none>
 147         Extra options to pass to debootstrap.
 148
 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.
 153
 154 adt_debootstrap_components      *
 155         Components of the distribution to consider.  (Eg, `main'.)
 156
 157 adt_debootstrap_mirrors         <empty string>
 158 adt_debootstrap_script          <empty string>
 159         Third and fourth arguments to debootstrap.
 160
 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.
 171
 172 ---------- Tuning parameters ----------
 173
 174 adt_fs_type             ext3
 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
 179         mkfs.
 180
 181 adt_testbed_ram         256 [Mby]
 182         Physical RAM allocated for each testbed instance while
 183         creating and running.
 184
 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
 188         it.
 189
 190 adt_fs_size             6144M
 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).
 195
 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.
 200
 201 adt_fs_cowchunk         8 [Mby]
 202         Copy-on-write chunk size.
 203
 204 adt_swap_size           5120M
 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.
 208
 209 adt_swap_cowchunk       <fs_cowchunk>
 210         Copy-on-write chunk size for swap area.
 211
 212 adt_vm_reduce_retries   10 [seconds]
 213         Time to wait for VM to reduce its memory following
 214         xm mem-set.
 215
 216 ---------- Configuration for advanced uses ----------
 217
 218 adt_config              /etc/autopkgtest/xenlvm_<nominum>_conf
 219
 220 adt_ssh_keytype         dsa
 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
 234
 235 adt_nominum             adt
 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.
 244
 245 adt_lvm_swapvg          <lvm_vg>
 246         VG to use for guest's swap.
 247
 248 adt_lvm_eraseswap       <lvm_erasebase>
 249         Whether the base swap image needs to be filled with zeroes.
 250
 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
 256         up to lvcreate.
 257
 258 adt_guest_macaddr       00:16:3e:7c:aa:7f
 259 adt_net_vifscript       /etc/xen/scripts/vif-route-adt
 260
 261 adt_normaluser          adtxenu
 262         Create a normal user account of this name, with disabled
 263         password.
 264
 265 ---------- Items which should not usually need to be changed ----------
 266
 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
 274         changes.
 275
 276 adt_playbase            /var/lib/autopkgtest/xenlvm
 277         Base of filesystem playground areas.
 278
 279 adt_play                <playbase>/<nominum>_<distro>
 280         Playground area for this particular testbed construction and
 281         data.
 282
 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
 290         lock continuously.
 291
 292 adt_xmconfig            <play>/xmconfig
 293         Xen virtual machine creation configuration for xm create.
 294         This file will be (over)written during testbed setup.
 295
 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>.
 304
 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.
 310
 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.
 318
 319 adt_xmname              <nominum>_<distro>
 320         Xen virtual machine name, as passed to xm create.
 321
 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
 334         xmdomain.cfg(5).