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 testbed will actually revert when it is closed. If this
49 feature is not mentioned then changes to the testbed are
50 persistent (so destructive tests should not be performed).
53 Commands specified by `execute' will be run as root on the
54 testbed, and copyup/copydown will have full access to the
55 filesystem. Unless this capability is advertised, root access
56 is not (or may not be) available.
58 + suggested-normal-user=<username>
59 The caller is advised that <username> would be a good user to
60 use for running tests (and doing other operations) when root
61 is not required. The advertised account will exist on the
62 testbed already. Several suggested-normal-user= capabilities
63 (with distinct <username>s) may be advertised in which case
64 more than one such user is available.
70 ok <testbed-scratchspace>
72 Checks that the testbed is present and reserves it (waiting for
73 other uses of the testbed to finish first, if necessary). State:
74 Closed to Open. <testbed-scratchspace> is a pathname on the
75 testbed which can be used freely by the test scripts and which
76 is valid until the next `close', `revert' or `quit'.
82 ok <testbed-scratchspace>
84 Restores the testbed, undoing all of the changes made so far.
85 State: Open, remains Open. Only available if the `revert'
86 capability is advertised. If possible, the testbed's set of running
87 processes will also be restored to the initial state.
93 Stops the testbed and undoes filesystem changes (if `revert' is
94 advertised). State: Open to Closed.
99 print-shstring-command
101 ok <program>,<arg>,<arg>... [<keyword-info> ...]
102 Prints a command that can be executed by the caller to run a command
105 The command has the following properties (which are, for example,
106 satisfiable when the virt server uses `env' `ssh' or `dchroot'):
107 - The caller is expected to url-decode <program> and each <arg>,
108 append the command to be run on the testbed, and call exec on the
110 - For the command provided by `print-auxverb-command', the supplied
111 additional arguments to command will be interpreted as the
112 command and arguments to be run on the testbed (as env and nice
113 interpret their arguments)
114 - The command provided by `print-shstring-command', should be
115 invoked with exactly one additional argument which should be a
116 legal shell script. It will be fed to sh -c on the testbed (this
117 is the way ssh interprets its arguments).
118 - The testbed program's stdin, stdout and stderr will be plumbed
119 through to the stdin, stdout and stderr passed to <program>; this
120 may involve fd passing, or indirection via pipes or sockets. The
121 testbed program may not assume that the descriptors it receives
122 are seekable even if the originals are.
123 - It is not defined whether other file descriptors, environment
124 variables, and process properties in general, are inherited by
126 - <program> may exit as soon as the testbed command does, or it may
127 wait until every copy of the stdout and stderr descriptors passed
128 to the testbed command have been closed on the testbed.
129 - <program>'s exit status will be that of the testbed command if
130 the latter exits with a value from 0..125. If the testbed
131 command dies due to a signal, then either (i) <program> will exit
132 with the signal number with 128 added, or (ii) <program> will die
133 with the same signal (although it may fail to dump core even if
134 the testbed program did), or (iii) <program> will fail. If
135 <program> fails it will exit 126, 127, 254, or 255; of course
136 <program> may die to a some signals other than because the
137 testbed program died with the same signal.
138 - The caller may run several of these at once, subject to
139 limitation of resources (eg, file descriptors, processes)
140 - The behaviour if a command is running when the testbed is closed
141 or reverted is not defined. However, if the testbed advertises
142 `revert' then after the testbed is closed or reverted any such
143 <program> invocation will not have any further effect on the
145 - Sending <program> signals in an attempt to terminate it may not
146 terminate all of the relevant processes and may not have any
147 effect on the testbed.
148 - The behaviour if no testbed command is specified (ie, if
149 just the specified <program> and <arg>s is passed to exec) is
151 - Currently no <keyword-info>s are defined; they work the same
152 way as capabilities in that unrecognised ones should be ignored
154 The response (ie, the <command>) is only valid between `open' and
155 the next subsequent `close', `revert' or `quit'. Using it at other
156 times has undefined behaviour.
160 execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
165 Executes the command (args separated by commas, everything including
166 filenames and env var names and values url-encoded). stdin, stdout,
167 stderr are files on the testbed (must be files, not pipes).
169 Currently defined keyword arguments:
173 Sets the environment variable <var> to <value>.
177 Arranges to pass fd <tfd> the testbed command, and
178 send all output to it to the fd <hfd> as passed
179 by the virt server's caller.
181 <tfd> may be 1 or 2, in which case no output will
182 be written to the <stdout> or <stderr> files.
184 If this feature is available, execute-debug will
185 be advertised. Only one such plumbing is available.
189 Ensures that the whole execute command does not take
190 more than <seconds>. If it does, the response is
192 instead of `ok <exit-status>'.
194 An effort will be made to kill the processes on the
195 testbed but this is not guaranteed to be possible or
196 successful. After an `execute' has timed out, the
197 testbed should probably be reverted with `revert' if
198 that facility is available.
201 copydown <host-path> <testbed-path>
202 copyup <testbed-path> <host-path>
206 1. Both paths end in `/', in which case the source must be an
207 existing directory. The destination directory is replaced with a
208 copy as if made by cp -dR --preserve=mode,timestamps except
209 across the testbed boundary.
211 2. Neither path ends in `/', in which case the source must be an
212 existing file. The data from the source file is written to the
213 destination as if via shell redirection; except that if for
214 copydown of an executable file, `chmod +x' is run on the
215 destination file after the copy.
222 and then the regime server exits with status 0, after
223 closing the testbed if applicable.
228 On any error including signals to the regime server or EOF on stdin
229 the testbed is unreserved and restored to its original state (ie,
230 closed), and the regime server will print a message to stderr (unless
231 it is dying with a signal).