* 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.
-
- * Initial response from regime server: ok
-
- * Command capabilities; response eg ok efficient-diff 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).
-
- * Command open; response ok testbed-scratchspace. 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.
-
- * Command stop local-pathname; response ok. Indicates that the testbed should
- be stopped; replaces local-pathname (on the host) with a directory
- containing a representation of the changes to the testbed's filesystem.
- Then reverts the testbed. State: Open to Closed.
-
- * Command close; response ok. Stops and undoes filesystem changes. State:
- Open to Closed.
-
- * Command execute program,arg,arg... stdin stdout stderr cwd; response
- ok exitstatus. Executes the command (args separated by commas, everything
- url-encoded). stdin, stdout, stderr are files on the testbed (must be
- files, not pipes).
-
- * Command copydown host-tree testbed-path or copyup testbed-tree host-path.
- Response ok. Like cp -dR --preserve=mode,timestamps only across the testbed
- boundary.
-
- * Command quit; response ok and 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)
-
+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 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
+ 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
+ open
+ response
+ ok <testbed-scratchspace>
+
+ 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 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'
+ 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.
+
+
+* 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 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-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.
+
+ 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
+ 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).
~ianmdlvl / autopkgtest.git / blobdiff