chiark / gitweb /
admin: Improve handling of background jobs.
[tripe] / doc / tripe-admin.5.in
... / ...
CommitLineData
1.\" -*-nroff-*-
2.\"
3.ie t \{\
4. if \n(.g \{\
5. fam P
6. \}
7.\}
8.
9.de SP
10.TP
11..
12.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
13.SH NAME
14tripe-admin \- administrator commands for TrIPE
15.SH DESCRIPTION
16This manual page describes the administration interface provided by the
17.BR tripe (8)
18daemon.
19.PP
20The
21.BR tripectl (8)
22program can be used either interactively or in scripts to communicate
23with the server using this interface. Alternatively, simple custom
24clients can be written in scripting languages such as Perl, Python or
25Tcl, or more advanced clients such as GUI monitors can be written in C
26with little difficulty.
27.PP
28By default, the server listens for admin connections on the Unix-domain
29socket
30.BR /var/lib/tripe/tripesock .
31Administration commands use a textual protocol. Each client command or
32server response consists of a line of ASCII text terminated by a single
33linefeed character. No command may be longer than 255 characters.
34.SS "General structure"
35Each command or response line consists of a sequence of
36whitespace-separated words. The number and nature of whitespace
37characters separating two words in a client command is not significant;
38the server always uses a single space character. The first word in a
39line is a
40.I keyword
41identifying the type of command or response contained. Keywords in
42client commands are not case-sensitive; the server always uses uppercase
43for its keywords.
44.SS "Simple commands"
45For simple client command, the server responds with zero or more
46.B INFO
47lines, followed by either an
48.B OK
49line or a
50.B FAIL
51line. Each
52.B INFO
53provides information requested in the command. An
54.B OK
55response contains no further data. A
56.B FAIL
57code is followed by a machine-readable explanation of why the command
58failed.
59.PP
60Simple command processing is strictly synchronous: the server reads a
61command, processes it, and responds, before reading the next command.
62All commands can be run as simple commands. Long-running commands
63(e.g.,
64.B ADD
65and
66.BR PING )
67block the client until they finish, but the rest of the server continues
68running.
69.SS "Asynchronous messages"
70There are three types of asynchronous messages which
71aren't associated with any particular command.
72.PP
73The
74.B WARN
75message contains a machine-readable message warning of an error
76encountered while processing a command, unexpected or unusual behaviour
77by a peer, or a possible attack by an adversary. Under normal
78conditions, the server shouldn't emit any warnings.
79.PP
80The
81.B TRACE
82message contains a human-readable tracing message containing diagnostic
83information. Trace messages are controlled using the
84.B \-T
85command-line option to the server, or the
86.B TRACE
87administration command (see below). Support for tracing can be disabled
88when the package is being configured, and may not be available in your
89version.
90.PP
91Finally, the
92.B NOTE
93message is a machine-readable notification about some routine but
94interesting event such as creation or destruction of peers.
95.PP
96The presence of asynchronous messages can be controlled using the
97.B WATCH
98command.
99.SS "Background commands"
100Some commands (e.g.,
101.B ADD
102and
103.BR PING )
104take a long time to complete. To prevent these long-running commands
105from tying up a server connection, they can be run in the background.
106Not all commands can be run like this: the ones that can provide a
107.B \-background
108option, which must be supplied with a
109.IR tag .
110.PP
111A command may fail before it starts running in the background. In this
112case, the server emits a
113.B FAIL
114response, as usual. To indicate that a command has started running in
115the background, the server emits a response of the form
116.BI "BGDETACH " tag \fR,
117where
118.I tag
119is the value passed to the
120.B \-background
121option. From this point on, the server is ready to process more
122commands and reply to them.
123.PP
124Responses to background commands are indicated by a line beginning with
125one of the tokens
126.BR BGOK ,
127.BR BGFAIL ,
128or
129.BR BGINFO ,
130followed by the command tag. These correspond to the
131.BR OK ,
132.BR FAIL ,
133and
134.B INFO
135responses for simple commands:
136.B BGINFO
137indicates information from a background command which has not completed
138yet; and
139.B BGOK
140and
141.B BGFAIL
142indicates that a background command succeeded or failed, respectively.
143.PP
144A background command will never issue an
145.B OK
146or
147.B BGINFO
148response: it will always detach and then issue any
149.B BGINFO
150lines followed by
151.B BGOK
152response.
153.SS "Network addresses"
154A network address is a sequence of words. The first is a token
155identifying the network address family. The length of an address and
156the meanings of the subsequent words depend on the address family.
157Address family tokens are not case-sensitive on input; on output, they
158are always in upper-case.
159.PP
160At present, only one address family is understood.
161.TP
162.BI "INET " address " " port
163An Internet socket, naming an IPv4 address and UDP port. On output, the
164address is always in numeric dotted-quad form, and the port is given as
165a plain number. On input, DNS hostnames and symbolic port names are
166permitted. Name resolution does not block the main server, but will
167block the requesting client. This hopefully makes life simpler for
168stupid clients. Complex clients which don't wish to be held up can open
169extra connections or do the resolution themselves.)
170.PP
171If, on input, no recognised address family token is found, the following
172words are assumed to represent an
173.B INET
174address.
175.SS "Key-value output"
176Some commands (e.g.,
177.B STATS
178and
179.BR SERVINFO )
180produce output in the form of
181.IB key = value
182pairs, one per word. Neither the
183.I key
184nor the
185.I value
186contain spaces.
187.SS "Trace lists"
188Commands which enable or disable kinds of output (e.g.,
189.B TRACE
190and
191.BR WATCH )
192work in similar ways. They take a single optional argument, which
193consists of a string of letters selecting message types, optionally
194interspersed with
195.RB ` + '
196to enable, or
197.RB ` \- '
198to disable, the subsequently listed types.
199.PP
200If the argument is omitted, the available message types are displayed,
201one to an
202.B INFO
203line, in a fixed-column format. Column zero contains the key letter for
204selecting that message type; column one contains either a space or a
205.RB ` + '
206sign, if the message type is disabled or enabled respectively; and a
207textual description of the message type begins at column 3 and continues
208to the end of the line.
209.PP
210Lowercase key letters control individual message types. Uppercase key
211letters control collections of message types.
212.SH "COMMAND REFERENCE"
213.\"* 10 Commands
214The commands provided are:
215.SP
216.BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
217Adds a new peer. The peer is given the name
218.IR peer ;
219the peer's public key is assumed to be in the file
220.B keyring.pub
221(or whatever alternative file was specified in the
222.B \-K
223option on the command line). The
224.I address
225is the network address (see above for the format) at which the peer can
226be contacted. The following options are recognised.
227.RS
228.\"+opts
229.TP
230.BI "\-background " tag
231Run the command in the background, using the given
232.IR tag .
233.TP
234.BI "\-keepalive " time
235Send a no-op packet if we've not sent a packet to the peer in the last
236.I time
237interval. This is useful for persuading port-translating firewalls to
238believe that the `connection' is still active. The
239.I time
240is expressed as a nonnegative integer followed optionally by
241.BR d ,
242.BR h ,
243.BR m ,
244or
245.BR s
246for days, hours, minutes, or seconds respectively; if no suffix is
247given, seconds are assumed.
248.TP
249.BI "\-tunnel " tunnel
250Use the named tunnel driver, rather than the default.
251.\"-opts
252.RE
253.SP
254.BI "ADDR " peer
255Emits an
256.B INFO
257line reporting the IP address and port number stored for
258.IR peer .
259.SP
260.BI "BGCANCEL " tag
261Cancels the background job with the named
262.IR tag .
263.SP
264.BI "CHECKCHAL " challenge
265Verifies a challenge as being one earlier issued by
266.B GETCHAL
267and not previously either passed to
268.B CHECKCHAL
269or in a greeting message.
270.SP
271.B "DAEMON"
272Causes the server to disassociate itself from its terminal and become a
273background task. This only works once. A warning is issued.
274.TP
275.BI "EPING \fR[" options "\fR] " peer
276Sends an encrypted ping to the peer, and expects an encrypted response.
277This checks that the peer is running (and not being impersonated), and
278that it can encrypt and decrypt packets correctly. Options and
279responses are the same as for the
280.B PING
281command.
282.SP
283.BI "FORCEKX " peer
284Requests the server to begin a new key exchange with
285.I peer
286immediately.
287.SP
288.B "GETCHAL"
289Requests a challenge. The challenge is returned in an
290.B INFO
291line, as a base64-encoded string. See
292.BR CHECKCHAL .
293.SP
294.BI "GREET " peer " " challenge
295Sends a greeting packet containing the
296.I challenge
297(base-64 encoded) to the named
298.IR peer .
299The expectation is that this will cause the peer to recognize us and
300begin a key-exchange.
301.SP
302.B "HELP"
303Causes the server to emit an
304.B INFO
305line for each command it supports. Each line lists the command name,
306followed by the names of the arguments. This may be helpful as a memory
307aid for interactive use, or for program clients probing for features.
308.SP
309.BI "IFNAME " peer
310Emits an
311.B INFO
312line containing the name of the network interface used to collect IP
313packets which are to be encrypted and sent to
314.IR peer .
315Used by configuration scripts so that they can set up routing tables
316appropriately after adding new peers.
317.SP
318.B "JOBS"
319Emits an
320.B INFO
321line giving the tag for each outstanding background job.
322.SP
323.BI "KILL " peer
324Causes the server to forget all about
325.IR peer .
326All keys are destroyed, and no more packets are sent. No notification
327is sent to the peer: if it's important that the peer be notified, you
328must think of a way to do that yourself.
329.SP
330.B "LIST"
331For each currently-known peer, an
332.B INFO
333line is written containing the peer's name, as given to
334.BR ADD .
335.SP
336.BI "NOTIFY " tokens\fR...
337Issues a
338.B USER
339notification to all interested administration clients.
340.SP
341.BI "PEERINFO " peer
342Returns information about a peer, in key-value form. The following keys
343are returned.
344.RS
345.TP
346.B tunnel
347The tunnel driver used for this peer.
348.TP
349.B keepalive
350The keepalive interval, in seconds, or zero if no keepalives are to be
351sent.
352.RE
353.SP
354.BI "PING \fR[" options "\fR] " peer
355Send a transport-level ping to the peer. The ping and its response are
356not encrypted or authenticated. This command, possibly in conjunction
357with tracing, is useful for ensuring that UDP packets are actually
358flowing in both directions. See also the
359.B EPING
360command.
361.IP
362An
363.B INFO
364line is printed describing the outcome:
365.RS
366.TP
367.BI "ping-ok " millis
368A response was received
369.I millis
370after the ping was sent.
371.TP
372.BI "ping-timeout"
373No response was received within the time allowed.
374.TP
375.BI "ping-peer-died"
376The peer was killed (probably by another admin connection) before a
377response was received.
378.RE
379.IP
380Options recognized for this command are:
381.RS
382.\"+opts
383.TP
384.BI "\-background " tag
385Run the command in the background, using the given
386.IR tag .
387.TP
388.BI "\-timeout " time
389Wait for
390.I time
391seconds before giving up on a response. The default is 5 seconds. (The
392time format is the same as for the
393.B "ADD \-keepalive"
394option.)
395.\"-opts
396.RE
397.SP
398.B "PORT"
399Emits an
400.B INFO
401line containing just the number of the UDP port used by the
402.B tripe
403server. If you've allowed your server to allocate a port dynamically,
404this is how to find out which one it chose.
405.SP
406.B "RELOAD"
407Instructs the server to recheck its keyring files. The server checks
408these periodically anyway but it may be necessary to force a recheck,
409for example after adding a new peer key.
410.SP
411.B "QUIT"
412Instructs the server to exit immediately. A warning is sent.
413.SP
414.B "SERVINFO"
415Returns information about the server, in the form of key-value pairs.
416The following keys are used.
417.RS
418.TP
419.B implementation
420A keyword naming the implementation of the
421.BR tripe (8)
422server. The current implementation is called
423.BR edgeware-tripe .
424.TP
425.B version
426The server's version number, as reported by
427.BR VERSION .
428.TP
429.B daemon
430Either
431.B t
432or
433.BR nil ,
434if the server has or hasn't (respectively) become a daemon.
435.RE
436.SP
437.BI "SETIFNAME " peer " " new-name
438Informs the server that the
439.IR peer 's
440tunnel-interface name has been changed to
441.IR new-name .
442This is useful if firewalling decisions are made based on interface
443names: a setup script for a particular peer can change the name, and
444then update the server's records so that they're accurate.
445.SP
446.BI "STATS " peer
447Emits a number of
448.B INFO
449lines, each containing one or more statistics in the form
450.IB name = value \fR.
451The statistics-gathering is experimental and subject to change.
452.SP
453.BR "TRACE " [\fIoptions\fP]
454Selects trace outputs: see
455.B "Trace lists"
456above. Message types provided are:
457.RS
458.PP
459Currently, the following tracing options are supported:
460.TP
461.B t
462Tunnel events: reception of packets to be encrypted, and injection of
463successfully-decrypted packets.
464.TP
465.B r
466Peer management events: creation and destruction of peer attachments,
467and arrival of messages.
468.TP
469.B a
470Administration interface: acceptance of new connections, and handling of
471the backgroud name-resolution required by the
472.B ADD
473command.
474.TP
475.B s
476Handling of symmetric keysets: creation and expiry of keysets, and
477encryption and decryption of messages.
478.TP
479.B x
480Key exchange: reception, parsing and emission of key exchange messages.
481.TP
482.B m
483Key management: loading keys and checking for file modifications.
484.TP
485.B l
486Display information about challenge issuing and verification.
487.TP
488.B p
489Display contents of packets sent and received by the tunnel and/or peer
490modules.
491.TP
492.B c
493Display inputs, outputs and intermediate results of cryptographic
494operations. This includes plaintext and key material. Use with
495caution.
496.TP
497.B A
498All of the above.
499.PP
500Note that the
501.B p
502(packet contents)
503and
504.B c
505(crypto details)
506outputs provide extra detail for other outputs. Specifying
507.B p
508without
509.BR r
510or
511.B t
512isn't useful; neither is specifying
513.B c
514without one of
515.BR s ,
516.BR l ,
517.B x
518or
519.BR m .
520.RE
521.SP
522.B "TUNNELS"
523For each available tunnel driver, an
524.B INFO
525line is printed giving its name.
526.SP
527.B "VERSION"
528Causes the server to emit an
529.B INFO
530line stating its software version, as two words: the server name, and
531its version string. The server name
532.B tripe
533is reserved to the Straylight/Edgeware implementation.
534.SP
535.BR "WATCH " [\fIoptions\fP]
536Enables or disables asynchronous messages
537.IR "for the current connection only" .
538See
539.B "Trace lists"
540above. The default watch state for the connection the server opens
541automatically on stdin/stdout is to show warnings and trace messages;
542other connections show no asynchronous messages. (This is done in order
543to guarantee that a program reading the server's stdout does not miss
544any warnings.)
545.RS
546.PP
547Message types provided are:
548.TP
549.B t
550.B TRACE
551messages.
552.TP
553.B n
554.B NOTE
555messages.
556.TP
557.B w
558.B WARN
559messages.
560.TP
561.B A
562All of the above.
563.RE
564.SP
565.BI "WARN " tokens\fR...
566Issues a
567.B USER
568warning to all interested administration clients.
569.SH "ERROR MESSAGES"
570.\"* 20 Error messages (FAIL codes)
571The following
572.B FAIL
573(or
574.BR BGFAIL )
575messages are sent to clients as a result of errors during command
576processing.
577.SP
578.BI "already-daemon"
579(For
580.BR DAEMON .)
581The
582.B tripe
583server is already running as a daemon.
584.SP
585.BI "bad-addr-syntax " message
586(For commands accepting socket addresses.) The address couldn't be
587understood.
588.SP
589.BI "bad-syntax " cmd " " message
590(For any command.) The command couldn't be understood: e.g., the number
591of arguments was wrong.
592.SP
593.BI "bad-time-spec " word
594The
595.I word
596is not a valid time interval specification. Acceptable time
597specifications are nonnegative integers followed optionally by
598.BR d ,
599.BR h ,
600.BR m ,
601or
602.BR s ,
603for days, hours, minutes, or seconds, respectively.
604.SP
605.BI "bad-trace-option " char
606(For
607.BR TRACE .)
608An unknown trace option was requested.
609.SP
610.BI "bad-watch-option " char
611(For
612.BR WATCH .)
613An unknown watch option was requested.
614.SP
615.BI "daemon-error " ecode " " message
616(For
617.BR DAEMON .)
618An error occurred during the attempt to become a daemon, as reported by
619.IR message .
620.SP
621.BI "invalid-port " number
622(For
623.BR ADD .)
624The given port number is out of range.
625.SP
626.BI "peer-create-fail " peer
627(For
628.BR ADD .)
629Adding
630.I peer
631failed for some reason. A warning should have been emitted explaining
632why.
633.SP
634.BI "peer-exists " peer
635(For
636.BR ADD .)
637There is already a peer named
638.IR peer .
639.SP
640.B "ping-send-failed"
641The attempt to send a ping packet failed, probably due to lack of
642encryption keys.
643.SP
644.BI "resolve-error " hostname
645(For
646.BR ADD .)
647The DNS name
648.I hostname
649could not be resolved.
650.SP
651.BI "resolver-timeout " hostname
652(For
653.BR ADD .)
654The DNS name
655.I hostname
656took too long to resolve.
657.SP
658.BI "tag-exists " tag
659(For long-running commands.) The named
660.I tag
661is already the tag of an outstanding job.
662.SP
663.BI "unknown-command " token
664The command
665.B token
666was not recognised.
667.SP
668.BI "unknown-peer " name
669(For
670.BR ADDR ,
671.BR IFNAME ,
672.BR KILL ,
673.BR SETIFNAME ,
674and
675.BR STATS .)
676There is no peer called
677.IR name .
678.SP
679.BI "unknown-service " service
680(For
681.BR ADD .)
682The service name
683.I service
684couldn't be found in
685.BR /etc/services .
686.TP
687.BI "unknown-tag " tag
688(For
689.BR BGCANCEL .)
690The given
691.I tag
692is not the tag for any outstanding background job. It may have just
693finished.
694.SH "NOTIFICATIONS"
695.\"* 30 Notification broadcasts (NOTE codes)
696The following notifications are sent to clients who request them.
697.SP
698.BI "ADD " peer " " ifname " " address \fR...
699A new peer has been added. The peer's name is
700.IR peer ,
701its tunnel is network interface
702.IR ifname ,
703and its network address is
704.IR address .
705.SP
706.BI "DAEMON"
707The server has forked off into the sunset and become a daemon.
708.SP
709.BI "GREET " challenge " " address \fR...
710A valid greeting was received, with the given challenge (exactly as it
711was returned by
712.B GETCHAL
713earlier).
714.SP
715.BI "KILL " peer
716The peer
717.I peer
718has been killed.
719.SP
720.BI "KXDONE " peer
721Key exchange with
722.I peer
723finished successfully.
724.SP
725.BI "KXSTART " peer
726Key exchange with
727.I peer
728has begun or restarted. If key exchange keeps failing, this message
729will be repeated periodically.
730.SP
731.BI "NEWIFNAME " peer " " old-name " " new-name
732The given
733.IR peer 's
734tunnel interface name has been changed from
735.I old-name
736to
737.IR new-name ,
738as a result of a
739.B SETIFNAME
740command.
741.SP
742.BI "USER " tokens\fR...
743An administration client issued a notification using the
744.B NOTIFY
745command.
746.SH "WARNINGS"
747.\"* 40 Warning broadcasts (WARN codes)
748.\"+sep
749There are many possible warnings. They are categorized according to
750their first tokens.
751.PP
752Many of these warnings report system errors. These are reported as a
753pair of tokens, described below as
754.I ecode
755and
756.IR message .
757The
758.I ecode
759is a string of the form
760.BI E number
761giving the
762.BR errno (3)
763value of the error; the
764.I message
765is the `human-readable' form of the message, as reported by
766.BR strerror (3).
767.SS "ABORT warnings"
768These all indicate that the
769.B tripe
770server has become unable to continue. If enabled, the server will dump
771core in its configuration directory.
772.SP
773.BI "ABORT repeated-select-errors"
774The main event loop is repeatedly failing. If the server doesn't quit,
775it will probably waste all available CPU doing nothing.
776.SS "ADMIN warnings"
777These indicate a problem with the administration socket interface.
778.SP
779.BI "ADMIN accept-error " ecode " " message
780There was an error while attempting to accept a connection from a new
781client.
782.SP
783.BI "ADMIN client-write-error " ecode " " message
784There was an error sending data to a client. The connection to the
785client has been closed.
786.SS "CHAL warnings"
787These indicate errors in challenges, either in the
788.B CHECKCHAL
789command or in greeting packets.
790.SP
791.B "CHAL impossible-challenge"
792The server hasn't issued any challenges yet. Quite how anyone else
793thought he could make one up is hard to imagine.
794.SP
795.B "CHAL incorrect-tag"
796Challenge received contained the wrong authentication data. It might be
797very stale, or a forgery.
798.SP
799.B "CHAL invalid-challenge"
800Challenge received was the wrong length. We might have changed MAC
801algorithms since the challenge was issued, or it might just be rubbish.
802.SP
803.B "CHAL replay duplicated-sequence"
804Challenge received was a definite replay of an old challenge. Someone's
805up to something!
806.SP
807.B "CHAL replay old-sequence"
808Challenge received was old, but maybe not actually a replay. Try again.
809.SS "KEYMGMT warnings"
810These indicate a problem with the keyring files, or the keys stored in
811them.
812.SP
813.BI "KEYMGMT bad-private-key " message
814The private key could not be read, or failed a consistency check. If
815there was a problem with the file, usually there will have been
816.B key-file-error
817warnings before this.
818.SP
819.BI "KEYMGMT bad-public-keyring " message
820The public keyring couldn't be read. Usually, there will have been
821.B key-file-error
822warnings before this.
823.SP
824.BI "KEYMGMT key-file-error " file ":" line " " message
825Reports a specific error with the named keyring file. This probably
826indicates a bug in
827.BR key (1).
828.SP
829.BI "KEYMGMT public-key " tag " " tokens\fR...
830These messages all indicate a problem with the public key named
831.IR tag .
832.SP
833.BI "KEYMGMT public-key " tag " algorithm-mismatch"
834The algorithms specified on the public key don't match the ones for our
835private key. All the peers in a network have to use the same
836algorithms.
837.SP
838.BI "KEYMGMT public-key " tag " bad " message
839The public key couldn't be read, or is invalid.
840.SP
841.BI "KEYMGMT public-key " tag " bad-public-group-element"
842The public key is invalid. This may indicate a malicious attempt to
843introduce a bogus key.
844.SP
845.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
846The algorithms listed on the public key couldn't be understood. The
847algorithm selection attributes are probably malformed and need fixing.
848.SP
849.BI "KEYMGMT public-key " tag " incorrect-group"
850The public key doesn't use the same group as our private key. All the
851peers in a network have to use the same group.
852.SP
853.BI "KEYMGMT public-key " tag " not-found"
854The public key for peer
855.I tag
856wasn't in the public keyring.
857.SP
858.BI "KEYMGMT public-key " tag " unknown-type"
859The type of the public key isn't understood. Maybe you need to upgrade
860your copy of
861.BR tripe .
862(Even if you do, you'll have to regenerate your keys.)
863.SS "KX warnings"
864These indicate problems during key-exchange. Many indicate either a bug
865in the server (either yours or the remote one), or some kind of attack
866in progress. All name a
867.I peer
868as the second token: this is the peer the packet is apparently from,
869though it may have been sent by an attacker instead.
870.PP
871In the descriptions below,
872.I msgtoken
873is one of the tokens
874.BR pre-challenge ,
875.BR cookie ,
876.BR challenge ,
877.BR reply ,
878.BR switch-rq ,
879or
880.BR switch-ok .
881.SP
882.BI "KX " peer " bad-expected-reply-log"
883The challenges
884.B tripe
885uses in its protocol contain a check value which proves that the
886challenge is honest. This message indicates that the check value
887supplied is wrong: someone is attempting to use bogus challenges to
888persuade your
889.B tripe
890server to leak private key information. No chance!
891.SP
892.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
893A symmetrically-encrypted portion of a key-exchange message failed to
894decrypt.
895.SP
896.BI "KX " peer " invalid " msgtoken
897A key-exchange message was malformed. This almost certainly indicates a
898bug somewhere.
899.SP
900.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
901A message didn't contain the right magic data. This may be a replay of
902some old exchange, or random packets being sent in an attempt to waste
903CPU.
904.SP
905.BI "KX " peer " public-key-expired"
906The peer's public key has expired. It's maintainer should have given
907you a replacement before now.
908.SP
909.BI "KX " peer " sending-cookie"
910We've received too many bogus pre-challenge messages. Someone is trying
911to flood us with key-exchange messages and make us waste CPU on doing
912hard asymmetric crypto sums.
913.SP
914.BI "KX " peer " unexpected " msgtoken
915The message received wasn't appropriate for this stage of the key
916exchange process. This may mean that one of our previous packets got
917lost. For
918.BR pre-challenge ,
919it may simply mean that the peer has recently restarted.
920.SP
921.BI "KX " peer " unknown-challenge"
922The peer is asking for an answer to a challenge which we don't know
923about. This may mean that we've been inundated with challenges from
924some malicious source
925.I who can read our messages
926and discarded the valid one.
927.SP
928.BI "KX " peer " unknown-message 0x" nn
929An unknown key-exchange message arrived.
930.SS "PEER warnings"
931These are largely concerned with management of peers and the low-level
932details of the network protocol. The second word is usually the name of
933a peer, or
934.RB ` \- '
935if none is relevant.
936.SP
937.BI "PEER " peer " bad-packet no-type"
938An empty packet arrived. This is very strange.
939.SP
940.BI "PEER " peer " bad-packet unknown-category 0x" nn
941The message category
942.I nn
943(in hex) isn't understood. Probably a strange random packet from
944somewhere; could be an unlikely bug.
945.SP
946.BI "PEER " peer " bad-packet unknown-type 0x" nn
947The message type
948.I nn
949(in hex) isn't understood. Probably a strange random packet from
950somewhere; could be an unlikely bug.
951.SP
952.BI "PEER " peer " corrupt-encrypted-ping"
953The peer sent a ping response which matches an outstanding ping, but its
954payload is wrong. There's definitely a bug somewhere.
955.SP
956.BI "PEER " peer " corrupt-transport-ping"
957The peer (apparently) sent a ping response which matches an outstanding
958ping, but its payload is wrong. Either there's a bug, or the bad guys
959are playing tricks on you.
960.SP
961.BI "PEER " peer " decrypt-failed"
962An encrypted IP packet failed to decrypt. It may have been mangled in
963transit, or may be a very old packet from an expired previous session
964key. There is usually a considerable overlap in the validity periods of
965successive session keys, so this shouldn't occur unless the key exchange
966takes ages or fails.
967.SP
968.BI "PEER " peer " malformed-encrypted-ping"
969The peer sent a ping response which is hopelessly invalid. There's
970definitely a bug somewhere.
971.SP
972.BI "PEER " peer " malformed-transport-ping"
973The peer (apparently) sent a ping response which is hopelessly invalid.
974Either there's a bug, or the bad guys are playing tricks on you.
975.SP
976.BI "PEER " peer " packet-build-failed"
977There wasn't enough space in our buffer to put the packet we wanted to
978send. Shouldn't happen.
979.SP
980.BI "PEER \- socket-read-error " ecode " " message
981An error occurred trying to read an incoming packet.
982.SP
983.BI "PEER " peer " socket-write-error " ecode " " message
984An error occurred attempting to send a network packet. We lost that
985one.
986.SP
987.BI "PEER " peer " unexpected-encrypted-ping 0x" id
988The peer sent an encrypted ping response whose id doesn't match any
989outstanding ping. Maybe it was delayed for longer than the server was
990willing to wait, or maybe the peer has gone mad.
991.SP
992.BI "PEER \- unexpected-source " address\fR...
993A packet arrived from
994.I address
995(a network address \(en see above), but no peer is known at that
996address. This may indicate a misconfiguration, or simply be a result of
997one end of a connection being set up before the other.
998.SP
999.BI "PEER " peer " unexpected-transport-ping 0x" id
1000The peer (apparently) sent a transport ping response whose id doesn't
1001match any outstanding ping. Maybe it was delayed for longer than the
1002server was willing to wait, or maybe the peer has gone mad; or maybe
1003there are bad people trying to confuse you.
1004.SS "SERVER warnings"
1005These indicate problems concerning the server process as a whole.
1006.SP
1007.BI "SERVER ignore signal " name
1008A signal arrived, but the server ignored it. Currently this happens for
1009.B SIGHUP
1010because that's a popular way of telling daemons to re-read their
1011configuration files. Since
1012.B tripe
1013re-reads its keyrings automatically and has no other configuration
1014files, it's not relevant, but it seemed better to ignore the signal than
1015let the server die.
1016.SP
1017.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1018A signal arrived and
1019.B tripe
1020is going to quit.
1021.SP
1022.BI "SERVER quit admin-request"
1023A client of the administration interface issued a
1024.B QUIT
1025command.
1026.SP
1027.BI "SERVER select-error " ecode " " message
1028An error occurred in the server's main event loop. This is bad: if it
1029happens too many times, the server will abort.
1030.SS "SYMM warnings"
1031These are concerned with the symmetric encryption and decryption
1032process.
1033.SP
1034.BI "SYMM replay old-sequence"
1035A packet was received with an old sequence number. It may just have
1036been delayed or duplicated, or it may have been an attempt at a replay
1037attack.
1038.SP
1039.BI "SYMM replay duplicated-sequence"
1040A packet was received with a sequence number we've definitely seen
1041before. It may be an accidental duplication because the 'net is like
1042that, or a deliberate attempt at a replay.
1043.SS "TUN warnings"
1044These concern the workings of the system-specific tunnel driver. The
1045second word is the name of the tunnel interface in question, or
1046.RB ` \- '
1047if none.
1048.SP
1049.BI "TUN \- bsd no-tunnel-devices"
1050The driver couldn't find an available tunnel device. Maybe if you
1051create some more
1052.BI /dev/tun nn
1053files, it will work.
1054.SP
1055.BI "TUN - " tun-name " open-error " device " " ecode " " message
1056An attempt to open the tunnel device file
1057.I device
1058failed.
1059.SP
1060.BI "TUN \- linux config-error " ecode " " message
1061Configuring the Linux TUN/TAP interface failed.
1062.SP
1063.BI "TUN " ifname " " tun-name " read-error " ecode " " message
1064Reading from the tunnel device failed.
1065.SP
1066.BI "TUN " ifname " slip bad-escape"
1067The SLIP driver encountered a escaped byte it wasn't expecting to see.
1068The erroneous packet will be ignored.
1069.SP
1070.BI "TUN " ifname " slip eof"
1071The SLIP driver encountered end-of-file on its input descriptor.
1072Pending data is discarded, and no attempt is made to read any more data
1073from that interface ever.
1074.SP
1075.BI "TUN " ifname " slip escape-end"
1076The SLIP driver encountered an escaped `end' marker. This probably
1077means that someone's been sending it junk. The erroneous packet is
1078discarded, and we hope that we've rediscovered synchronization.
1079.SP
1080.BI "TUN \- slip fork-error " ecode " " message
1081The SLIP driver encountered an error forking a child process while
1082allocating a new dynamic interface.
1083.SP
1084.BI "TUN \- slip no-slip-interfaces"
1085The driver ran out of static SLIP interfaces. Either preallocate more,
1086or use dynamic SLIP interface allocation.
1087.SP
1088.BI "TUN " ifname " slip overflow"
1089The SLIP driver gave up reading a packet because it got too large.
1090.SP
1091.BI "TUN \- slip pipe-error " ecode " " message
1092The SLIP driver encountered an error creating pipes while allocating a
1093new dynamic interface.
1094.SP
1095.BI "TUN \- slip read-ifname-failed " ecode " " message
1096The SLIP driver encountered an error reading the name of a dynamically
1097allocated interface. Maybe the allocation script is broken.
1098.SP
1099.BI "TUN \- unet config-error " ecode " " message
1100Configuring the Linux Unet interface failed. Unet is obsolete and
1101shouldn't be used any more.
1102.SP
1103.BI "TUN \- unet getinfo-error " ecode " " message
1104Reading information about the Unet interface failed. Unet is obsolete
1105and shouldn't be used any more.
1106.SP
1107.BI "TUN \- unet ifname-too-long"
1108The Unet interface's name overflowed, so we couldn't read it properly.
1109Unet is obsolete and shouldn't be used any more.
1110.SS "USER warnings"
1111These are issued by administration clients using the
1112.B WARN
1113command.
1114.SP
1115.BI "USER " tokens\fR...
1116An administration client issued a warning.
1117.\"-sep
1118.SH "SUMMARY"
1119.SS "Command responses"
1120.nf
1121.BI "BGFAIL " tag " " tokens \fR...
1122.BI "BGINFO " tag " " tokens \fR...
1123.BI "BGOK " tag
1124.BI "FAIL " tokens \fR...
1125.BI "INFO " tokens \fR...
1126.B OK
1127.fi
1128.\"= summary
1129.SH "SEE ALSO"
1130.BR tripectl (1),
1131.BR tripe (8).
1132.PP
1133.IR "The Trivial IP Encryption Protocol" .
1134.SH "AUTHOR"
1135Mark Wooding, <mdw@distorted.org.uk>