From 5fe4f4913af2cc78ff5eb00ffd7943c41d5f16f4 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 23 Jan 2007 11:06:05 +0000 Subject: [PATCH 1/1] cut and paste the virt server stuff from the wiki; needs reformatting etc. --- doc/README.virtualisation-server | 74 ++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 doc/README.virtualisation-server diff --git a/doc/README.virtualisation-server b/doc/README.virtualisation-server new file mode 100644 index 0000000..0e52f8b --- /dev/null +++ b/doc/README.virtualisation-server @@ -0,0 +1,74 @@ +AUTOPKGTEST VIRTUALISATION SERVICE INTERFACE +============================================ + +The virtualisation regime provides a single executable program which +is used by the tester core to request virtualisation facilities. + +The server has the following states: + + * Closed: there is no particular testbed. This is the initial state. + + * 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) + -- 2.30.2