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