X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/0ba8de86535cf6025076f5034b76ab753e4dde08..d8f6a5994b25de9ad478c94e86441a900acf2b96:/doc/tripe-admin.5

diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5
index 327d1b56..4afa6a9f 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
@@ -18,10 +24,9 @@ with little difficulty.
 By default, the server listens for admin connections on the Unix-domain
 socket
 .BR /var/lib/tripe/tripesock .
-Administration commands use a simple textual protocol.  Each client
-command or server response consists of a line of ASCII text terminated
-by a single linefeed character.  No command may be longer than 255
-characters.
+Administration commands use a textual protocol.  Each client command or
+server response consists of a line of ASCII text terminated by a single
+linefeed character.  No command may be longer than 255 characters.
 .SS "General structure"
 Each command or response line consists of a sequence of
 whitespace-separated words.  The number and nature of whitespace
@@ -32,8 +37,8 @@ line is a
 identifying the type of command or response contained.  Keywords in
 client commands are not case-sensitive; the server always uses uppercase
 for its keywords.
-.SS "Server responses"
-For client command, the server responds with zero or more
+.SS "Simple commands"
+For simple client command, the server responds with zero or more
 .B INFO
 lines, followed by either an
 .B OK
@@ -48,13 +53,27 @@ response contains no further data.  A
 code is followed by a machine-readable explanation of why the command
 failed.
 .PP
-In addition, there are three types of asynchronous messages which
-aren't associated with any particular command.  The
+Simple command processing is strictly synchronous: the server reads a
+command, processes it, and responds, before reading the next command.
+All commands can be run as simple commands.  Long-running commands
+(e.g.,
+.B ADD
+and
+.BR PING )
+block the client until they finish, but the rest of the server continues
+running.
+.SS "Asynchronous messages"
+There are three types of asynchronous messages which
+aren't associated with any particular command.
+.PP
+The
 .B WARN
 message contains a machine-readable message warning of an error
 encountered while processing a command, unexpected or unusual behaviour
 by a peer, or a possible attack by an adversary.  Under normal
-conditions, the server shouldn't emit any warnings.  The
+conditions, the server shouldn't emit any warnings.
+.PP
+The
 .B TRACE
 message contains a human-readable tracing message containing diagnostic
 information.  Trace messages are controlled using the
@@ -63,7 +82,9 @@ command-line option to the server, or the
 .B TRACE
 administration command (see below).  Support for tracing can be disabled
 when the package is being configured, and may not be available in your
-version.  Finally, the
+version.
+.PP
+Finally, the
 .B NOTE
 message is a machine-readable notification about some routine but
 interesting event such as creation or destruction of peers.
@@ -71,6 +92,60 @@ interesting event such as creation or destruction of peers.
 The presence of asynchronous messages can be controlled using the
 .B WATCH
 command.
+.SS "Background commands"
+Some commands (e.g.,
+.B ADD
+and
+.BR PING )
+take a long time to complete.  To prevent these long-running commands
+from tying up a server connection, they can be run in the background.
+Not all commands can be run like this: the ones that can provide a
+.B \-background
+option, which must be supplied with a
+.IR tag .
+.PP
+A command may fail before it starts running in the background.  In this
+case, the server emits a
+.B FAIL
+response, as usual.  To indicate that a command has started running in
+the background, the server emits a response of the form
+.BI "BGDETACH " tag \fR,
+where
+.I tag
+is the value passed to the
+.B \-background
+option.  From this point on, the server is ready to process more
+commands and reply to them.
+.PP
+Responses to background commands are indicated by a line beginning with
+one of the tokens 
+.BR BGOK ,
+.BR BGFAIL ,
+or
+.BR BGINFO ,
+followed by the command tag.  These correspond to the 
+.BR OK ,
+.BR FAIL ,
+and
+.B INFO
+responses for simple commands:
+.B BGINFO
+indicates information from a background command which has not completed
+yet; and
+.B BGOK
+and
+.B BGFAIL
+indicates that a background command succeeded or failed, respectively.
+.PP
+A background command will never issue an
+.B OK
+or
+.B BGINFO
+response: it will always detach and then issue any
+.B BGINFO
+lines followed by
+.B BGOK
+response.
 .SS "Network addresses"
 A network address is a sequence of words.  The first is a token
 identifying the network address family.  The length of an address and
@@ -93,6 +168,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
@@ -109,6 +221,10 @@ is the network address (see above for the format) at which the peer can
 be contacted.  The following options are recognised.
 .RS
 .TP
+.BI "\-background " tag
+Run the command in the background, using the given
+.IR tag .
+.TP
 .BI "\-keepalive " time
 Send a no-op packet if we've not sent a packet to the peer in the last
 .I time
@@ -134,6 +250,13 @@ Emits an
 line reporting the IP address and port number stored for
 .IR peer .
 .TP
+.BI "CHECKCHAL " challenge
+Verifies a challenge as being one earlier issued by
+.B GETCHAL
+and not previously either passed to
+.B CHECKCHAL
+or in a greeting message.
+.TP
 .B "DAEMON"
 Causes the server to disassociate itself from its terminal and become a
 background task.  This only works once.  A warning is issued.
@@ -146,6 +269,25 @@ responses are the same as for the
 .B PING
 command.
 .TP
+.BI "FORCEKX " peer
+Requests the server to begin a new key exchange with
+.I peer
+immediately.
+.TP
+.B "GETCHAL"
+Requests a challenge.  The challenge is returned in an
+.B INFO
+line, as a base64-encoded string.  See
+.BR CHECKCHAL .
+.TP
+.BI "GREET " peer " " challenge
+Sends a greeting packet containing the
+.I challenge
+(base-64 encoded) to the named
+.IR peer .
+The expectation is that this will cause the peer to recognize us and
+begin a key-exchange.
+.TP
 .B "HELP"
 Causes the server to emit an
 .B INFO
@@ -180,6 +322,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
@@ -209,6 +364,10 @@ response was received.
 Options recognized for this command are:
 .RS
 .TP
+.BI "\-background " tag
+Run the command in the background, using the given
+.IR tag .
+.TP
 .BI "\-timeout " time
 Wait for
 .I time
@@ -226,9 +385,37 @@ line containing just the number of the UDP port used by the
 server.  If you've allowed your server to allocate a port dynamically,
 this is how to find out which one it chose.
 .TP
+.B "RELOAD"
+Instructs the server to recheck its keyring files.  The server checks
+these periodically anyway but it may be necessary to force a recheck,
+for example after adding a new peer key.
+.TP
 .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
@@ -237,20 +424,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:
@@ -269,15 +445,6 @@ the backgroud name-resolution required by the
 .B ADD
 command.
 .TP
-.B p
-Display contents of packets sent and received by the tunnel and/or peer
-modules.
-.TP
-.B c
-Display inputs, outputs and intermediate results of cryptographic
-operations.  This includes plaintext and key material.  Use with
-caution.
-.TP
 .B s
 Handling of symmetric keysets: creation and expiry of keysets, and
 encryption and decryption of messages.
@@ -287,6 +454,21 @@ Key exchange: reception, parsing and emission of key exchange messages.
 .TP
 .B m
 Key management: loading keys and checking for file modifications.
+.TP
+.B l
+Display information about challenge issuing and verification.
+.TP
+.B p
+Display contents of packets sent and received by the tunnel and/or peer
+modules.
+.TP
+.B c
+Display inputs, outputs and intermediate results of cryptographic
+operations.  This includes plaintext and key material.  Use with
+caution.
+.TP
+.B A
+All of the above.
 .PP
 Note that the
 .B p
@@ -297,32 +479,37 @@ and
 outputs provide extra detail for other outputs.  Specifying
 .B p
 without
-.B r
+.BR r
 or
 .B t
 isn't useful; neither is specifying
 .B c
 without one of
 .BR s ,
+.BR l ,
 .B x
 or
 .BR m .
-.TP
-.B A
-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
@@ -330,7 +517,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
@@ -344,18 +531,10 @@ messages.
 .B WARN
 messages.
 .TP
-.B a
+.B A
 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
@@ -363,6 +542,8 @@ warning to all interested administration clients.
 .SH "ERROR MESSAGES"
 The following
 .B FAIL
+(or
+.BR BGFAIL )
 messages are sent to clients as a result of errors during command
 processing.
 .TP
@@ -373,6 +554,10 @@ The
 .B tripe
 server is already running as a daemon.
 .TP
+.BI "bad-addr-syntax \-\- " message
+(For commands accepting socket addresses.)  The address couldn't be
+understood.
+.TP
 .BI "bad-syntax \-\- " message
 (For any command.)  The command couldn't be understood: e.g., the number
 of arguments was wrong.
@@ -478,6 +663,12 @@ and its network address is
 .BI "DAEMON"
 The server has forked off into the sunset and become a daemon.
 .TP
+.BI "GREET " challenge " " address \fR...
+A valid greeting was received, with the given challenge (exactly as it
+was returned by
+.B GETCHAL
+earlier).
+.TP
 .BI "KILL " peer
 The peer
 .I peer
@@ -520,6 +711,29 @@ client.
 .BI "ADMIN client-read-error \-\- " message
 There was an error sending data to a client.  The connection to the
 client has been closed.
+.SS "CHAL warnings"
+These indicate errors in challenges, either in the
+.B CHECKCHAL
+command or in greeting packets.
+.TP
+.B "CHAL impossible-challenge"
+The server hasn't issued any challenges yet.  Quite how anyone else
+thought he could make one up is hard to imagine.
+.TP
+.B "CHAL incorrect-tag"
+Challenge received contained the wrong authentication data.  It might be
+very stale, or a forgery.
+.TP
+.B "CHAL invalid-challenge"
+Challenge received was the wrong length.  We might have changed MAC
+algorithms since the challenge was issued, or it might just be rubbish.
+.TP
+.B "CHAL replay duplicated-sequence"
+Challenge received was a definite replay of an old challenge.  Someone's
+up to something!
+.TP
+.B "CHAL replay old-sequence"
+Challenge received was old, but maybe not actually a replay.  Try again.
 .SS "KEYMGMT warnings"
 These indicate a problem with the keyring files, or the keys stored in
 them.