chiark / gitweb /
General overhaul of tunnelling: allow multiple tunnel drivers in one daemon,
[tripe] / doc / tripe-admin.5
CommitLineData
d6623498 1.\" -*-nroff-*-
2.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
3.SH NAME
4tripe-admin \- administrator commands for TrIPE
5.SH DESCRIPTION
6This manual page describes the administration interface provided by the
7.BR tripe (8)
8daemon.
9.PP
10The
11.BR tripectl (8)
12program can be used either interactively or in scripts to communicate
13with the server using this interface. Alternatively, simple custom
14clients can be written in scripting languages such as Perl, Python or
15Tcl, or more advanced clients such as GUI monitors can be written in C
16with little difficulty.
17.PP
18By default, the server listens for admin connections on the Unix-domain
19socket
20.BR /var/lib/tripe/tripesock .
21Administration commands use a simple textual protocol. Each client
22command or server response consists of a line of ASCII text terminated
8bc63560 23by a single linefeed character. No command may be longer than 255
24characters.
d6623498 25.SS "General structure"
26Each command or response line consists of a sequence of
27whitespace-separated words. The number and nature of whitespace
28characters separating two words in a client command is not significant;
29the server always uses a single space character. The first word in a
30line is a
31.I keyword
32identifying the type of command or response contained. Keywords in
33client commands are not case-sensitive; the server always uses uppercase
34for its keywords.
35.SS "Server responses"
36For client command, the server responds with zero or more
37.B INFO
38lines, followed by either an
39.B OK
40line or a
41.B FAIL
42line. Each
43.B INFO
44provides information requested in the command. An
45.B OK
46response contains no further data. A
47.B FAIL
3cdc3f3a 48code is followed by a machine-readable explanation of why the command
d6623498 49failed.
50.PP
3cdc3f3a 51In addition, there are three types of asynchronous messages which
d6623498 52aren't associated with any particular command. The
53.B WARN
3cdc3f3a 54message contains a machine-readable message warning of an error
d6623498 55encountered while processing a command, unexpected or unusual behaviour
56by a peer, or a possible attack by an adversary. Under normal
57conditions, the server shouldn't emit any warnings. The
58.B TRACE
3cdc3f3a 59message contains a human-readable tracing message containing diagnostic
d6623498 60information. Trace messages are controlled using the
61.B \-T
62command-line option to the server, or the
63.B TRACE
64administration command (see below). Support for tracing can be disabled
65when the package is being configured, and may not be available in your
3cdc3f3a 66version. Finally, the
67.B NOTE
68message is a machine-readable notification about some routine but
69interesting event such as creation or destruction of peers.
70.PP
71The presence of asynchronous messages can be controlled using the
72.B WATCH
73command.
74.SS "Network addresses"
75A network address is a sequence of words. The first is a token
76identifying the network address family. The length of an address and
77the meanings of the subsequent words depend on the address family.
78Address family tokens are not case-sensitive on input; on output, they
79are always in upper-case.
80.PP
81At present, only one address family is understood.
82.TP
83.BI "INET " address " " port
84An Internet socket, naming an IPv4 address and UDP port. On output, the
85address is always in numeric dotted-quad form, and the port is given as
86a plain number. On input, DNS hostnames and symbolic port names are
87permitted. Name resolution does not block the main server, but will
88block the requesting client. This hopefully makes life simpler for
89stupid clients. Complex clients which don't wish to be held up can open
90extra connections or do the resolution themselves.)
91.PP
92If, on input, no recognised address family token is found, the following
93words are assumed to represent an
94.B INET
95address.
96.SH "COMMAND REFERENCE"
d6623498 97The commands provided are:
98.TP
42da2a58 99.BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
3cdc3f3a 100Adds a new peer. The peer is given the name
101.IR peer ;
102the peer's public key is assumed to be in the file
103.B keyring.pub
104(or whatever alternative file was specified in the
105.B \-K
106option on the command line). The
107.I address
108is the network address (see above for the format) at which the peer can
42da2a58 109be contacted. The following options are recognised.
110.RS
111.TP
112.BI "-tunnel " tunnel
113Use the named tunnel driver, rather than the default.
114.RE
3cdc3f3a 115.TP
116.BI "ADDR " peer
117Emits an
118.B INFO
119line reporting the IP address and port number stored for
120.IR peer .
121.TP
122.B "DAEMON"
123Causes the server to disassociate itself from its terminal and become a
124background task. This only works once. A warning is issued.
125.TP
d6623498 126.B "HELP"
127Causes the server to emit an
128.B INFO
129line for each command it supports. Each line lists the command name,
130followed by the names of the arguments. This may be helpful as a memory
131aid for interactive use, or for program clients probing for features.
3cdc3f3a 132.TP
133.BI "IFNAME " peer
134Emits an
135.B INFO
136line containing the name of the network interface used to collect IP
137packets which are to be encrypted and sent to
138.IR peer .
139Used by configuration scripts so that they can set up routing tables
140appropriately after adding new peers.
141.TP
142.BI "KILL " peer
143Causes the server to forget all about
144.IR peer .
145All keys are destroyed, and no more packets are sent. No notification
146is sent to the peer: if it's important that the peer be notified, you
147must think of a way to do that yourself.
148.TP
149.B "LIST"
150For each currently-known peer, an
151.B INFO
152line is written containing the peer's name, as given to
153.BR ADD .
154.TP
bd58d532 155.BI "NOTIFY " tokens\fR...
156Issues a
157.B USER
158notification to all interested administration clients.
159.TP
3cdc3f3a 160.B "PORT"
161Emits an
162.B INFO
163line containing just the number of the UDP port used by the
164.B tripe
165server. If you've allowed your server to allocate a port dynamically,
166this is how to find out which one it chose.
167.TP
168.B "QUIT"
169Instructs the server to exit immediately. A warning is sent.
170.TP
171.BI "STATS " peer
172Emits a number of
173.B INFO
174lines, each containing one or more statistics in the form
175.IB name = value \fR.
176The statistics-gathering is experimental and subject to change.
d6623498 177.TP
178.BR "TRACE " [\fIoptions\fP]
179A trace argument consists of a string of letters (listed below)
180selecting trace outputs, optionally interspersed with
181.RB ` + '
182to enable, or
183.RB ` \- '
184to disable, the subsequently listed outputs; the initial behaviour is to
185enable listed outputs. For example, the string
186.B ra\-st+x
187enables tracing of peer management, admin-connection handling and
188key-exchange processing, and disables tracing of symmetric keyset
189management and the system-specific tunnel driver. If no argument is
190given, a table is returned showing the available tracing option letters
191and their meanings. Programs should not attempt to parse this table:
192its format is not guaranteed to remain the same.
193.RS
2d752320 194.PP
d6623498 195Currently, the following tracing options are supported:
196.TP
197.B t
198Tunnel events: reception of packets to be encrypted, and injection of
199successfully-decrypted packets.
200.TP
201.B r
202Peer management events: creation and destruction of peer attachments,
203and arrival of messages.
204.TP
205.B a
206Administration interface: acceptance of new connections, and handling of
207the backgroud name-resolution required by the
208.B ADD
209command.
210.TP
211.B p
212Display contents of packets sent and received by the tunnel and/or peer
213modules.
214.TP
215.B c
216Display inputs, outputs and intermediate results of cryptographic
217operations. This includes plaintext and key material. Use with
218caution.
219.TP
220.B s
221Handling of symmetric keysets: creation and expiry of keysets, and
222encryption and decryption of messages.
223.TP
224.B x
225Key exchange: reception, parsing and emission of key exchange messages.
226.TP
227.B m
228Key management: loading keys and checking for file modifications.
229.PP
230Note that the
231.B p
232(packet contents)
233and
234.B c
235(crypto details)
236outputs provide extra detail for other outputs. Specifying
237.B p
238without
239.B r
240or
241.B t
242isn't useful; neither is specifying
243.B c
244without one of
245.BR s ,
246.B x
247or
248.BR m .
3cdc3f3a 249.TP
250.B A
251All of the above.
d6623498 252.RE
253.TP
3cdc3f3a 254.BR "WATCH " [\fIoptions\fP]
255Enables or disables asynchronous messages
256.IR "for the current connection only" .
257This command has no effect on other connections. A watch argument
258consists of a string of letters (listed below) selecting message types,
259optionally interspersed with
260.RB ` + '
261to enable, or
262.RB ` \- '
263to disable, the subsequently listed types, similar to
264.B trace
265above. The default watch state for the connection the server opens
266automatically on stdin/stdout is to show warnings and trace messages;
267other connections show no asynchronous messages. (This is done in order
268to guarantee that a program reading the server's stdout does not miss
269any warnings.)
270.RS
271.PP
272Currently, the following watch options are supported:
273.TP
274.B t
275.B TRACE
276messages.
277.TP
278.B n
279.B NOTE
280messages.
281.TP
282.B w
283.B WARN
284messages.
285.TP
286.B a
287All of the above.
288.RE
289.TP
290.B "VERSION"
291Causes the server to emit an
d6623498 292.B INFO
3cdc3f3a 293line stating its software version, as two words: the server name, and
294its version string. The server name
d6623498 295.B tripe
3cdc3f3a 296is reserved to the Straylight/Edgeware implementation.
bd58d532 297.TP
298.BI "WARN " tokens\fR...
299Issues a
300.B USER
301warning to all interested administration clients.
3cdc3f3a 302.SH "ERROR MESSAGES"
303The following
304.B FAIL
305messages are sent to clients as a result of errors during command
306processing.
d6623498 307.TP
3cdc3f3a 308.BI "already-daemon"
309(For
310.BR DAEMON .)
311The
312.B tripe
313server is already running as a daemon.
d6623498 314.TP
3cdc3f3a 315.BI "bad-syntax \-\- " message
316(For any command.) The command couldn't be understood: e.g., the number
317of arguments was wrong.
d6623498 318.TP
3cdc3f3a 319.BI "bad-trace-option " char
320(For
321.BR TRACE .)
322An unknown trace option was requested.
323.TP
324.BI "bad-watch-option " char
325(For
326.BR WATCH .)
327An unknown watch option was requested.
328.TP
329.BI "daemon-error \-\- " message
330(For
331.BR DAEMON .)
332An error occurred during the attempt to become a daemon, as reported by
333.IR message .
334.TP
335.BI "invalid-port " number
336(For
337.BR ADD .)
338The given port number is out of range.
339.TP
340.BI "peer-create-fail " peer
341(For
342.BR ADD .)
343Adding
344.I peer
345failed for some reason. A warning should have been emitted explaining
346why.
347.TP
348.BI "peer-exists " peer
349(For
350.BR ADD .)
351There is already a peer named
d6623498 352.IR peer .
353.TP
3cdc3f3a 354.BI "resolve-error " hostname
355(For
356.BR ADD .)
357The DNS name
358.I hostname
359could not be resolved.
360.TP
361.BI "resolver-timeout " hostname
362(For
363.BR ADD .)
364The DNS name
365.I hostname
366took too long to resolve.
367.TP
368.BI "unknown-command " token
369The command
370.B token
371was not recognised.
372.TP
373.BI "unknown-peer " name
374(For
375.BR ADDR ,
376.BR IFNAME ,
377.BR KILL ,
378and
379.BR STATS .)
380There is no peer called
381.IR name .
382.TP
383.BI "unknown-service " service
384(For
385.BR ADD .)
386The service name
387.I service
388couldn't be found in
389.BR /etc/services .
390.SH "NOTIFICATIONS"
391The following notifications are sent to clients who request them.
392.TP
42da2a58 393.BI "ADD " peer " " ifname " " address \fR...
3cdc3f3a 394A new peer has been added. The peer's name is
42da2a58 395.IR peer ,
396its tunnel is network interface
397.IR ifname ,
3cdc3f3a 398and its network address is
399.IR address .
400.TP
401.BI "DAEMON"
402The server has forked off into the sunset and become a daemon.
d6623498 403.TP
404.BI "KILL " peer
3cdc3f3a 405The peer
406.I peer
407has been killed.
d6623498 408.TP
3cdc3f3a 409.BI "KXDONE " peer
410Key exchange with
411.I peer
412finished successfully.
413.TP
414.BI "KXSTART " peer
415Key exchange with
416.I peer
417has begun or restarted. If key exchange keeps failing, this message
418will be repeated periodically.
bd58d532 419.TP
420.BI "USER " tokens\fR...
421An administration client issued a notification using the
422.B NOTIFY
423command.
3cdc3f3a 424.SH "WARNINGS"
425There are many possible warnings. They are categorized according to
426their first tokens.
427.SS "ABORT warnings"
428These all indicate that the
d6623498 429.B tripe
3cdc3f3a 430server has become unable to continue. If enabled, the server will dump
431core in its configuration directory.
d6623498 432.TP
3cdc3f3a 433.BI "ABORT repeated-select-errors"
434The main event loop is repeatedly failing. If the server doesn't quit,
435it will probably waste all available CPU doing nothing.
436.SS "ADMIN warnings"
437These indicate a problem with the administration socket interface.
438.TP
439.BI "ADMIN accept-error \-\- " message
440There was an error while attempting to accept a connection from a new
441client.
442.TP
443.BI "ADMIN client-read-error \-\- " message
444There was an error sending data to a client. The connection to the
445client has been closed.
446.SS "KEYMGMT warnings"
447These indicate a problem with the keyring files, or the keys stored in
448them.
449.TP
450.BI "KEYMGMT bad-private-key \-\- " message
451The private key could not be read, or failed a consistency check. If
452there was a problem with the file, usually there will have been
453.B key-file-error
454warnings before this.
455.TP
456.BI "KEYMGMT bad-public-keyring \-\- " message
457The public keyring couldn't be read. Usually, there will have been
458.B key-file-error
459warnings before this.
460.TP
461.BI "KEYMGMT key-file-error " file ":" line " \-\- " message
462Reports a specific error with the named keyring file. This probably
463indicates a bug in
464.BR key (1).
465.TP
466.BI "KEYMGMT public-key " tag " " tokens\fR...
467These messages all indicate a problem with the public key named
468.IR tag .
469.TP
470.BI "KEYMGMT public-key " tag " algorithm-mismatch"
471The algorithms specified on the public key don't match the ones for our
472private key. All the peers in a network have to use the same
473algorithms.
474.TP
475.BI "KEYMGMT public-key " tag " bad \-\- " message
476The public key couldn't be read, or is invalid.
477.TP
478.BI "KEYMGMT public-key " tag " bad-public-group-element"
479The public key is invalid. This may indicate a malicious attempt to
480introduce a bogus key.
481.TP
482.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
483The algorithms listed on the public key couldn't be understood. The
484algorithm selection attributes are probably malformed and need fixing.
485.TP
486.BI "KEYMGMT public-key " tag " incorrect-group"
487The public key doesn't use the same group as our private key. All the
488peers in a network have to use the same group.
489.TP
490.BI "KEYMGMT public-key " tag " not-found"
491The public key for peer
492.I tag
493wasn't in the public keyring.
494.TP
495.BI "KEYMGMT public-key " tag " unknown-type"
496The type of the public key isn't understood. Maybe you need to upgrade
497your copy of
498.BR tripe .
499(Even if you do, you'll have to regenerate your keys.)
500.SS "KX warnings"
501These indicate problems during key-exchange. Many indicate either a bug
502in the server (either yours or the remote one), or some kind of attack
503in progress. All name a
504.I peer
505as the second token: this is the peer the packet is apparently from,
506though it may have been sent by an attacker instead.
507.PP
508In the descriptions below,
509.I msgtoken
510is one of the tokens
511.BR pre-challenge ,
512.BR cookie ,
513.BR challenge ,
514.BR reply ,
515.BR switch-rq ,
516or
517.BR switch-ok .
518.TP
519.BI "KX " peer " bad-expected-reply-log"
520The challenges
521.B tripe
522uses in its protocol contain a check value which proves that the
523challenge is honest. This message indicates that the check value
524supplied is wrong: someone is attempting to use bogus challenges to
525persuade your
526.B tripe
527server to leak private key information. No chance!
528.TP
bd58d532 529.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
3cdc3f3a 530A symmetrically-encrypted portion of a key-exchange message failed to
531decrypt.
532.TP
533.BI "KX " peer " invalid " msgtoken
534A key-exchange message was malformed. This almost certainly indicates a
535bug somewhere.
536.TP
bd58d532 537.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
3cdc3f3a 538A message didn't contain the right magic data. This may be a replay of
539some old exchange, or random packets being sent in an attempt to waste
540CPU.
541.TP
542.BI "KX " peer " public-key-expired"
543The peer's public key has expired. It's maintainer should have given
544you a replacement before now.
545.TP
546.BI "KX " peer " sending-cookie"
547We've received too many bogus pre-challenge messages. Someone is trying
548to flood us with key-exchange messages and make us waste CPU on doing
549hard asymmetric crypto sums.
550.TP
551.BI "KX " peer " unexpected " msgtoken
552The message received wasn't appropriate for this stage of the key
553exchange process. This may mean that one of our previous packets got
554lost. For
555.BR pre-challenge ,
556it may simply mean that the peer has recently restarted.
557.TP
558.BI "KX " peer " unknown-challenge"
559The peer is asking for an answer to a challenge which we don't know
560about. This may mean that we've been inundated with challenges from
561some malicious source
562.I who can read our messages
563and discarded the valid one.
564.TP
565.BI "KX " peer " unknown-message 0x" nn
566An unknown key-exchange message arrived.
567.SS "PEER warnings"
568These are largely concerned with management of peers and the low-level
569details of the network protocol. The second word is usually the name of
570a peer, or
571.RB ` \- '
572if none is relevant.
573.TP
574.BI "PEER \- unexpected-source " address\fR...
575A packet arrived from
576.I address
577(a network address \(en see above), but no peer is known at that
578address. This may indicate a misconfiguration, or simply be a result of
579one end of a connection being set up before the other.
580.TP
581.BI "PEER " peer " bad-packet no-type"
582An empty packet arrived. This is very strange.
583.TP
584.BI "PEER " peer " bad-packet unknown-category 0x" nn
585The message category
586.I nn
587(in hex) isn't understood. Probably a strange random packet from
588somewhere; could be an unlikely bug.
589.TP
590.BI "PEER " peer " bad-packet unknown-type 0x" nn
591The message type
592.I nn
593(in hex) isn't understood. Probably a strange random packet from
594somewhere; could be an unlikely bug.
595.TP
596.BI "PEER " peer " decrypt-failed"
597An encrypted IP packet failed to decrypt. It may have been mangled in
598transit, or may be a very old packet from an expired previous session
599key. There is usually a considerable overlap in the validity periods of
600successive session keys, so this shouldn't occur unless the key exchange
601takes ages or fails.
602.TP
603.BI "PEER " peer " packet-build-failed"
604There wasn't enough space in our buffer to put the packet we wanted to
605send. Shouldn't happen.
606.TP
607.BI "PEER \- socket-read-error \-\- " message
608An error occurred trying to read an incoming packet.
609.TP
610.BI "PEER " peer " socket-write-error \-\- " message
611An error occurred attempting to send a network packet. We lost that
612one.
613.SS "SERVER warnings"
614These indicate problems concerning the server process as a whole.
615.TP
616.BI "SERVER ignore signal " name
617A signal arrived, but the server ignored it. Currently this happens for
618.B SIGHUP
619because that's a popular way of telling daemons to re-read their
620configuration files. Since
621.B tripe
622re-reads its keyrings automatically and has no other configuration
623files, it's not relevant, but it seemed better to ignore the signal than
624let the server die.
625.TP
626.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
627A signal arrived and
628.B tripe
629is going to quit.
630.TP
631.BI "SERVER quit admin-request"
632A client of the administration interface issued a
633.B QUIT
634command.
635.TP
636.BI "SERVER select-error \-\- " message
637An error occurred in the server's main event loop. This is bad: if it
638happens too many times, the server will abort.
639.SS "SYMM warnings"
640These are concerned with the symmetric encryption and decryption
641process.
642.TP
643.BI "SYMM replay old-sequence"
644A packet was received with an old sequence number. It may just have
645been delayed or duplicated, or it may have been an attempt at a replay
646attack.
647.TP
648.BI "SYMM replay duplicated-sequence"
649A packet was received with a sequence number we've definitely seen
650before. It may be an accidental duplication because the 'net is like
651that, or a deliberate attempt at a replay.
652.SS "TUN warnings"
653These concern the workings of the system-specific tunnel driver. The
654second word is the name of the tunnel interface in question, or
655.RB ` \- '
656if none.
657.TP
658.BI "TUN \- bsd no-tunnel-devices"
659The driver couldn't find an available tunnel device. Maybe if you
660create some more
661.BI /dev/tun nn
662files, it will work.
663.TP
664.BI "TUN - open-error " device " \-\- " message
665An attempt to open the tunnel device file
666.I device
667failed.
668.TP
3cdc3f3a 669.BI "TUN \- linux config-error \-\- " message
670Configuring the Linux TUN/TAP interface failed.
671.TP
42da2a58 672.BI "TUN " ifname " read-error \-\- " message
673Reading from the tunnel device failed.
3cdc3f3a 674.TP
42da2a58 675.BI "TUN " ifname " slip bad-escape"
676The SLIP driver encountered a escaped byte it wasn't expecting to see.
677The erroneous packet will be ignored.
b9066fbb 678.TP
679.BI "TUN " ifname " slip eof"
680The SLIP driver encountered end-of-file on its input descriptor.
681Pending data is discarded, and no attempt is made to read any more data
682from that interface ever.
683.TP
684.BI "TUN " ifname " slip escape-end"
685The SLIP driver encountered an escaped `end' marker. This probably
686means that someone's been sending it junk. The erroneous packet is
687discarded, and we hope that we've rediscovered synchronization.
688.TP
42da2a58 689.BI "TUN \- slip fork-error \-\- " message
690The SLIP driver encountered an error forking a child process while
691allocating a new dynamic interface.
692.TP
693.BI "TUN \- slip no-slip-interfaces"
694The driver ran out of static SLIP interfaces. Either preallocate more,
695or use dynamic SLIP interface allocation.
b9066fbb 696.TP
697.BI "TUN " ifname " slip overflow"
698The SLIP driver gave up reading a packet because it got too large.
42da2a58 699.TP
700.BI "TUN \- slip pipe-error \-\- " message
701The SLIP driver encountered an error creating pipes while allocating a
702new dynamic interface.
703.TP
704.BI "TUN \- slip read-ifname-failed \-\- " message
705The SLIP driver encountered an error reading the name of a dynamically
706allocated interface. Maybe the allocation script is broken.
707.TP
708.BI "TUN \- unet config-error \-\- " message
709Configuring the Linux Unet interface failed. Unet is obsolete and
710shouldn't be used any more.
711.TP
712.BI "TUN \- unet getinfo-error \-\- " message
713Reading information about the Unet interface failed. Unet is obsolete
714and shouldn't be used any more.
715.TP
716.BI "TUN \- unet ifname-too-long \-\- " message
717The Unet interface's name overflowed, so we couldn't read it properly.
718Unet is obsolete and shouldn't be used any more.
bd58d532 719.SS "USER warnings"
720These are issued by administration clients using the
721.B WARN
722command.
723.TP
724.BI "USER " tokens\fR...
725An administration client issued a warning.
d6623498 726.SH "SEE ALSO"
727.BR tripectl (1),
728.BR tripe (8).
729.PP
3cdc3f3a 730.IR "The Trivial IP Encryption Protocol" .
d6623498 731.SH "AUTHOR"
d36eda2a 732Mark Wooding, <mdw@distorted.org.uk>