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 capabilities:

    + 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).

    + root-on-testbed
	Commands specified by `execute' will be run as root on the
	testbed, and copyup/copydown will have full access to the
	filesystem.  Unless this capability is advertised, root access
	is not (or may not be) available.

    + suggested-normal-user=<username>
	The caller is advised that <username> would be a good user to
	use for running tests (and doing other operations) when root
	is not required.  The advertised account will exist on the
	testbed already.  Several suggested-normal-user= capabilities
	(with distinct <username>s) may be advertised in which case
	more than one such user is available.


* 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
	revert

  Restores the testbed, undoing all of the changes made so far.
  State: Open, remains Open.  Only available if the `revert'
  capability is advertised.  If possible, the testbed's set of running
  processes will also be restored to the initial state.


* 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> \
		[<keyword-args> ...]
  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).

  Currently defined keyword arguments:

	debug=<tfd>-<hfd>

		Arranges to pass fd <tfd> the testbed command, and
		send all output to it to the fd <hfd> as passed
		by the virt server's caller.

		If this feature is available, execute-debug will
		be advertised.  Only one such plumbing is available.

		<tfd> may be 1 or 2, in which case no output will
		be written to the <stdout> or <stderr> files.

* 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)