.\" -*-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
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
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
.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.
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
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
-.BI "ADD " peer " " address\fR...
+.BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
Adds a new peer. The peer is given the name
.IR peer ;
the peer's public key is assumed to be in the file
option on the command line). The
.I address
is the network address (see above for the format) at which the peer can
-be contacted.
+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
+interval. This is useful for persuading port-translating firewalls to
+believe that the `connection' is still active. The
+.I time
+is expressed as a nonnegative integer followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s
+for days, hours, minutes, or seconds respectively; if no suffix is
+given, seconds are assumed.
+.TP
+.BI "\-tunnel " tunnel
+Use the named tunnel driver, rather than the default.
+.RE
.TP
.BI "ADDR " peer
Emits an
Causes the server to disassociate itself from its terminal and become a
background task. This only works once. A warning is issued.
.TP
+.BI "EPING \fR[" options "\fR] " peer
+Sends an encrypted ping to the peer, and expects an encrypted response.
+This checks that the peer is running (and not being impersonated), and
+that it can encrypt and decrypt packets correctly. Options and
+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 "HELP"
Causes the server to emit an
.B INFO
line is written containing the peer's name, as given to
.BR ADD .
.TP
+.BI "NOTIFY " tokens\fR...
+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
+with tracing, is useful for ensuring that UDP packets are actually
+flowing in both directions. See also the
+.B EPING
+command.
+.IP
+An
+.B INFO
+line is printed describing the outcome:
+.RS
+.TP
+.BI "ping-ok " millis
+A response was received
+.I millis
+after the ping was sent.
+.TP
+.BI "ping-timeout"
+No response was received within the time allowed.
+.TP
+.BI "ping-peer-died"
+The peer was killed (probably by another admin connection) before a
+response was received.
+.RE
+.IP
+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
+seconds before giving up on a response. The default is 5 seconds. (The
+time format is the same as for the
+.B "ADD \-keepalive"
+option.)
+.RE
+.TP
.B "PORT"
Emits an
.B INFO
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
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:
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
any warnings.)
.RS
.PP
-Currently, the following watch options are supported:
+Message types provided are:
.TP
.B t
.B TRACE
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.
+.BI "WARN " tokens\fR...
+Issues a
+.B USER
+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
(For any command.) The command couldn't be understood: e.g., the number
of arguments was wrong.
.TP
+.BI "bad-time-spec " word
+The
+.I word
+is not a valid time interval specification. Acceptable time
+specifications are nonnegative integers followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s ,
+for days, hours, minutes, or seconds, respectively.
+.TP
.BI "bad-trace-option " char
(For
.BR TRACE .)
There is already a peer named
.IR peer .
.TP
+.B "ping-send-failed"
+The attempt to send a ping packet failed, probably due to lack of
+encryption keys.
+.TP
.BI "resolve-error " hostname
(For
.BR ADD .)
.SH "NOTIFICATIONS"
The following notifications are sent to clients who request them.
.TP
-.BI "ADD " peer " " address \fR...
+.BI "ADD " peer " " ifname " " address \fR...
A new peer has been added. The peer's name is
-.I peer
+.IR peer ,
+its tunnel is network interface
+.IR ifname ,
and its network address is
.IR address .
.TP
.I peer
has begun or restarted. If key exchange keeps failing, this message
will be repeated periodically.
+.TP
+.BI "USER " tokens\fR...
+An administration client issued a notification using the
+.B NOTIFY
+command.
.SH "WARNINGS"
There are many possible warnings. They are categorized according to
their first tokens.
.B tripe
server to leak private key information. No chance!
.TP
-.BI "KX " peer " decrypt-failed \fR[\fBreply\fR|\fBswitch-ok\fR]"
+.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
A symmetrically-encrypted portion of a key-exchange message failed to
decrypt.
.TP
A key-exchange message was malformed. This almost certainly indicates a
bug somewhere.
.TP
-.BI "KX " peer " incorrect \fR[\fBcookie\fR|\fBswitch-rq\fR|\fBswitch-ok\fR]"
+.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
A message didn't contain the right magic data. This may be a replay of
some old exchange, or random packets being sent in an attempt to waste
CPU.
.RB ` \- '
if none is relevant.
.TP
-.BI "PEER \- unexpected-source " address\fR...
-A packet arrived from
-.I address
-(a network address \(en see above), but no peer is known at that
-address. This may indicate a misconfiguration, or simply be a result of
-one end of a connection being set up before the other.
-.TP
.BI "PEER " peer " bad-packet no-type"
An empty packet arrived. This is very strange.
.TP
(in hex) isn't understood. Probably a strange random packet from
somewhere; could be an unlikely bug.
.TP
+.BI "PEER " peer " corrupt-encrypted-ping"
+The peer sent a ping response which matches an outstanding ping, but its
+payload is wrong. There's definitely a bug somewhere.
+.TP
+.BI "PEER " peer " corrupt-transport-ping"
+The peer (apparently) sent a ping response which matches an outstanding
+ping, but its payload is wrong. Either there's a bug, or the bad guys
+are playing tricks on you.
+.TP
.BI "PEER " peer " decrypt-failed"
An encrypted IP packet failed to decrypt. It may have been mangled in
transit, or may be a very old packet from an expired previous session
successive session keys, so this shouldn't occur unless the key exchange
takes ages or fails.
.TP
+.BI "PEER " peer " malformed-encrypted-ping"
+The peer sent a ping response which is hopelessly invalid. There's
+definitely a bug somewhere.
+.TP
+.BI "PEER " peer " malformed-transport-ping"
+The peer (apparently) sent a ping response which is hopelessly invalid.
+Either there's a bug, or the bad guys are playing tricks on you.
+.TP
.BI "PEER " peer " packet-build-failed"
There wasn't enough space in our buffer to put the packet we wanted to
send. Shouldn't happen.
.BI "PEER " peer " socket-write-error \-\- " message
An error occurred attempting to send a network packet. We lost that
one.
+.TP
+.BI "PEER " peer " unexpected-encrypted-ping 0x" id
+The peer sent an encrypted ping response whose id doesn't match any
+outstanding ping. Maybe it was delayed for longer than the server was
+willing to wait, or maybe the peer has gone mad.
+.TP
+.BI "PEER \- unexpected-source " address\fR...
+A packet arrived from
+.I address
+(a network address \(en see above), but no peer is known at that
+address. This may indicate a misconfiguration, or simply be a result of
+one end of a connection being set up before the other.
+.TP
+.BI "PEER " peer " unexpected-transport-ping 0x" id
+The peer (apparently) sent a transport ping response whose id doesn't
+match any outstanding ping. Maybe it was delayed for longer than the
+server was willing to wait, or maybe the peer has gone mad; or maybe
+there are bad people trying to confuse you.
.SS "SERVER warnings"
These indicate problems concerning the server process as a whole.
.TP
.I device
failed.
.TP
+.BI "TUN \- linux config-error \-\- " message
+Configuring the Linux TUN/TAP interface failed.
+.TP
.BI "TUN " ifname " read-error \-\- " message
Reading from the tunnel device failed.
.TP
-.BI "TUN \- linux config-error \-\- " message
-Configuring the Linux TUN/TAP interface failed.
+.BI "TUN " ifname " slip bad-escape"
+The SLIP driver encountered a escaped byte it wasn't expecting to see.
+The erroneous packet will be ignored.
+.TP
+.BI "TUN " ifname " slip eof"
+The SLIP driver encountered end-of-file on its input descriptor.
+Pending data is discarded, and no attempt is made to read any more data
+from that interface ever.
+.TP
+.BI "TUN " ifname " slip escape-end"
+The SLIP driver encountered an escaped `end' marker. This probably
+means that someone's been sending it junk. The erroneous packet is
+discarded, and we hope that we've rediscovered synchronization.
+.TP
+.BI "TUN \- slip fork-error \-\- " message
+The SLIP driver encountered an error forking a child process while
+allocating a new dynamic interface.
+.TP
+.BI "TUN \- slip no-slip-interfaces"
+The driver ran out of static SLIP interfaces. Either preallocate more,
+or use dynamic SLIP interface allocation.
+.TP
+.BI "TUN " ifname " slip overflow"
+The SLIP driver gave up reading a packet because it got too large.
+.TP
+.BI "TUN \- slip pipe-error \-\- " message
+The SLIP driver encountered an error creating pipes while allocating a
+new dynamic interface.
+.TP
+.BI "TUN \- slip read-ifname-failed \-\- " message
+The SLIP driver encountered an error reading the name of a dynamically
+allocated interface. Maybe the allocation script is broken.
.TP
.BI "TUN \- unet config-error \-\- " message
Configuring the Linux Unet interface failed. Unet is obsolete and
.BI "TUN \- unet ifname-too-long \-\- " message
The Unet interface's name overflowed, so we couldn't read it properly.
Unet is obsolete and shouldn't be used any more.
+.SS "USER warnings"
+These are issued by administration clients using the
+.B WARN
+command.
+.TP
+.BI "USER " tokens\fR...
+An administration client issued a warning.
.SH "SEE ALSO"
.BR tripectl (1),
.BR tripe (8).
.PP
.IR "The Trivial IP Encryption Protocol" .
.SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blobdiff