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