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