Autopkgtest Virtualisation Service Interface

The virtualisation server 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 server will prevent multiple concurrent uses of the same testbed; the tester core is allowed to assume that either its caller or the virtualisation server will ensure that it has exclusive use of the testbed.

The server program speaks 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.

Initial response from virtualization server after starting is ok. This response is also the response from any of the commands listed below, unless otherwise specified.

Command: capabilities

Response, for example:

ok gnomovision-server revert ...

where the words after ok are features that not all servers support. Valid in all states.

Currently defined capabilities:

revert

The revert command is supported. The base semantics are that the following aspects of the testbed are reverted:

  • the set of installed packages
  • the contents of the root filesystem, BUT
  • not the contents of /home
  • not the contents of /tmp
  • not the set of running processes

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

revert-full-system
The revert and close commands will completely revert the testbed to the state after open. This reversion is done with some kind of virtualisation, and includes (without limitation) the contents of all the testbed filesystems, its running processes, network configuration, etc.
reboot
The testbed supports (re)booting, to pick up updated kernels and/or init system scripts, e. g. from --setup-commands.
root-on-testbed
Commands run through print-execute-command 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 user names) may be advertised in which case more than one such user is available.
downtmp-host=path
If the testbed has the ability of setting up a shared directory with the host, this gives the host directory path of the "downtmp" directory as reported by the virt server's hook_downtmp() function. This makes copying files in and out much more efficient.
isolation-container
The testbed runs in a Linux cgroup/container (nspawn, LXC, docker, etc.) and thus tests have full control over starting services and opening network ports.
isolation-machine
The testbed runs in a complete (virtual or real) machine on its own (qemu or bare metal) and thus tests have full control over starting services, opening network ports, interacting with the kernel (e. g. modprobe), rebooting, and accessing hardware.

Command: open

Response:

ok testbed-scratchspace

State: Closed to Open

Checks that the testbed is present and reserves it (waiting for other uses of the testbed to finish first, if necessary). testbed-scratchspace is a pathname on the testbed which can be used freely by the test scripts and which is valid until the next close, revert, or quit.

Command: revert

Response:

ok testbed-scratchspace

State: Open, remains Open

Restores the testbed, undoing all of the changes made so far. 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: reboot

Response:

ok testbed-scratchspace

State: Open, remains Open

Reboots the testbed, without reverting any changes to the files. Only available if the reboot capability is advertised.

Command: close

Response:

ok

State: Open to Closed

Stops the testbed and undoes filesystem changes (if revert is advertised).

Command: print-execute-command

Response:

ok program,arg,arg... [keyword-info ...]

Prints a command that can be executed by the caller to run a command on the testbed.

The program has the following properties:

The response is only valid between open and the next subsequent close, revert or quit. Using it at other times has undefined behaviour.

Commands: copyup/copydown

Command:

copydown host-path testbed-path
copyup testbed-path host-path

Response:

ok

Either

  1. Both paths end in /, in which case the source must be an existing directory.
  2. Neither path ends in /, in which case the source must be an existing file.

Both filenames are URL-encoded.

Command: quit

Reponse:

ok

The server exits with status 0, after closing the testbed if applicable.

Command: shell

Response: one of

ok
not supported by virt server

Runs a shell in the testbed (as root, if available), while the testbed is open. This is intended for interactively debugging problems with tests. The virt server has to provide a hook_shell() function for this, otherwise this command is not supported.

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