1 AUTOPKGTEST VIRTUALISATION SERVICE INTERFACE
2 ============================================
4 The virtualisation regime provides a single executable program which
5 is used by the tester core to request virtualisation facilities.
7 The server has the following states:
9 * Closed: there is no particular testbed. This is the initial state.
11 * Open: the testbed is running and can be communicated with (and, if
12 applicable, is not being used by any other concurrent test run)
14 Note that these are the states of the server, in the tester core to
15 server protocol. The actual testbed will probably have more states,
16 including for example Closed, Open (and therefore busy), Modified,
17 Broken, etc. Ideally the virtualisation regime will prevent multiple
18 concurrent uses of the same testbed; the tester core is allowed to
19 assume that either its caller or the virtualisation regime will ensure
20 that it has exclusive use of the testbed.
22 The server program is invoked with the argument
23 --debian-package-testing and then proceeds to speak a protocol on its
24 stdin/stdout. The protocol is line-based. In the future other ways
25 of invoking the server may be defined; the current server should of
26 course reject such invocations.
32 * Initial response from regime server:
34 This response is also the response from any of the commands listed
35 below, unless otherwise specified.
41 ok gnomovision-server revert ...
42 where the words after ok are features that not all regimes
43 support. Valid in all states.
45 Currently defined capabilities:
48 The "revert" command is supported. The base semantics
49 are that the following aspects of the testbed are reverted:
50 - the set of installed packages
51 - the contents of the root filesystem, BUT
52 - NOT the contents of /home
53 - NOT the contents of /tmp
54 - NOT the set of running processes
57 The "revert" and "close" commands will completely revert the
58 testbed to the state after "open". This reversion is done
59 with some kind of virtualisation, and includes (without
60 limitation) the contents of all the testbed filesystems, its
61 running processes, network configuration, etc. etc. etc.
64 The testbed will actually revert when it is closed. If this
65 feature is not mentioned then changes to the testbed are
66 persistent (so destructive tests should not be performed).
69 Commands specified by `execute' will be run as root on the
70 testbed, and copyup/copydown will have full access to the
71 filesystem. Unless this capability is advertised, root access
72 is not (or may not be) available.
74 + suggested-normal-user=<username>
75 The caller is advised that <username> would be a good user to
76 use for running tests (and doing other operations) when root
77 is not required. The advertised account will exist on the
78 testbed already. Several suggested-normal-user= capabilities
79 (with distinct <username>s) may be advertised in which case
80 more than one such user is available.
86 ok <testbed-scratchspace>
88 Checks that the testbed is present and reserves it (waiting for
89 other uses of the testbed to finish first, if necessary). State:
90 Closed to Open. <testbed-scratchspace> is a pathname on the
91 testbed which can be used freely by the test scripts and which
92 is valid until the next `close', `revert' or `quit'.
98 ok <testbed-scratchspace>
100 Restores the testbed, undoing all of the changes made so far.
101 State: Open, remains Open. Only available if the `revert'
102 capability is advertised. If possible, the testbed's set of running
103 processes will also be restored to the initial state.
109 Stops the testbed and undoes filesystem changes (if `revert' is
110 advertised). State: Open to Closed.
114 print-auxverb-command
115 print-shstring-command
117 ok <program>,<arg>,<arg>... [<keyword-info> ...]
118 Prints a command that can be executed by the caller to run a command
121 The command has the following properties (which are, for example,
122 satisfiable when the virt server uses `env' `ssh' or `dchroot'):
123 - The caller is expected to url-decode <program> and each <arg>,
124 append the command to be run on the testbed, and call exec on the
126 - For the command provided by `print-auxverb-command', the supplied
127 additional arguments to command will be interpreted as the
128 command and arguments to be run on the testbed (as env and nice
129 interpret their arguments)
130 - The command provided by `print-shstring-command', should be
131 invoked with exactly one additional argument which should be a
132 legal shell script. It will be fed to sh -c on the testbed (this
133 is the way ssh interprets its arguments).
134 - The testbed program's stdin, stdout and stderr will be plumbed
135 through to the stdin, stdout and stderr passed to <program>; this
136 may involve fd passing, or indirection via pipes or sockets. The
137 testbed program may not assume that the descriptors it receives
138 are seekable even if the originals are.
139 - It is not defined whether other file descriptors, environment
140 variables, and process properties in general, are inherited by
142 - <program> may exit as soon as the testbed command does, or it may
143 wait until every copy of the stdout and stderr descriptors passed
144 to the testbed command have been closed on the testbed.
145 - <program>'s exit status will be that of the testbed command if
146 the latter exits with a value from 0..125. If the testbed
147 command dies due to a signal, then either (i) <program> will exit
148 with the signal number with 128 added, or (ii) <program> will die
149 with the same signal (although it may fail to dump core even if
150 the testbed program did), or (iii) <program> will fail. If
151 <program> fails it will exit 126, 127, 254, or 255; of course
152 <program> may die to a some signals other than because the
153 testbed program died with the same signal.
154 - The caller may run several of these at once, subject to
155 limitation of resources (eg, file descriptors, processes)
156 - The behaviour if a command is running when the testbed is closed
157 or reverted is not defined. However, if the testbed advertises
158 `revert' then after the testbed is closed or reverted any such
159 <program> invocation will not have any further effect on the
161 - Sending <program> signals in an attempt to terminate it may not
162 terminate all of the relevant processes and may not have any
163 effect on the testbed.
164 - The behaviour if no testbed command is specified (ie, if
165 just the specified <program> and <arg>s is passed to exec) is
167 - Currently no <keyword-info>s are defined; they work the same
168 way as capabilities in that unrecognised ones should be ignored
170 The response (ie, the <command>) is only valid between `open' and
171 the next subsequent `close', `revert' or `quit'. Using it at other
172 times has undefined behaviour.
176 execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
181 Executes the command (args separated by commas, everything including
182 filenames and env var names and values url-encoded). stdin, stdout,
183 stderr are files on the testbed (must be files, not pipes).
185 Currently defined keyword arguments:
189 Sets the environment variable <var> to <value>.
193 Arranges to pass fd <tfd> the testbed command, and
194 send all output to it to the fd <hfd> as passed
195 by the virt server's caller.
197 <tfd> may be 1 or 2, in which case no output will
198 be written to the <stdout> or <stderr> files.
200 If this feature is available, execute-debug will
201 be advertised. Only one such plumbing is available.
205 Ensures that the whole execute command does not take
206 more than <seconds>. If it does, the response is
208 instead of `ok <exit-status>'.
210 An effort will be made to kill the processes on the
211 testbed but this is not guaranteed to be possible or
212 successful. After an `execute' has timed out, the
213 testbed should probably be reverted with `revert' if
214 that facility is available.
217 copydown <host-path> <testbed-path>
218 copyup <testbed-path> <host-path>
222 1. Both paths end in `/', in which case the source must be an
223 existing directory. The destination directory is replaced with a
224 copy as if made by cp -dR --preserve=mode,timestamps except
225 across the testbed boundary.
227 2. Neither path ends in `/', in which case the source must be an
228 existing file. The data from the source file is written to the
229 destination as if via shell redirection; except that if for
230 copydown of an executable file, `chmod +x' is run on the
231 destination file after the copy.
238 and then the regime server exits with status 0, after
239 closing the testbed if applicable.
244 On any error including signals to the regime server or EOF on stdin
245 the testbed is unreserved and restored to its original state (ie,
246 closed), and the regime server will print a message to stderr (unless
247 it is dying with a signal).