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= The caller is advised that 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 s) may be advertised in which case more than one such user is available. + print-execute-command The 'print-execute-command' command is available, so that the caller can execute multiple concurrent commands on the testbed with asynchronous input and output, if desired. * Command open response ok 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. 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 print-execute-command response ok ,,... auxverb|shstring [ ...] Prints a command that can be executed by the caller to run a command on the testbed. Only available if the `print-execute-command' capability is advertised. The command has the following properties (which are, for example, satisfiable when the virt server uses `env' `ssh' or `dchroot'): - The caller is expected to url-decode and each , append the command to be run on the testbed, and call exec on the results. - If auxverb is advertised, the supplied additional arguments to command will be interpreted as the command and arguments to be run on the testbed (as env and nice interpret their arguments) - If shstring is advertised, there should be one additional argument which will be fed to sh -c on the testbed (this is the way ssh interprets its arguments). - The testbed program's stdin, stdout and stderr will be plumbed through to the stdin, stdout and stderr passed to ; 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. - 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. - '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) will exit with the signal number with 128 added, or (ii) will die with the same signal (although it may fail to dump core even if the testbed program did), or (iii) will fail. If fails it will exit 126, 127, 254, or 255; of course 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 (eg, file descriptors, 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 invocation will not have any further effect on the testbed. - Sending 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 (ie, if just the specified and s is passed to exec) is not defined. - Currently no s are defined; they work the same way as capabilities in that unrecognised ones should be ignored by the caller. The response (ie, the ) is only valid between `open' and the next subsequent `close', `revert' or `quit'. Using it at other times has undefined behaviour. * Command execute ,,... \ [ ...] response ok 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: env== Sets the environment variable to . debug=- Arranges to pass fd the testbed command, and send all output to it to the fd as passed by the virt server's caller. may be 1 or 2, in which case no output will be written to the or files. If this feature is available, execute-debug will be advertised. Only one such plumbing is available. timeout= Ensures that the whole execute command does not take more than . If it does, the response is timeout instead of `ok '. An effort will be made to kill the processes on the testbed but this is not guaranteed to be possible or successful. After an `execute' has timed out, the testbed should probably be reverted with `revert' if that facility is available. * Commands copydown copyup 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)