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 efficient-diff 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 testbed will actually revert when it is closed.  If this
  49         feature is not mentioned then changes to the testbed are
  50         persistent (so destructive tests should not be performed).
  51
  52     + root-on-testbed
  53         Commands specified by `execute' will be run as root on the
  54         testbed, and copyup/copydown will have full access to the
  55         filesystem.  Unless this capability is advertised, root access
  56         is not (or may not be) available.
  57
  58     + suggested-normal-user=<username>
  59         The caller is advised that <username> would be a good user to
  60         use for running tests (and doing other operations) when root
  61         is not required.  The advertised account will exist on the
  62         testbed already.  Several suggested-normal-user= capabilities
  63         (with distinct <username>s) may be advertised in which case
  64         more than one such user is available.
  65
  66    + print-execute-command
  67         The 'print-execute-command' command is available, so that the
  68         caller can execute multiple concurrent commands on the testbed
  69         with asynchronous input and output, if desired.
  70
  71
  72 * Command
  73         open
  74   response
  75         ok <testbed-scratchspace>
  76
  77   Checks that the testbed is present and reserves it (waiting for
  78   other uses of the testbed to finish first, if necessary).  State:
  79   Closed to Open.  <testbed-scratchspace> is a pathname on the
  80   testbed which can be used freely by the test scripts.
  81
  82
  83 * Command
  84         revert
  85
  86   Restores the testbed, undoing all of the changes made so far.
  87   State: Open, remains Open.  Only available if the `revert'
  88   capability is advertised.  If possible, the testbed's set of running
  89   processes will also be restored to the initial state.
  90
  91
  92 * Command
  93         close
  94
  95   Stops the testbed and undoes filesystem changes (if `revert' is
  96   advertised). State: Open to Closed.
  97
  98
  99 * Command
 100         print-execute-command
 101   response
 102         ok <program>,<arg>,<arg>... auxverb|shstring [<keyword-info> ...]
 103   Prints a command that can be executed by the caller to run a command
 104   on the testbed.  Only available if the `print-execute-command'
 105   capability is advertised.
 106
 107   The command has the following properties (which are, for example,
 108   satisfiable when the virt server uses `env' `ssh' or `dchroot'):
 109    - The caller is expected to url-decode <program> and each <arg>,
 110      append the command to be run on the testbed, and call exec on the
 111      results.
 112    - If auxverb is advertised, the supplied additional arguments to
 113      command will be interpreted as the command and arguments to be
 114      run on the testbed (as env and nice interpret their arguments)
 115    - If shstring is advertised, there should be one additional
 116      argument which will be fed to sh -c on the testbed (this is the
 117      way ssh interprets its arguments).
 118    - The testbed program's stdin, stdout and stderr will be plumbed
 119      through to the stdin, stdout and stderr passed to <program>; this
 120      may involve fd passing, or indirection via pipes or sockets.  The
 121      testbed program may not assume that the descriptors it receives
 122      are seekable even if the originals are.
 123    - It is not defined whether other file descriptors, environment
 124      variables, and process properties in general, are inherited by
 125      the testbed command.
 126    - <program> may exit as soon as the testbed command does, or it may
 127      wait until every copy of the stdout and stderr descriptors passed
 128      to the testbed command have been closed on the testbed.
 129    - <program>'s exit status will be that of the testbed command if
 130      the latter exits with a value from 0..125.  If the testbed
 131      command dies due to a signal, then either (i) <program> will exit
 132      with the signal number with 128 added, or (ii) <program> will die
 133      with the same signal (although it may fail to dump core even if
 134      the testbed program did), or (iii) <program> will fail.  If
 135      <program> fails it will exit 126, 127, 254, or 255; of course
 136      <program> may die to a some signals other than because the
 137      testbed program died with the same signal.
 138    - The caller may run several of these at once, subject to
 139      limitation of resources (eg, file descriptors, processes)
 140    - The behaviour if a command is running when the testbed is closed
 141      or reverted is not defined.  However, if the testbed advertises
 142      `revert' then after the testbed is closed or reverted any such
 143      <program> invocation will not have any further effect on the
 144      testbed.
 145    - Sending <program> signals in an attempt to terminate it may not
 146      terminate all of the relevant processes and may not have any
 147      effect on the testbed.
 148    - The behaviour if no testbed command is specified (ie, if
 149      just the specified <program> and <arg>s is passed to exec) is
 150      not defined.
 151    - Currently no <keyword-info>s are defined; they work the same
 152      way as capabilities in that unrecognised ones should be ignored
 153      by the caller.
 154   The response (ie, the <command>) is only valid between `open' and
 155   the next subsequent `close', `revert' or `quit'.  Using it at other
 156   times has undefined behaviour.
 157
 158
 159 * Command
 160         execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
 161                 [<keyword-args> ...]
 162   response
 163         ok <exit-status>
 164
 165   Executes the command (args separated by commas, everything
 166   url-encoded).  stdin, stdout, stderr are files on the testbed
 167   (must be files, not pipes).
 168
 169   Currently defined keyword arguments:
 170
 171         env=<var>=<value>
 172
 173                 Sets the environment variable <var> to <value>.
 174
 175         debug=<tfd>-<hfd>
 176
 177                 Arranges to pass fd <tfd> the testbed command, and
 178                 send all output to it to the fd <hfd> as passed
 179                 by the virt server's caller.
 180
 181                 <tfd> may be 1 or 2, in which case no output will
 182                 be written to the <stdout> or <stderr> files.
 183
 184                 If this feature is available, execute-debug will
 185                 be advertised.  Only one such plumbing is available.
 186
 187         timeout=<seconds>
 188
 189                 Ensures that the whole execute command does not take
 190                 more than <seconds>.  If it does, the response is
 191                         timeout
 192                 instead of `ok <exit-status>'.
 193
 194                 An effort will be made to kill the processes on the
 195                 testbed but this is not guaranteed to be possible or
 196                 successful.  After an `execute' has timed out, the
 197                 testbed should probably be reverted with `revert' if
 198                 that facility is available.
 199
 200 * Commands
 201         copydown <host-tree> <testbed-path>
 202         copyup <testbed-tree> <host-path>
 203
 204   Like cp -dR --preserve=mode,timestamps exce[t across the testbed
 205   boundary.
 206
 207
 208 * Command
 209         quit
 210   response
 211         ok
 212   and then the regime server exits with status 0, after
 213   closing the testbed if applicable.
 214
 215
 216
 217
 218 On any error including signals to the regime server or EOF on stdin
 219 the testbed is unreserved and restored to its original state (ie,
 220 closed), and the regime server will print a message to stderr (unless
 221 it is dying with a signal).
 222
 223 The representation of changes to the local filesystem is a directory
 224 containing zero or more of:
 225         + changed-files: list of filenames, each one nul-terminated
 226         + other formats with other data or combinations of data
 227           (for future use)
 228