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         debug=<tfd>-<hfd>
 107
 108                 Arranges to pass fd <tfd> the testbed command, and
 109                 send all output to it to the fd <hfd> as passed
 110                 by the virt server's caller.
 111
 112                 If this feature is available, execute-debug will
 113                 be advertised.  Only one such plumbing is available.
 114
 115                 <tfd> may be 1 or 2, in which case no output will
 116                 be written to the <stdout> or <stderr> files.
 117
 118 * Commands
 119         copydown <host-tree> <testbed-path>
 120         copyup <testbed-tree> <host-path>
 121
 122   Like cp -dR --preserve=mode,timestamps exce[t across the testbed
 123   boundary.
 124
 125
 126 * Command
 127         quit
 128   response
 129         ok
 130   and then the regime server exits with status 0, after
 131   closing the testbed if applicable.
 132
 133
 134
 135
 136 On any error including signals to the regime server or EOF on stdin
 137 the testbed is unreserved and restored to its original state (ie,
 138 closed), and the regime server will print a message to stderr (unless
 139 it is dying with a signal).
 140
 141 The representation of changes to the local filesystem is a directory
 142 containing zero or more of:
 143         + changed-files: list of filenames, each one nul-terminated
 144         + other formats with other data or combinations of data
 145           (for future use)
 146