where the words after ok are features that not all regimes
support. Valid in all states.
- Currently defined features:
+ 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).
+ + 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).
+ + 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.
+
+ + 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
* Command
- stop <local-pathname>
+ revert
- 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
* Command
- execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd>
+ print-execute-command
+ response
+ ok <program>,<arg>,<arg>... auxverb|shstring [<keyword-info> ...]
+ 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 <program> and each <arg>,
+ 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 <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>
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>
~ianmdlvl / autopkgtest.git / blobdiff