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 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.
  66
  67
  68 ========== Configuration ==========
  69
  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
  81      on other variables)
  82
  83 ---------- Items which definitely need attention ----------
  84
  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
  97         testbed.
  98
  99 ---------- Firewall policy items ----------
 100
 101 adt_fw_localmirrors     <none>
 102         List of IP addresses of local mirrors, to which the
 103         testbed should allowed to make HTTP requests.
 104
 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.
 108
 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
 112         allowglobalports.
 113
 114 adt_fw_allowglobalports <none>
 115         List of ports to which the testbed will be allowed to make
 116         outgoing connections.
 117
 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
 121
 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.
 126
 127 ---------- Items that are likely to need attention ----------
 128
 129 adt_kernel              Xen kernel matching /boot/xen*`uname -r`
 130         Kernel to boot in the testbed image
 131
 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.
 135
 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.
 139
 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.
 142
 143 adt_distro              host system's distribution
 144         Distribution name (eg, `edgy', `feisty', `sarge', `etch').
 145
 146 adt_pbuilder_args       <none>
 147         Extra arguments to pass to pbuilder.
 148
 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'.
 154
 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.
 159
 160 adt_debootstrap_components      *
 161         Components of the distribution to consider.  (Eg, `main'.)
 162
 163 adt_debootstrap_mirrors         <empty string>
 164 adt_debootstrap_script          <empty string>
 165         Third and fourth arguments to debootstrap.
 166
 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.
 177
 178 ---------- Tuning parameters ----------
 179
 180 adt_fs_type             ext3
 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
 185         mkfs.
 186
 187 adt_testbed_ram         256 [Mby]
 188         Physical RAM allocated for each testbed instance while
 189         creating and running.
 190
 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
 194         it.
 195
 196 adt_fs_size             1G
 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).
 201
 202 adt_fs_snapsize         500M
 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.
 206
 207 adt_fs_cowchunk         8 [Mby]
 208         Copy-on-write chunk size.
 209
 210 adt_vm_reduce_retries   10 [seconds]
 211         Time to wait for VM to reduce its memory following
 212         xm mem-set.
 213
 214 ---------- Configuration for advanced uses ----------
 215
 216 adt_config              /etc/autopkgtest/xenlvm_<nominum>_conf
 217
 218 adt_ssh_keytype         dsa
 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
 232
 233 adt_nominum             adt
 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.
 242
 243 adt_guest_macaddr       00:16:3e:7c:aa:7f
 244 adt_net_vifscript       /etc/xen/scripts/vif-route-adt
 245
 246 adt_normaluser          adtxenu
 247         Create a normal user account of this name, with disabled
 248         password.
 249
 250 ---------- Items which should not usually need to be changed ----------
 251
 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
 259         changes.
 260
 261 adt_playbase            /var/lib/autopkgtest/xenlvm
 262         Base of filesystem playground areas.
 263
 264 adt_play                <playbase>/<nominum>_<distro>
 265         Playground area for this particular testbed construction and
 266         data.
 267
 268 adt_xmconfig            <play>/xmconfig
 269         Xen virtual machine creation configuration for xm create.
 270         This file will be (over)written during testbed setup.
 271
 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>.
 278
 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.
 283
 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.
 289
 290 adt_xmname              <nominum>_<distro>
 291         Xen virtual machine name, as passed to xm create.