doc/README.virtualisation-server

   1 AUTOPKGTEST VIRTUALISATION SERVICE INTERFACE
   2 ============================================
   3
   4 The virtualisation regime provides a single executable program which
   5 is used by the tester core to request virtualisation facilities.
   6
   7 The server has the following states:
   8
   9   * Closed: there is no particular testbed. This is the initial state.
  10
  11   * Open: the testbed is running and can be communicated with (and, if
  12     applicable, is not being used by any other concurrent test run)
  13
  14 Note that these are the states of the server, in the tester core to
  15 server protocol.  The actual testbed will probably have more states,
  16 including for example Closed, Open (and therefore busy), Modified,
  17 Broken, etc.  Ideally the virtualisation regime will prevent multiple
  18 concurrent uses of the same testbed; the tester core is allowed to
  19 assume that either its caller or the virtualisation regime will ensure
  20 that it has exclusive use of the testbed.
  21
  22 The server program is invoked with the argument
  23 --debian-package-testing and then proceeds to speak a protocol on its
  24 stdin/stdout.  The protocol is line-based.  In the future other ways
  25 of invoking the server may be defined; the current server should of
  26 course reject such invocations.
  27
  28
  29 Protocol
  30 --------
  31
  32 * Initial response from regime server:
  33         ok
  34   This response is also the response from any of the commands listed
  35   below, unless otherwise specified.
  36
  37
  38 * Command
  39         capabilities
  40   response, for example
  41         ok gnomovision-server revert ...
  42   where the words after ok are features that not all regimes
  43   support.  Valid in all states.
  44
  45   Currently defined capabilities:
  46
  47     + revert
  48         The "revert" command is supported.  The base semantics
  49         are that the following aspects of the testbed are reverted:
  50                 - the set of installed packages
  51                 - the contents of the root filesystem, BUT
  52                 - NOT the contents of /home
  53                 - NOT the contents of /tmp
  54                 - NOT the set of running processes
  55
  56     + revert-full-system
  57         The "revert" and "close" commands will completely revert the
  58         testbed to the state after "open".  This reversion is done
  59         with some kind of virtualisation, and includes (without
  60         limitation) the contents of all the testbed filesystems, its
  61         running processes, network configuration, etc. etc. etc.
  62
  63     + revert
  64         The testbed will actually revert when it is closed.  If this
  65         feature is not mentioned then changes to the testbed are
  66         persistent (so destructive tests should not be performed).
  67
  68     + root-on-testbed
  69         Commands specified by `execute' will be run as root on the
  70         testbed, and copyup/copydown will have full access to the
  71         filesystem.  Unless this capability is advertised, root access
  72         is not (or may not be) available.
  73
  74     + suggested-normal-user=<username>
  75         The caller is advised that <username> would be a good user to
  76         use for running tests (and doing other operations) when root
  77         is not required.  The advertised account will exist on the
  78         testbed already.  Several suggested-normal-user= capabilities
  79         (with distinct <username>s) may be advertised in which case
  80         more than one such user is available.
  81
  82
  83 * Command
  84         open
  85   response
  86         ok <testbed-scratchspace>
  87
  88   Checks that the testbed is present and reserves it (waiting for
  89   other uses of the testbed to finish first, if necessary).  State:
  90   Closed to Open.  <testbed-scratchspace> is a pathname on the
  91   testbed which can be used freely by the test scripts and which
  92   is valid until the next `close', `revert' or `quit'.
  93
  94
  95 * Command
  96         revert
  97   response
  98         ok <testbed-scratchspace>
  99
 100   Restores the testbed, undoing all of the changes made so far.
 101   State: Open, remains Open.  Only available if the `revert'
 102   capability is advertised.  If possible, the testbed's set of running
 103   processes will also be restored to the initial state.
 104
 105
 106 * Command
 107         close
 108
 109   Stops the testbed and undoes filesystem changes (if `revert' is
 110   advertised). State: Open to Closed.
 111
 112
 113 * Commands
 114         print-auxverb-command
 115         print-shstring-command
 116   response
 117         ok <program>,<arg>,<arg>... [<keyword-info> ...]
 118   Prints a command that can be executed by the caller to run a command
 119   on the testbed.
 120
 121   The command has the following properties (which are, for example,
 122   satisfiable when the virt server uses `env' `ssh' or `dchroot'):
 123    - The caller is expected to url-decode <program> and each <arg>,
 124      append the command to be run on the testbed, and call exec on the
 125      results.
 126    - For the command provided by `print-auxverb-command', the supplied
 127      additional arguments to command will be interpreted as the
 128      command and arguments to be run on the testbed (as env and nice
 129      interpret their arguments)
 130    - The command provided by `print-shstring-command', should be
 131      invoked with exactly one additional argument which should be a
 132      legal shell script.  It will be fed to sh -c on the testbed (this
 133      is the way ssh interprets its arguments).
 134    - The testbed program's stdin, stdout and stderr will be plumbed
 135      through to the stdin, stdout and stderr passed to <program>; this
 136      may involve fd passing, or indirection via pipes or sockets.  The
 137      testbed program may not assume that the descriptors it receives
 138      are seekable even if the originals are.
 139    - It is not defined whether other file descriptors, environment
 140      variables, and process properties in general, are inherited by
 141      the testbed command.
 142    - <program> may exit as soon as the testbed command does, or it may
 143      wait until every copy of the stdout and stderr descriptors passed
 144      to the testbed command have been closed on the testbed.
 145    - <program>'s exit status will be that of the testbed command if
 146      the latter exits with a value from 0..125.  If the testbed
 147      command dies due to a signal, then either (i) <program> will exit
 148      with the signal number with 128 added, or (ii) <program> will die
 149      with the same signal (although it may fail to dump core even if
 150      the testbed program did), or (iii) <program> will fail.  If
 151      <program> fails it will exit 126, 127, 254, or 255; of course
 152      <program> may die to a some signals other than because the
 153      testbed program died with the same signal.
 154    - The caller may run several of these at once, subject to
 155      limitation of resources (eg, file descriptors, processes)
 156    - The behaviour if a command is running when the testbed is closed
 157      or reverted is not defined.  However, if the testbed advertises
 158      `revert' then after the testbed is closed or reverted any such
 159      <program> invocation will not have any further effect on the
 160      testbed.
 161    - Sending <program> signals in an attempt to terminate it may not
 162      terminate all of the relevant processes and may not have any
 163      effect on the testbed.
 164    - The behaviour if no testbed command is specified (ie, if
 165      just the specified <program> and <arg>s is passed to exec) is
 166      not defined.
 167    - Currently no <keyword-info>s are defined; they work the same
 168      way as capabilities in that unrecognised ones should be ignored
 169      by the caller.
 170   The response (ie, the <command>) is only valid between `open' and
 171   the next subsequent `close', `revert' or `quit'.  Using it at other
 172   times has undefined behaviour.
 173
 174
 175 * Command
 176         execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
 177                 [<keyword-args> ...]
 178   response
 179         ok <exit-status>
 180
 181   Executes the command (args separated by commas, everything including
 182   filenames and env var names and values url-encoded).  stdin, stdout,
 183   stderr are files on the testbed (must be files, not pipes).
 184
 185   Currently defined keyword arguments:
 186
 187         env=<var>=<value>
 188
 189                 Sets the environment variable <var> to <value>.
 190
 191         debug=<tfd>-<hfd>
 192
 193                 Arranges to pass fd <tfd> the testbed command, and
 194                 send all output to it to the fd <hfd> as passed
 195                 by the virt server's caller.
 196
 197                 <tfd> may be 1 or 2, in which case no output will
 198                 be written to the <stdout> or <stderr> files.
 199
 200                 If this feature is available, execute-debug will
 201                 be advertised.  Only one such plumbing is available.
 202
 203         timeout=<seconds>
 204
 205                 Ensures that the whole execute command does not take
 206                 more than <seconds>.  If it does, the response is
 207                         timeout
 208                 instead of `ok <exit-status>'.
 209
 210                 An effort will be made to kill the processes on the
 211                 testbed but this is not guaranteed to be possible or
 212                 successful.  After an `execute' has timed out, the
 213                 testbed should probably be reverted with `revert' if
 214                 that facility is available.
 215
 216 * Commands
 217         copydown <host-path> <testbed-path>
 218         copyup <testbed-path> <host-path>
 219
 220   Either
 221
 222   1. Both paths end in `/', in which case the source must be an
 223      existing directory.  The destination directory is replaced with a
 224      copy as if made by cp -dR --preserve=mode,timestamps except
 225      across the testbed boundary.
 226
 227   2. Neither path ends in `/', in which case the source must be an
 228      existing file.  The data from the source file is written to the
 229      destination as if via shell redirection; except that if for
 230      copydown of an executable file, `chmod +x' is run on the
 231      destination file after the copy.
 232
 233   Both filenames are url-encoded.
 234
 235
 236 * Command
 237         quit
 238   response
 239         ok
 240   and then the regime server exits with status 0, after
 241   closing the testbed if applicable.
 242
 243
 244
 245
 246 On any error including signals to the regime server or EOF on stdin
 247 the testbed is unreserved and restored to its original state (ie,
 248 closed), and the regime server will print a message to stderr (unless
 249 it is dying with a signal).