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