define new debug keyword arg

[autopkgtest.git] / doc / README.virtualisation-server

diff --git a/doc/README.virtualisation-server b/doc/README.virtualisation-server
index 25cfdfa636a9fcb791f58439836fd6515f7e19f8..8bcdedf50ba672f3b3fb7139c357ea5d7ffcfa1a 100644 (file)
--- a/doc/README.virtualisation-server
+++ b/doc/README.virtualisation-server
@@ -42,14 +42,26 @@ Protocol
   where the words after ok are features that not all regimes
   support.  Valid in all states.
 
-  Currently defined features:
+  Currently defined capabilities:
 
-    + 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).
+    + 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).
+    + 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
@@ -64,12 +76,12 @@ Protocol
 
 
 * Command
-       stop <local-pathname>
+       reset
 
-  Stops the testbed.  Replaces local-pathname (on the host) with a
-  directory containing a representation of the changes to the
-  testbed's filesystem; these changes are undone (if `revert' was
-  advertised).  Then reverts the testbed.  State: Open to Closed.
+  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
@@ -80,7 +92,8 @@ Protocol
 
 
 * Command
-       execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd>
+       execute <program>,<arg>,<arg>... <stdin> <stdout> <stderr> <cwd> \
+               [<keyword-args> ...]
   response
        ok <exit-status>
 
@@ -88,6 +101,16 @@ Protocol
   url-encoded).  stdin, stdout, stderr are files on the testbed
   (must be files, not pipes).
 
+  Currently defined keyword arguments:
+
+       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.
+
+               If this feature is available, execute-debug will
+               be advertised.  Only one such plumbing is available.
 
 * Commands
        copydown <host-tree> <testbed-path>