X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/de014da64011b21929158b746803d69cbfb05ee6..060ca767db058036f7ade27219de9ebaf1d4737b:/doc/tripe-admin.5

diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5
index b4d51b5c..b6bcdfc1 100644
--- a/doc/tripe-admin.5
+++ b/doc/tripe-admin.5
@@ -1,4 +1,10 @@
 .\" -*-nroff-*-
+.\"
+.ie t \{\
+.  if \n(.g \{\
+.    fam P
+.  \}
+.\}
 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
 .SH NAME
 tripe-admin \- administrator commands for TrIPE
@@ -134,7 +140,11 @@ indicates that a background command succeeded or failed, respectively.
 .PP
 A background command will never issue an
 .B OK
-response: it will always detach and then issue a
+or
+.B BGINFO
+response: it will always detach and then issue any
+.B BGINFO
+lines followed by
 .B BGOK
 response.
 .SS "Network addresses"
@@ -159,6 +169,43 @@ If, on input, no recognised address family token is found, the following
 words are assumed to represent an
 .B INET
 address.
+.SS "Key-value output"
+Some commands (e.g.,
+.B STATS
+and
+.BR SERVINFO )
+produce output in the form of
+.IB key = value
+pairs, one per word.  Neither the
+.I key
+nor the
+.I value
+contain spaces.
+.SS "Trace lists"
+Commands which enable or disable kinds of output (e.g.,
+.B TRACE
+and
+.BR WATCH )
+work in similar ways.  They take a single optional argument, which
+consists of a string of letters selecting message types, optionally
+interspersed with
+.RB ` + '
+to enable, or
+.RB ` \- '
+to disable, the subsequently listed types.
+.PP
+If the argument is omitted, the available message types are displayed,
+one to an
+.B INFO
+line, in a fixed-column format.  Column zero contains the key letter for
+selecting that message type; column one contains either a space or a
+.RB ` + ' 
+sign, if the message type is disabled or enabled respectively; and a
+textual description of the message type begins at column 3 and continues
+to the end of the line.
+.PP
+Lowercase key letters control individual message types.  Uppercase key
+letters control collections of message types.
 .SH "COMMAND REFERENCE"
 The commands provided are:
 .TP
@@ -255,6 +302,19 @@ Issues a
 .B USER
 notification to all interested administration clients.
 .TP
+.BI "PEERINFO " peer
+Returns information about a peer, in key-value form.  The following keys
+are returned.
+.RS
+.TP
+.B tunnel
+The tunnel driver used for this peer.
+.TP
+.B keepalive
+The keepalive interval, in seconds, or zero if no keepalives are to be
+sent.
+.RE
+.TP
 .BI "PING \fR[" options "\fR] " peer
 Send a transport-level ping to the peer.  The ping and its response are
 not encrypted or authenticated.  This command, possibly in conjunction
@@ -313,6 +373,29 @@ for example after adding a new peer key.
 .B "QUIT"
 Instructs the server to exit immediately.  A warning is sent.
 .TP
+.B "SERVINFO"
+Returns information about the server, in the form of key-value pairs.
+The following keys are used.
+.RS
+.TP
+.B implementation
+A keyword naming the implementation of the
+.BR tripe (8)
+server.  The current implementation is called
+.BR edgeware-tripe .
+.TP
+.B version
+The server's version number, as reported by
+.BR VERSION .
+.TP
+.B daemon
+Either
+.B t
+or
+.BR nil ,
+if the server has or hasn't (respectively) become a daemon.
+.RE
+.TP
 .BI "STATS " peer
 Emits a number of
 .B INFO
@@ -321,20 +404,9 @@ lines, each containing one or more statistics in the form
 The statistics-gathering is experimental and subject to change.
 .TP
 .BR "TRACE " [\fIoptions\fP]
-A trace argument consists of a string of letters (listed below)
-selecting trace outputs, optionally interspersed with
-.RB ` + '
-to enable, or
-.RB ` \- '
-to disable, the subsequently listed outputs; the initial behaviour is to
-enable listed outputs.  For example, the string
-.B ra\-st+x
-enables tracing of peer management, admin-connection handling and
-key-exchange processing, and disables tracing of symmetric keyset
-management and the system-specific tunnel driver.  If no argument is
-given, a table is returned showing the available tracing option letters
-and their meanings.  Programs should not attempt to parse this table:
-its format is not guaranteed to remain the same.
+Selects trace outputs: see
+.B "Trace lists" 
+above.  Message types provided are:
 .RS
 .PP
 Currently, the following tracing options are supported:
@@ -396,17 +468,24 @@ or
 All of the above.
 .RE
 .TP
+.B "TUNNELS"
+For each available tunnel driver, an
+.B INFO
+line is printed giving its name.
+.TP
+.B "VERSION"
+Causes the server to emit an
+.B INFO
+line stating its software version, as two words: the server name, and
+its version string.  The server name
+.B tripe
+is reserved to the Straylight/Edgeware implementation.
+.TP
 .BR "WATCH " [\fIoptions\fP]
 Enables or disables asynchronous messages
 .IR "for the current connection only" .
-This command has no effect on other connections.  A watch argument
-consists of a string of letters (listed below) selecting message types,
-optionally interspersed with
-.RB ` + '
-to enable, or
-.RB ` \- '
-to disable, the subsequently listed types, similar to
-.B trace
+See
+.B "Trace lists" 
 above.  The default watch state for the connection the server opens
 automatically on stdin/stdout is to show warnings and trace messages;
 other connections show no asynchronous messages.  (This is done in order
@@ -414,7 +493,7 @@ to guarantee that a program reading the server's stdout does not miss
 any warnings.)
 .RS
 .PP
-Currently, the following watch options are supported:
+Message types provided are:
 .TP
 .B t
 .B TRACE
@@ -432,14 +511,6 @@ messages.
 All of the above.
 .RE
 .TP
-.B "VERSION"
-Causes the server to emit an
-.B INFO
-line stating its software version, as two words: the server name, and
-its version string.  The server name
-.B tripe
-is reserved to the Straylight/Edgeware implementation.
-.TP
 .BI "WARN " tokens\fR...
 Issues a 
 .B USER