AUTOPKGTEST VIRTUALISATION SERVICE INTERFACE
============================================

The virtualisation regime provides a single executable program which
is used by the tester core to request virtualisation facilities.

The server has the following states:

  * Closed: there is no particular testbed. This is the initial state.

  * Open: the testbed is running and can be communicated with (and, if
    applicable, is not being used by any other concurrent test run)

Note that these are the states of the server, in the tester core to
server protocol.  The actual testbed will probably have more states,
including for example Closed, Open (and therefore busy), Modified,
Broken, etc.  Ideally the virtualisation regime will prevent multiple
concurrent uses of the same testbed; the tester core is allowed to
assume that either its caller or the virtualisation regime will ensure
that it has exclusive use of the testbed.

The server program is invoked with the argument
--debian-package-testing and then proceeds to speak a protocol on its
stdin/stdout.  The protocol is line-based.  In the future other ways
of invoking the server may be defined; the current server should of
course reject such invocations.


Protocol
--------

* Initial response from regime server:
	ok
  This response is also the response from any of the commands listed
  below, unless otherwise specified.


* Command
	capabilities
  response, for example
	ok efficient-diff revert ...
  where the words after ok are features that not all regimes
  support.  Valid in all states.

  Currently defined features:

    + revert: the testbed will actually revert when it is closed.
      If this feature is not mentioned then changes to the testbed
      are persistent (so destructive tests should not be performed).

    + changed-files: the regime will provide a changed-files file
      (see below).


* Command
	open
  response
	ok <testbed-scratchspace>

  Checks that the testbed is present and reserves it (waiting for
  other uses of the testbed to finish first, if necessary).  State:
  Closed to Open.  <testbed-scratchspace> is a pathname on the
  testbed which can be used freely by the test scripts.


* Command
	stop <local-pathname>

  Stops the testbed.  Replaces local-pathname (on the host) with a
  directory containing a representation of the changes to the
  testbed's filesystem; these changes are undone (if `revert' was
  advertised).  Then reverts the testbed.  State: Open to Closed.


* Command
	close

  Stops the testbed and undoes filesystem changes (if `revert' is
  advertised). State: Open to Closed.


* Command
	execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd>
  response
	ok <exit-status>

  Executes the command (args separated by commas, everything
  url-encoded).  stdin, stdout, stderr are files on the testbed
  (must be files, not pipes).


* Commands
	copydown <host-tree> <testbed-path>
	copyup <testbed-tree> <host-path>

  Like cp -dR --preserve=mode,timestamps exce[t across the testbed
  boundary.


* Command
	quit
  response
	ok
  and then the regime server exits with status 0, after
  closing the testbed if applicable.




On any error including signals to the regime server or EOF on stdin
the testbed is unreserved and restored to its original state (ie,
closed), and the regime server will print a message to stderr (unless
it is dying with a signal).

The representation of changes to the local filesystem is a directory
containing zero or more of:
	+ changed-files: list of filenames, each one nul-terminated
	+ other formats with other data or combinations of data
	  (for future use)