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 efficient-diff 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.
81 Restores the testbed, undoing all of the changes made so far.
82 State: Open, remains Open. Only available if the `revert'
83 capability is advertised. If possible, the testbed's set of running
84 processes will also be restored to the initial state.
90 Stops the testbed and undoes filesystem changes (if `revert' is
91 advertised). State: Open to Closed.
95 execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
100 Executes the command (args separated by commas, everything
101 url-encoded). stdin, stdout, stderr are files on the testbed
102 (must be files, not pipes).
104 Currently defined keyword arguments:
108 Arranges to pass fd <tfd> the testbed command, and
109 send all output to it to the fd <hfd> as passed
110 by the virt server's caller.
112 If this feature is available, execute-debug will
113 be advertised. Only one such plumbing is available.
116 copydown <host-tree> <testbed-path>
117 copyup <testbed-tree> <host-path>
119 Like cp -dR --preserve=mode,timestamps exce[t across the testbed
127 and then the regime server exits with status 0, after
128 closing the testbed if applicable.
133 On any error including signals to the regime server or EOF on stdin
134 the testbed is unreserved and restored to its original state (ie,
135 closed), and the regime server will print a message to stderr (unless
136 it is dying with a signal).
138 The representation of changes to the local filesystem is a directory
139 containing zero or more of:
140 + changed-files: list of filenames, each one nul-terminated
141 + other formats with other data or combinations of data