* 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 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
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
revert
+ response
+ ok <testbed-scratchspace>
Restores the testbed, undoing all of the changes made so far.
State: Open, remains Open. Only available if the `revert'
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> \
[<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.
- <tfd> may be 1 or 2, in which case no output will
- be written to the <stdout> or <stderr> files.
+ 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>
- Like cp -dR --preserve=mode,timestamps exce[t across the testbed
- boundary.
+ 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.
+
+ 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.
+
+ Both filenames are url-encoded.
* 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)
-
~ianmdlvl / autopkgtest.git / blobdiff