Issue ADD and KXSTART notifications in the right order!

[tripe] / doc / tripe-admin.5

.\" -*-nroff-*-
.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH NAME
tripe-admin \- administrator commands for TrIPE
.SH DESCRIPTION
This manual page describes the administration interface provided by the
.BR tripe (8)
daemon.
.PP
The
.BR tripectl (8)
program can be used either interactively or in scripts to communicate
with the server using this interface.  Alternatively, simple custom
clients can be written in scripting languages such as Perl, Python or
Tcl, or more advanced clients such as GUI monitors can be written in C
with little difficulty.
.PP
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.
.SS "General structure"
Each command or response line consists of a sequence of
whitespace-separated words.  The number and nature of whitespace
characters separating two words in a client command is not significant;
the server always uses a single space character.  The first word in a
line is a
.I keyword
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
.B INFO
lines, followed by either an
.B OK
line or a
.B FAIL
line.  Each
.B INFO
provides information requested in the command.  An
.B OK
response contains no further data.  A
.B FAIL
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
.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
.B TRACE
message contains a human-readable tracing message containing diagnostic
information.  Trace messages are controlled using the
.B \-T
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
.B NOTE
message is a machine-readable notification about some routine but
interesting event such as creation or destruction of peers.
.PP
The presence of asynchronous messages can be controlled using the
.B WATCH
command.
.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
the meanings of the subsequent words depend on the address family.
Address family tokens are not case-sensitive on input; on output, they
are always in upper-case.
.PP
At present, only one address family is understood.
.TP
.BI "INET " address " " port
An Internet socket, naming an IPv4 address and UDP port.  On output, the
address is always in numeric dotted-quad form, and the port is given as
a plain number.  On input, DNS hostnames and symbolic port names are
permitted.  Name resolution does not block the main server, but will
block the requesting client.  This hopefully makes life simpler for
stupid clients.  Complex clients which don't wish to be held up can open
extra connections or do the resolution themselves.)
.PP
If, on input, no recognised address family token is found, the following
words are assumed to represent an
.B INET
address.
.SH "COMMAND REFERENCE"
The commands provided are:
.TP
.BI "ADD " peer " " 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
.B keyring.pub
(or whatever alternative file was specified in the
.B \-K
option on the command line).  The
.I address
is the network address (see above for the format) at which the peer can
be contacted.
.TP
.BI "ADDR " peer
Emits an
.B INFO
line reporting the IP address and port number stored for
.IR peer .
.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.
.TP
.B "HELP"
Causes the server to emit an
.B INFO
line for each command it supports.  Each line lists the command name,
followed by the names of the arguments.  This may be helpful as a memory
aid for interactive use, or for program clients probing for features.
.TP 
.BI "IFNAME " peer
Emits an
.B INFO
line containing the name of the network interface used to collect IP
packets which are to be encrypted and sent to
.IR peer .
Used by configuration scripts so that they can set up routing tables
appropriately after adding new peers.
.TP
.BI "KILL " peer
Causes the server to forget all about
.IR peer .
All keys are destroyed, and no more packets are sent.  No notification
is sent to the peer: if it's important that the peer be notified, you
must think of a way to do that yourself.
.TP
.B "LIST"
For each currently-known peer, an
.B INFO
line is written containing the peer's name, as given to
.BR ADD .
.TP
.B "PORT"
Emits an
.B INFO
line containing just the number of the UDP port used by the
.B tripe
server.  If you've allowed your server to allocate a port dynamically,
this is how to find out which one it chose.
.TP
.B "QUIT"
Instructs the server to exit immediately.  A warning is sent.
.TP
.BI "STATS " peer
Emits a number of
.B INFO
lines, each containing one or more statistics in the form
.IB name = value \fR.
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.
.RS
.PP
Currently, the following tracing options are supported:
.TP
.B t
Tunnel events: reception of packets to be encrypted, and injection of
successfully-decrypted packets.
.TP
.B r
Peer management events: creation and destruction of peer attachments,
and arrival of messages.
.TP
.B a
Administration interface: acceptance of new connections, and handling of
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.
.TP
.B x
Key exchange: reception, parsing and emission of key exchange messages.
.TP
.B m
Key management: loading keys and checking for file modifications.
.PP
Note that the
.B p
(packet contents)
and
.B c
(crypto details)
outputs provide extra detail for other outputs.  Specifying
.B p
without
.B r
or
.B t
isn't useful; neither is specifying
.B c
without one of
.BR s ,
.B x
or
.BR m .
.TP
.B A
All of the above.
.RE
.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
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
to guarantee that a program reading the server's stdout does not miss
any warnings.)
.RS
.PP
Currently, the following watch options are supported:
.TP
.B t
.B TRACE
messages.
.TP
.B n
.B NOTE
messages.
.TP
.B w
.B WARN
messages.
.TP
.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.
.SH "ERROR MESSAGES"
The following
.B FAIL
messages are sent to clients as a result of errors during command
processing.
.TP
.BI "already-daemon"
(For
.BR DAEMON .)
The
.B tripe
server is already running as a daemon.
.TP
.BI "bad-syntax \-\- " message
(For any command.)  The command couldn't be understood: e.g., the number
of arguments was wrong.
.TP
.BI "bad-trace-option " char
(For
.BR TRACE .)
An unknown trace option was requested.
.TP
.BI "bad-watch-option " char
(For
.BR WATCH .)
An unknown watch option was requested.
.TP
.BI "daemon-error \-\- " message
(For
.BR DAEMON .)
An error occurred during the attempt to become a daemon, as reported by
.IR message .
.TP
.BI "invalid-port " number
(For
.BR ADD .)
The given port number is out of range.
.TP
.BI "peer-create-fail " peer
(For
.BR ADD .)
Adding
.I peer
failed for some reason.  A warning should have been emitted explaining
why.
.TP
.BI "peer-exists " peer
(For
.BR ADD .)
There is already a peer named
.IR peer .
.TP
.BI "resolve-error " hostname
(For
.BR ADD .)
The DNS name
.I hostname
could not be resolved.
.TP
.BI "resolver-timeout " hostname
(For
.BR ADD .)
The DNS name
.I hostname
took too long to resolve.
.TP
.BI "unknown-command " token
The command
.B token
was not recognised.
.TP
.BI "unknown-peer " name
(For
.BR ADDR ,
.BR IFNAME ,
.BR KILL ,
and
.BR STATS .)
There is no peer called
.IR name .
.TP
.BI "unknown-service " service
(For
.BR ADD .)
The service name
.I service
couldn't be found in 
.BR /etc/services .
.SH "NOTIFICATIONS"
The following notifications are sent to clients who request them.
.TP
.BI "ADD " peer " " address \fR...
A new peer has been added.  The peer's name is
.I peer
and its network address is
.IR address .
.TP
.BI "DAEMON"
The server has forked off into the sunset and become a daemon.
.TP
.BI "KILL " peer
The peer
.I peer
has been killed.
.TP
.BI "KXDONE " peer
Key exchange with
.I peer
finished successfully.
.TP
.BI "KXSTART " peer
Key exchange with
.I peer
has begun or restarted.  If key exchange keeps failing, this message
will be repeated periodically.
.SH "WARNINGS"
There are many possible warnings.  They are categorized according to
their first tokens.
.SS "ABORT warnings"
These all indicate that the
.B tripe
server has become unable to continue.  If enabled, the server will dump
core in its configuration directory.
.TP
.BI "ABORT repeated-select-errors"
The main event loop is repeatedly failing.  If the server doesn't quit,
it will probably waste all available CPU doing nothing.
.SS "ADMIN warnings"
These indicate a problem with the administration socket interface.
.TP
.BI "ADMIN accept-error \-\- " message
There was an error while attempting to accept a connection from a new
client.
.TP
.BI "ADMIN client-read-error \-\- " message
There was an error sending data to a client.  The connection to the
client has been closed.
.SS "KEYMGMT warnings"
These indicate a problem with the keyring files, or the keys stored in
them.
.TP
.BI "KEYMGMT bad-private-key \-\- " message
The private key could not be read, or failed a consistency check.  If
there was a problem with the file, usually there will have been
.B key-file-error
warnings before this.
.TP
.BI "KEYMGMT bad-public-keyring \-\- " message
The public keyring couldn't be read.  Usually, there will have been 
.B key-file-error
warnings before this.
.TP
.BI "KEYMGMT key-file-error " file ":" line " \-\- " message
Reports a specific error with the named keyring file.  This probably
indicates a bug in
.BR key (1).
.TP
.BI "KEYMGMT public-key " tag " " tokens\fR...
These messages all indicate a problem with the public key named
.IR tag .
.TP
.BI "KEYMGMT public-key " tag " algorithm-mismatch"
The algorithms specified on the public key don't match the ones for our
private key.  All the peers in a network have to use the same
algorithms.
.TP
.BI "KEYMGMT public-key " tag " bad \-\- " message
The public key couldn't be read, or is invalid.
.TP
.BI "KEYMGMT public-key " tag " bad-public-group-element"
The public key is invalid.  This may indicate a malicious attempt to
introduce a bogus key.
.TP
.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
The algorithms listed on the public key couldn't be understood.  The
algorithm selection attributes are probably malformed and need fixing.
.TP
.BI "KEYMGMT public-key " tag " incorrect-group"
The public key doesn't use the same group as our private key.  All the
peers in a network have to use the same group.
.TP
.BI "KEYMGMT public-key " tag " not-found"
The public key for peer
.I tag
wasn't in the public keyring.
.TP
.BI "KEYMGMT public-key " tag " unknown-type"
The type of the public key isn't understood.  Maybe you need to upgrade
your copy of
.BR tripe .
(Even if you do, you'll have to regenerate your keys.)
.SS "KX warnings"
These indicate problems during key-exchange.  Many indicate either a bug
in the server (either yours or the remote one), or some kind of attack
in progress.  All name a
.I peer
as the second token: this is the peer the packet is apparently from,
though it may have been sent by an attacker instead.
.PP
In the descriptions below,
.I msgtoken
is one of the tokens
.BR pre-challenge ,
.BR cookie ,
.BR challenge ,
.BR reply ,
.BR switch-rq ,
or
.BR switch-ok .
.TP
.BI "KX " peer " bad-expected-reply-log"
The challenges
.B tripe
uses in its protocol contain a check value which proves that the
challenge is honest.  This message indicates that the check value
supplied is wrong: someone is attempting to use bogus challenges to
persuade your
.B tripe
server to leak private key information.  No chance!
.TP
.BI "KX " peer " decrypt-failed \fR[\fBreply\fR|\fBswitch-ok\fR]"
A symmetrically-encrypted portion of a key-exchange message failed to
decrypt.
.TP
.BI "KX " peer " invalid " msgtoken
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]"
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.
.TP
.BI "KX " peer " public-key-expired"
The peer's public key has expired.  It's maintainer should have given
you a replacement before now.
.TP
.BI "KX " peer " sending-cookie"
We've received too many bogus pre-challenge messages.  Someone is trying
to flood us with key-exchange messages and make us waste CPU on doing
hard asymmetric crypto sums.
.TP
.BI "KX " peer " unexpected " msgtoken
The message received wasn't appropriate for this stage of the key
exchange process.  This may mean that one of our previous packets got
lost.  For 
.BR pre-challenge ,
it may simply mean that the peer has recently restarted.
.TP
.BI "KX " peer " unknown-challenge"
The peer is asking for an answer to a challenge which we don't know
about.  This may mean that we've been inundated with challenges from
some malicious source
.I who can read our messages
and discarded the valid one.
.TP
.BI "KX " peer " unknown-message 0x" nn
An unknown key-exchange message arrived.
.SS "PEER warnings"
These are largely concerned with management of peers and the low-level
details of the network protocol.  The second word is usually the name of
a peer, or 
.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
.BI "PEER " peer " bad-packet unknown-category 0x" nn
The message category
.I nn
(in hex) isn't understood.  Probably a strange random packet from
somewhere; could be an unlikely bug.
.TP
.BI "PEER " peer " bad-packet unknown-type 0x" nn
The message type
.I nn
(in hex) isn't understood.  Probably a strange random packet from
somewhere; could be an unlikely bug.
.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
key.  There is usually a considerable overlap in the validity periods of
successive session keys, so this shouldn't occur unless the key exchange
takes ages or fails.
.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.
.TP
.BI "PEER \- socket-read-error \-\- " message
An error occurred trying to read an incoming packet.
.TP
.BI "PEER " peer " socket-write-error \-\- " message
An error occurred attempting to send a network packet.  We lost that
one.
.SS "SERVER warnings"
These indicate problems concerning the server process as a whole.
.TP
.BI "SERVER ignore signal " name
A signal arrived, but the server ignored it.  Currently this happens for
.B SIGHUP
because that's a popular way of telling daemons to re-read their
configuration files.  Since
.B tripe
re-reads its keyrings automatically and has no other configuration
files, it's not relevant, but it seemed better to ignore the signal than
let the server die.
.TP
.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
A signal arrived and
.B tripe
is going to quit.
.TP
.BI "SERVER quit admin-request"
A client of the administration interface issued a
.B QUIT
command.
.TP
.BI "SERVER select-error \-\- " message
An error occurred in the server's main event loop.  This is bad: if it
happens too many times, the server will abort.
.SS "SYMM warnings"
These are concerned with the symmetric encryption and decryption
process.
.TP
.BI "SYMM replay old-sequence"
A packet was received with an old sequence number.  It may just have
been delayed or duplicated, or it may have been an attempt at a replay
attack.
.TP
.BI "SYMM replay duplicated-sequence"
A packet was received with a sequence number we've definitely seen
before.  It may be an accidental duplication because the 'net is like
that, or a deliberate attempt at a replay.
.SS "TUN warnings"
These concern the workings of the system-specific tunnel driver.  The
second word is the name of the tunnel interface in question, or
.RB ` \- '
if none.
.TP
.BI "TUN \- bsd no-tunnel-devices"
The driver couldn't find an available tunnel device.  Maybe if you
create some more 
.BI /dev/tun nn
files, it will work.
.TP
.BI "TUN - open-error " device " \-\- " message
An attempt to open the tunnel device file
.I device
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.
.TP
.BI "TUN \- unet config-error \-\- " message
Configuring the Linux Unet interface failed.  Unet is obsolete and
shouldn't be used any more.
.TP
.BI "TUN \- unet getinfo-error \-\- " message
Reading information about the Unet interface failed.  Unet is obsolete
and shouldn't be used any more.
.TP
.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.
.SH "SEE ALSO"
.BR tripectl (1),
.BR tripe (8).
.PP
.IR "The Trivial IP Encryption Protocol" .
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>