. fam P
. \}
.\}
+.
+.de SP
+.TP
+..
.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH NAME
tripe-admin \- administrator commands for TrIPE
Lowercase key letters control individual message types. Uppercase key
letters control collections of message types.
.SH "COMMAND REFERENCE"
+.\"* 10 Commands
The commands provided are:
-.TP
+.SP
.BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
Adds a new peer. The peer is given the name
.IR peer ;
is the network address (see above for the format) at which the peer can
be contacted. The following options are recognised.
.RS
+.\"+opts
.TP
.BI "\-background " tag
Run the command in the background, using the given
.TP
.BI "\-tunnel " tunnel
Use the named tunnel driver, rather than the default.
+.\"-opts
.RE
-.TP
+.SP
.BI "ADDR " peer
Emits an
.B INFO
line reporting the IP address and port number stored for
.IR peer .
-.TP
+.SP
.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
+.SP
.B "DAEMON"
Causes the server to disassociate itself from its terminal and become a
background task. This only works once. A warning is issued.
responses are the same as for the
.B PING
command.
-.TP
+.SP
.BI "FORCEKX " peer
Requests the server to begin a new key exchange with
.I peer
immediately.
-.TP
+.SP
.B "GETCHAL"
Requests a challenge. The challenge is returned in an
.B INFO
line, as a base64-encoded string. See
.BR CHECKCHAL .
-.TP
+.SP
.BI "GREET " peer " " challenge
Sends a greeting packet containing the
.I challenge
.IR peer .
The expectation is that this will cause the peer to recognize us and
begin a key-exchange.
-.TP
+.SP
.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
+.SP
.BI "IFNAME " peer
Emits an
.B INFO
.IR peer .
Used by configuration scripts so that they can set up routing tables
appropriately after adding new peers.
-.TP
+.SP
.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
+.SP
.B "LIST"
For each currently-known peer, an
.B INFO
line is written containing the peer's name, as given to
.BR ADD .
-.TP
+.SP
.BI "NOTIFY " tokens\fR...
Issues a
.B USER
notification to all interested administration clients.
-.TP
+.SP
.BI "PEERINFO " peer
Returns information about a peer, in key-value form. The following keys
are returned.
The keepalive interval, in seconds, or zero if no keepalives are to be
sent.
.RE
-.TP
+.SP
.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
.IP
Options recognized for this command are:
.RS
+.\"+opts
.TP
.BI "\-background " tag
Run the command in the background, using the given
time format is the same as for the
.B "ADD \-keepalive"
option.)
+.\"-opts
.RE
-.TP
+.SP
.B "PORT"
Emits an
.B INFO
.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
+.SP
.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
+.SP
.B "QUIT"
Instructs the server to exit immediately. A warning is sent.
-.TP
+.SP
.B "SERVINFO"
Returns information about the server, in the form of key-value pairs.
The following keys are used.
.BR nil ,
if the server has or hasn't (respectively) become a daemon.
.RE
-.TP
+.SP
.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
+.SP
.BR "TRACE " [\fIoptions\fP]
Selects trace outputs: see
.B "Trace lists"
or
.BR m .
.RE
-.TP
+.SP
.B "TUNNELS"
For each available tunnel driver, an
.B INFO
line is printed giving its name.
-.TP
+.SP
.B "VERSION"
Causes the server to emit an
.B INFO
its version string. The server name
.B tripe
is reserved to the Straylight/Edgeware implementation.
-.TP
+.SP
.BR "WATCH " [\fIoptions\fP]
Enables or disables asynchronous messages
.IR "for the current connection only" .
.B A
All of the above.
.RE
-.TP
+.SP
.BI "WARN " tokens\fR...
Issues a
.B USER
warning to all interested administration clients.
.SH "ERROR MESSAGES"
+.\"* 20 Error messages (FAIL codes)
The following
.B FAIL
(or
.BR BGFAIL )
messages are sent to clients as a result of errors during command
processing.
-.TP
+.SP
.BI "already-daemon"
(For
.BR DAEMON .)
The
.B tripe
server is already running as a daemon.
-.TP
+.SP
.BI "bad-addr-syntax " message
(For commands accepting socket addresses.) The address couldn't be
understood.
-.TP
+.SP
.BI "bad-syntax " cmd " " message
(For any command.) The command couldn't be understood: e.g., the number
of arguments was wrong.
-.TP
+.SP
.BI "bad-time-spec " word
The
.I word
or
.BR s ,
for days, hours, minutes, or seconds, respectively.
-.TP
+.SP
.BI "bad-trace-option " char
(For
.BR TRACE .)
An unknown trace option was requested.
-.TP
+.SP
.BI "bad-watch-option " char
(For
.BR WATCH .)
An unknown watch option was requested.
-.TP
+.SP
.BI "daemon-error " ecode " " message
(For
.BR DAEMON .)
An error occurred during the attempt to become a daemon, as reported by
.IR message .
-.TP
+.SP
.BI "invalid-port " number
(For
.BR ADD .)
The given port number is out of range.
-.TP
+.SP
.BI "peer-create-fail " peer
(For
.BR ADD .)
.I peer
failed for some reason. A warning should have been emitted explaining
why.
-.TP
+.SP
.BI "peer-exists " peer
(For
.BR ADD .)
There is already a peer named
.IR peer .
-.TP
+.SP
.B "ping-send-failed"
The attempt to send a ping packet failed, probably due to lack of
encryption keys.
-.TP
+.SP
.BI "resolve-error " hostname
(For
.BR ADD .)
The DNS name
.I hostname
could not be resolved.
-.TP
+.SP
.BI "resolver-timeout " hostname
(For
.BR ADD .)
The DNS name
.I hostname
took too long to resolve.
-.TP
+.SP
.BI "unknown-command " token
The command
.B token
was not recognised.
-.TP
+.SP
.BI "unknown-peer " name
(For
.BR ADDR ,
.BR STATS .)
There is no peer called
.IR name .
-.TP
+.SP
.BI "unknown-service " service
(For
.BR ADD .)
couldn't be found in
.BR /etc/services .
.SH "NOTIFICATIONS"
+.\"* 30 Notification broadcasts (NOTE codes)
The following notifications are sent to clients who request them.
-.TP
+.SP
.BI "ADD " peer " " ifname " " address \fR...
A new peer has been added. The peer's name is
.IR peer ,
.IR ifname ,
and its network address is
.IR address .
-.TP
+.SP
.BI "DAEMON"
The server has forked off into the sunset and become a daemon.
-.TP
+.SP
.BI "GREET " challenge " " address \fR...
A valid greeting was received, with the given challenge (exactly as it
was returned by
.B GETCHAL
earlier).
-.TP
+.SP
.BI "KILL " peer
The peer
.I peer
has been killed.
-.TP
+.SP
.BI "KXDONE " peer
Key exchange with
.I peer
finished successfully.
-.TP
+.SP
.BI "KXSTART " peer
Key exchange with
.I peer
has begun or restarted. If key exchange keeps failing, this message
will be repeated periodically.
-.TP
+.SP
.BI "USER " tokens\fR...
An administration client issued a notification using the
.B NOTIFY
command.
.SH "WARNINGS"
+.\"* 40 Warning broadcasts (WARN codes)
+.\"+sep
There are many possible warnings. They are categorized according to
their first tokens.
.PP
.B tripe
server has become unable to continue. If enabled, the server will dump
core in its configuration directory.
-.TP
+.SP
.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
+.SP
.BI "ADMIN accept-error " ecode " " message
There was an error while attempting to accept a connection from a new
client.
-.TP
+.SP
.BI "ADMIN client-write-error " ecode " " message
There was an error sending data to a client. The connection to the
client has been closed.
These indicate errors in challenges, either in the
.B CHECKCHAL
command or in greeting packets.
-.TP
+.SP
.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
+.SP
.B "CHAL incorrect-tag"
Challenge received contained the wrong authentication data. It might be
very stale, or a forgery.
-.TP
+.SP
.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
+.SP
.B "CHAL replay duplicated-sequence"
Challenge received was a definite replay of an old challenge. Someone's
up to something!
-.TP
+.SP
.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.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.BI "KEYMGMT public-key " tag " " tokens\fR...
These messages all indicate a problem with the public key named
.IR tag .
-.TP
+.SP
.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
+.SP
.BI "KEYMGMT public-key " tag " bad " message
The public key couldn't be read, or is invalid.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.BI "KEYMGMT public-key " tag " not-found"
The public key for peer
.I tag
wasn't in the public keyring.
-.TP
+.SP
.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 switch-rq ,
or
.BR switch-ok .
-.TP
+.SP
.BI "KX " peer " bad-expected-reply-log"
The challenges
.B tripe
persuade your
.B tripe
server to leak private key information. No chance!
-.TP
+.SP
.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
A symmetrically-encrypted portion of a key-exchange message failed to
decrypt.
-.TP
+.SP
.BI "KX " peer " invalid " msgtoken
A key-exchange message was malformed. This almost certainly indicates a
bug somewhere.
-.TP
+.SP
.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.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.BI "KX " peer " unknown-message 0x" nn
An unknown key-exchange message arrived.
.SS "PEER warnings"
a peer, or
.RB ` \- '
if none is relevant.
-.TP
+.SP
.BI "PEER " peer " bad-packet no-type"
An empty packet arrived. This is very strange.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.BI "PEER " peer " malformed-encrypted-ping"
The peer sent a ping response which is hopelessly invalid. There's
definitely a bug somewhere.
-.TP
+.SP
.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
+.SP
.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
+.SP
.BI "PEER \- socket-read-error " ecode " " message
An error occurred trying to read an incoming packet.
-.TP
+.SP
.BI "PEER " peer " socket-write-error " ecode " " message
An error occurred attempting to send a network packet. We lost that
one.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
there are bad people trying to confuse you.
.SS "SERVER warnings"
These indicate problems concerning the server process as a whole.
-.TP
+.SP
.BI "SERVER ignore signal " name
A signal arrived, but the server ignored it. Currently this happens for
.B SIGHUP
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
+.SP
.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
A signal arrived and
.B tripe
is going to quit.
-.TP
+.SP
.BI "SERVER quit admin-request"
A client of the administration interface issued a
.B QUIT
command.
-.TP
+.SP
.BI "SERVER select-error " ecode " " 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
+.SP
.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
+.SP
.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
second word is the name of the tunnel interface in question, or
.RB ` \- '
if none.
-.TP
+.SP
.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
+.SP
.BI "TUN - " tun-name " open-error " device " " ecode " " message
An attempt to open the tunnel device file
.I device
failed.
-.TP
+.SP
.BI "TUN \- linux config-error " ecode " " message
Configuring the Linux TUN/TAP interface failed.
-.TP
+.SP
.BI "TUN " ifname " " tun-name " read-error " ecode " " message
Reading from the tunnel device failed.
-.TP
+.SP
.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
+.SP
.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
+.SP
.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
+.SP
.BI "TUN \- slip fork-error " ecode " " message
The SLIP driver encountered an error forking a child process while
allocating a new dynamic interface.
-.TP
+.SP
.BI "TUN \- slip no-slip-interfaces"
The driver ran out of static SLIP interfaces. Either preallocate more,
or use dynamic SLIP interface allocation.
-.TP
+.SP
.BI "TUN " ifname " slip overflow"
The SLIP driver gave up reading a packet because it got too large.
-.TP
+.SP
.BI "TUN \- slip pipe-error " ecode " " message
The SLIP driver encountered an error creating pipes while allocating a
new dynamic interface.
-.TP
+.SP
.BI "TUN \- slip read-ifname-failed " ecode " " message
The SLIP driver encountered an error reading the name of a dynamically
allocated interface. Maybe the allocation script is broken.
-.TP
+.SP
.BI "TUN \- unet config-error " ecode " " message
Configuring the Linux Unet interface failed. Unet is obsolete and
shouldn't be used any more.
-.TP
+.SP
.BI "TUN \- unet getinfo-error " ecode " " message
Reading information about the Unet interface failed. Unet is obsolete
and shouldn't be used any more.
-.TP
+.SP
.BI "TUN \- unet ifname-too-long"
The Unet interface's name overflowed, so we couldn't read it properly.
Unet is obsolete and shouldn't be used any more.
These are issued by administration clients using the
.B WARN
command.
-.TP
+.SP
.BI "USER " tokens\fR...
An administration client issued a warning.
+.\"-sep
+.SH "SUMMARY"
+.SS "Command responses"
+.nf
+.BI "BGFAIL " tag " " tokens \fR...
+.BI "BGINFO " tag " " tokens \fR...
+.BI "BGOK " tag
+.BI "FAIL " tokens \fR...
+.BI "INFO " tokens \fR...
+.B OK
+.fi
+.\"= summary
.SH "SEE ALSO"
.BR tripectl (1),
.BR tripe (8).