* Command
capabilities
response, for example
- ok efficient-diff revert ...
+ ok gnomovision-server 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).
+ 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
+
+ + 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. etc. etc.
+
+ + 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
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.
+ testbed which can be used freely by the test scripts and which
+ is valid until the next `close', `revert' or `quit'.
* Command
- stop <local-pathname>
+ revert
+ response
+ ok <testbed-scratchspace>
- 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.
+ 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
advertised). State: Open to Closed.
+* Commands
+ print-auxverb-command
+ print-shstring-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 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 <program> and each <arg>,
+ append the command to be run on the testbed, and call exec on the
+ results.
+ - For the command provided by `print-auxverb-command', 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)
+ - The command provided by `print-shstring-command', should be
+ invoked with exactly one additional argument which should be a
+ legal shell script. It 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 <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 (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
+ <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 (ie, if
+ just the specified <program> and <arg>s is passed to exec) is
+ not defined.
+ - Currently no <keyword-info>s are defined; they work the same
+ way as capabilities in that unrecognised ones should be ignored
+ by the caller.
+ The response (ie, the <command>) is only valid between `open' and
+ the next subsequent `close', `revert' or `quit'. Using it at other
+ times has undefined behaviour.
+
+
* Command
- execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd>
+ 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).
+ Executes the command (args separated by commas, everything including
+ filenames and env var names and values url-encoded). stdin, stdout,
+ stderr are files on the testbed (must be files, not pipes).
+
+ Currently defined keyword arguments:
+
+ env=<var>=<value>
+
+ Sets the environment variable <var> to <value>.
+ 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.
+
+ <tfd> may be 1 or 2, in which case no output will
+ be written to the <stdout> or <stderr> files.
+
+ If this feature is available, execute-debug will
+ be advertised. Only one such plumbing is available.
+
+ timeout=<seconds>
+
+ Ensures that the whole execute command does not take
+ more than <seconds>. If it does, the response is
+ timeout
+ instead of `ok <exit-status>'.
+
+ 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 <host-tree> <testbed-path>
- copyup <testbed-tree> <host-path>
+ copydown <host-path> <testbed-path>
+ copyup <testbed-path> <host-path>
+
+ Either
+
+ 1. Both paths end in `/', in which case the source must be an
+ existing directory. The destination directory is replaced with a
+ copy as if made by cp -dR --preserve=mode,timestamps except
+ across the testbed boundary.
- Like cp -dR --preserve=mode,timestamps exce[t across the testbed
- boundary.
+ 2. Neither path ends in `/', in which case the source must be an
+ existing file. The data from the source file is written to the
+ destination as if via shell redirection; except that if for
+ copydown of an executable file, `chmod +x' is run on the
+ destination file after the copy.
* Command
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)
-