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 caller is expected to url-decode program and each arg, append the command to be run on the testbed, and call execve() on the resulting argv list.
• That command might need to convert the argument list into a shell string with appropriate quoting if it implements the execute command with programs that take shell commands instead of argv lists, like ssh.
• The testbed program's stdin, stdout and stderr will be plumbed through to the stdin, stdout and stderr passed to program; this may involve fd passing, or indirection via pipes or sockets. The testbed program may not assume that the descriptors it receives are seekable even if the originals are.
• It is not defined whether other file descriptors, environment variables, and process properties in general, are inherited by the testbed command.
• program may exit as soon as the testbed command does, or it may wait until every copy of the stdout and stderr descriptors passed to the testbed command have been closed on the testbed.
• program's exit status will be that of the testbed command if the latter exits with a value from 0..125. If the testbed command dies due to a signal, then either (i) program will exit with the signal number with 128 added, or (ii) program will die with the same signal (although it may fail to dump core even if the testbed program did), or (iii) program will fail. If program fails it will exit 126, 127, 254, or 255; of course program may die to a some signals other than because the testbed program died with the same signal.
• The caller may run several of these at once, subject to limitation of resources (e. g. file descriptors or processes)
• The behaviour if a command is running when the testbed is closed or reverted is not defined. However, if the testbed advertises revert then after the testbed is closed or reverted any such program invocation will not have any further effect on the testbed.
• Sending program signals in an attempt to terminate it may not terminate all of the relevant processes and may not have any effect on the testbed.
• The behaviour if no testbed command is specified (i. e., if just the specified program and args is passed to exec) is not defined.
• Currently no keyword-infos are defined; they work the same way as capabilities in that unrecognised ones should be ignored by the caller.

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