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
  67 * Command
  68         open
  69   response
  70         ok <testbed-scratchspace>
  71
  72   Checks that the testbed is present and reserves it (waiting for
  73   other uses of the testbed to finish first, if necessary).  State:
  74   Closed to Open.  <testbed-scratchspace> is a pathname on the
  75   testbed which can be used freely by the test scripts.
  76
  77
  78 * Command
  79         revert
  80
  81   Restores the testbed, undoing all of the changes made so far.
  82   State: Open, remains Open.  Only available if the `revert'
  83   capability is advertised.  If possible, the testbed's set of running
  84   processes will also be restored to the initial state.
  85
  86
  87 * Command
  88         close
  89
  90   Stops the testbed and undoes filesystem changes (if `revert' is
  91   advertised). State: Open to Closed.
  92
  93
  94 * Command
  95         execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
  96                 [<keyword-args> ...]
  97   response
  98         ok <exit-status>
  99
 100   Executes the command (args separated by commas, everything
 101   url-encoded).  stdin, stdout, stderr are files on the testbed
 102   (must be files, not pipes).
 103
 104   Currently defined keyword arguments:
 105
 106         env=<var>=<value>
 107
 108                 Sets the environment variable <var> to <value>.
 109
 110         debug=<tfd>-<hfd>
 111
 112                 Arranges to pass fd <tfd> the testbed command, and
 113                 send all output to it to the fd <hfd> as passed
 114                 by the virt server's caller.
 115
 116                 <tfd> may be 1 or 2, in which case no output will
 117                 be written to the <stdout> or <stderr> files.
 118
 119                 If this feature is available, execute-debug will
 120                 be advertised.  Only one such plumbing is available.
 121
 122         timeout=<seconds>
 123
 124                 Ensures that the whole execute command does not take
 125                 more than <seconds>.  If it does, the response is
 126                         timeout
 127                 instead of `ok <exit-status>'.
 128
 129                 An effort will be made to kill the processes on the
 130                 testbed but this is not guaranteed to be possible or
 131                 successful.  After an `execute' has timed out, the
 132                 testbed should probably be reverted with `revert' if
 133                 that facility is available.
 134
 135 * Commands
 136         copydown <host-tree> <testbed-path>
 137         copyup <testbed-tree> <host-path>
 138
 139   Like cp -dR --preserve=mode,timestamps exce[t across the testbed
 140   boundary.
 141
 142
 143 * Command
 144         quit
 145   response
 146         ok
 147   and then the regime server exits with status 0, after
 148   closing the testbed if applicable.
 149
 150
 151
 152
 153 On any error including signals to the regime server or EOF on stdin
 154 the testbed is unreserved and restored to its original state (ie,
 155 closed), and the regime server will print a message to stderr (unless
 156 it is dying with a signal).
 157
 158 The representation of changes to the local filesystem is a directory
 159 containing zero or more of:
 160         + changed-files: list of filenames, each one nul-terminated
 161         + other formats with other data or combinations of data
 162           (for future use)
 163