chiark / gitweb /
Great reorganization.
[tripe] / doc /
d6623498 1.\" -*-nroff-*-
060ca767 2.\" t \{\
4. if \n(.g \{\
5. fam P
6. \}
8. SP
d6623498 12.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
14tripe-admin \- administrator commands for TrIPE
16This manual page describes the administration interface provided by the
17.BR tripe (8)
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.
28By default, the server listens for admin connections on the Unix-domain
30.BR /var/lib/tripe/tripesock .
37941236 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.
d6623498 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.
de014da6 44.SS "Simple commands"
45For simple client command, the server responds with zero or more
d6623498 46.B INFO
47lines, followed by either an
48.B OK
49line or a
51line. Each
53provides information requested in the command. An
54.B OK
55response contains no further data. A
3cdc3f3a 57code is followed by a machine-readable explanation of why the command
d6623498 58failed.
de014da6 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
64.B ADD
66.BR PING )
67block the client until they finish, but the rest of the server continues
69.SS "Asynchronous messages"
70There are three types of asynchronous messages which
71aren't associated with any particular command.
d6623498 74.B WARN
3cdc3f3a 75message contains a machine-readable message warning of an error
d6623498 76encountered while processing a command, unexpected or unusual behaviour
77by a peer, or a possible attack by an adversary. Under normal
de014da6 78conditions, the server shouldn't emit any warnings.
d6623498 81.B TRACE
3cdc3f3a 82message contains a human-readable tracing message containing diagnostic
d6623498 83information. Trace messages are controlled using the
84.B \-T
85command-line option to the server, or the
87administration command (see below). Support for tracing can be disabled
88when the package is being configured, and may not be available in your
de014da6 89version.
91Finally, the
3cdc3f3a 92.B NOTE
93message is a machine-readable notification about some routine but
94interesting event such as creation or destruction of peers.
96The presence of asynchronous messages can be controlled using the
de014da6 99.SS "Background commands"
100Some commands (e.g.,
101.B ADD
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 .
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,
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.
124Responses to background commands are indicated by a line beginning with
125one of the tokens
126.BR BGOK ,
130followed by the command tag. These correspond to the
131.BR OK ,
132.BR FAIL ,
134.B INFO
135responses for simple commands:
137indicates information from a background command which has not completed
138yet; and
139.B BGOK
142indicates that a background command succeeded or failed, respectively.
144A background command will never issue an
145.B OK
060ca767 146or
148response: it will always detach and then issue any
150lines followed by
de014da6 151.B BGOK
3cdc3f3a 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.
160At present, only one address family is understood.
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.)
171If, on input, no recognised address family token is found, the following
172words are assumed to represent an
173.B INET
060ca767 175.SS "Key-value output"
176Some commands (e.g.,
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.,
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.
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.
210Lowercase key letters control individual message types. Uppercase key
211letters control collections of message types.
13a55605 213.\"* 10 Commands
d6623498 214The commands provided are:
13a55605 215.SP
42da2a58 216.BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
3cdc3f3a 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
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
42da2a58 226be contacted. The following options are recognised.
13a55605 228.\"+opts
42da2a58 229.TP
de014da6 230.BI "\-background " tag
231Run the command in the background, using the given
232.IR tag .
0ba8de86 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 ,
245.BR s
246for days, hours, minutes, or seconds respectively; if no suffix is
247given, seconds are assumed.
249.BI "\-tunnel " tunnel
42da2a58 250Use the named tunnel driver, rather than the default.
13a55605 251.\"-opts
42da2a58 252.RE
13a55605 253.SP
3cdc3f3a 254.BI "ADDR " peer
255Emits an
256.B INFO
257line reporting the IP address and port number stored for
258.IR peer .
13a55605 259.SP
37941236 260.BI "CHECKCHAL " challenge
261Verifies a challenge as being one earlier issued by
263and not previously either passed to
265or in a greeting message.
13a55605 266.SP
3cdc3f3a 267.B "DAEMON"
268Causes the server to disassociate itself from its terminal and become a
269background task. This only works once. A warning is issued.
0ba8de86 271.BI "EPING \fR[" options "\fR] " peer
272Sends an encrypted ping to the peer, and expects an encrypted response.
273This checks that the peer is running (and not being impersonated), and
274that it can encrypt and decrypt packets correctly. Options and
275responses are the same as for the
276.B PING
13a55605 278.SP
de014da6 279.BI "FORCEKX " peer
280Requests the server to begin a new key exchange with
281.I peer
13a55605 283.SP
37941236 284.B "GETCHAL"
285Requests a challenge. The challenge is returned in an
286.B INFO
287line, as a base64-encoded string. See
13a55605 289.SP
37941236 290.BI "GREET " peer " " challenge
291Sends a greeting packet containing the
292.I challenge
293(base-64 encoded) to the named
294.IR peer .
295The expectation is that this will cause the peer to recognize us and
296begin a key-exchange.
13a55605 297.SP
d6623498 298.B "HELP"
299Causes the server to emit an
300.B INFO
301line for each command it supports. Each line lists the command name,
302followed by the names of the arguments. This may be helpful as a memory
303aid for interactive use, or for program clients probing for features.
13a55605 304.SP
3cdc3f3a 305.BI "IFNAME " peer
306Emits an
307.B INFO
308line containing the name of the network interface used to collect IP
309packets which are to be encrypted and sent to
310.IR peer .
311Used by configuration scripts so that they can set up routing tables
312appropriately after adding new peers.
13a55605 313.SP
3cdc3f3a 314.BI "KILL " peer
315Causes the server to forget all about
316.IR peer .
317All keys are destroyed, and no more packets are sent. No notification
318is sent to the peer: if it's important that the peer be notified, you
319must think of a way to do that yourself.
13a55605 320.SP
3cdc3f3a 321.B "LIST"
322For each currently-known peer, an
323.B INFO
324line is written containing the peer's name, as given to
325.BR ADD .
13a55605 326.SP
bd58d532 327.BI "NOTIFY " tokens\fR...
328Issues a
329.B USER
330notification to all interested administration clients.
13a55605 331.SP
060ca767 332.BI "PEERINFO " peer
333Returns information about a peer, in key-value form. The following keys
334are returned.
337.B tunnel
338The tunnel driver used for this peer.
340.B keepalive
341The keepalive interval, in seconds, or zero if no keepalives are to be
13a55605 344.SP
0ba8de86 345.BI "PING \fR[" options "\fR] " peer
346Send a transport-level ping to the peer. The ping and its response are
347not encrypted or authenticated. This command, possibly in conjunction
348with tracing, is useful for ensuring that UDP packets are actually
349flowing in both directions. See also the
354.B INFO
355line is printed describing the outcome:
358.BI "ping-ok " millis
359A response was received
360.I millis
361after the ping was sent.
363.BI "ping-timeout"
364No response was received within the time allowed.
366.BI "ping-peer-died"
367The peer was killed (probably by another admin connection) before a
368response was received.
371Options recognized for this command are:
13a55605 373.\"+opts
0ba8de86 374.TP
de014da6 375.BI "\-background " tag
376Run the command in the background, using the given
377.IR tag .
0ba8de86 379.BI "\-timeout " time
380Wait for
381.I time
382seconds before giving up on a response. The default is 5 seconds. (The
383time format is the same as for the
384.B "ADD \-keepalive"
13a55605 386.\"-opts
0ba8de86 387.RE
13a55605 388.SP
3cdc3f3a 389.B "PORT"
390Emits an
391.B INFO
392line containing just the number of the UDP port used by the
393.B tripe
394server. If you've allowed your server to allocate a port dynamically,
395this is how to find out which one it chose.
13a55605 396.SP
de014da6 397.B "RELOAD"
398Instructs the server to recheck its keyring files. The server checks
399these periodically anyway but it may be necessary to force a recheck,
400for example after adding a new peer key.
13a55605 401.SP
3cdc3f3a 402.B "QUIT"
403Instructs the server to exit immediately. A warning is sent.
13a55605 404.SP
060ca767 405.B "SERVINFO"
406Returns information about the server, in the form of key-value pairs.
407The following keys are used.
410.B implementation
411A keyword naming the implementation of the
412.BR tripe (8)
413server. The current implementation is called
414.BR edgeware-tripe .
416.B version
417The server's version number, as reported by
420.B daemon
422.B t
424.BR nil ,
425if the server has or hasn't (respectively) become a daemon.
13a55605 427.SP
3cdc3f3a 428.BI "STATS " peer
429Emits a number of
430.B INFO
431lines, each containing one or more statistics in the form
432.IB name = value \fR.
433The statistics-gathering is experimental and subject to change.
13a55605 434.SP
d6623498 435.BR "TRACE " [\fIoptions\fP]
060ca767 436Selects trace outputs: see
437.B "Trace lists"
438above. Message types provided are:
d6623498 439.RS
2d752320 440.PP
d6623498 441Currently, the following tracing options are supported:
443.B t
444Tunnel events: reception of packets to be encrypted, and injection of
445successfully-decrypted packets.
447.B r
448Peer management events: creation and destruction of peer attachments,
449and arrival of messages.
451.B a
452Administration interface: acceptance of new connections, and handling of
453the backgroud name-resolution required by the
454.B ADD
d6623498 457.B s
458Handling of symmetric keysets: creation and expiry of keysets, and
459encryption and decryption of messages.
461.B x
462Key exchange: reception, parsing and emission of key exchange messages.
464.B m
465Key management: loading keys and checking for file modifications.
37941236 466.TP
467.B l
468Display information about challenge issuing and verification.
470.B p
471Display contents of packets sent and received by the tunnel and/or peer
474.B c
475Display inputs, outputs and intermediate results of cryptographic
476operations. This includes plaintext and key material. Use with
479.B A
480All of the above.
d6623498 481.PP
482Note that the
483.B p
484(packet contents)
486.B c
487(crypto details)
488outputs provide extra detail for other outputs. Specifying
489.B p
37941236 491.BR r
d6623498 492or
493.B t
494isn't useful; neither is specifying
495.B c
496without one of
497.BR s ,
37941236 498.BR l ,
d6623498 499.B x
501.BR m .
13a55605 503.SP
060ca767 504.B "TUNNELS"
505For each available tunnel driver, an
506.B INFO
507line is printed giving its name.
13a55605 508.SP
060ca767 509.B "VERSION"
510Causes the server to emit an
511.B INFO
512line stating its software version, as two words: the server name, and
513its version string. The server name
514.B tripe
515is reserved to the Straylight/Edgeware implementation.
13a55605 516.SP
3cdc3f3a 517.BR "WATCH " [\fIoptions\fP]
518Enables or disables asynchronous messages
519.IR "for the current connection only" .
060ca767 520See
521.B "Trace lists"
3cdc3f3a 522above. The default watch state for the connection the server opens
523automatically on stdin/stdout is to show warnings and trace messages;
524other connections show no asynchronous messages. (This is done in order
525to guarantee that a program reading the server's stdout does not miss
526any warnings.)
060ca767 529Message types provided are:
3cdc3f3a 530.TP
531.B t
535.B n
536.B NOTE
539.B w
540.B WARN
37941236 543.B A
3cdc3f3a 544All of the above.
13a55605 546.SP
bd58d532 547.BI "WARN " tokens\fR...
548Issues a
549.B USER
550warning to all interested administration clients.
3cdc3f3a 551.SH "ERROR MESSAGES"
13a55605 552.\"* 20 Error messages (FAIL codes)
3cdc3f3a 553The following
554.B FAIL
de014da6 555(or
3cdc3f3a 557messages are sent to clients as a result of errors during command
13a55605 559.SP
3cdc3f3a 560.BI "already-daemon"
562.BR DAEMON .)
564.B tripe
565server is already running as a daemon.
13a55605 566.SP
f43df819 567.BI "bad-addr-syntax " message
37941236 568(For commands accepting socket addresses.) The address couldn't be
13a55605 570.SP
f43df819 571.BI "bad-syntax " cmd " " message
3cdc3f3a 572(For any command.) The command couldn't be understood: e.g., the number
573of arguments was wrong.
13a55605 574.SP
0ba8de86 575.BI "bad-time-spec " word
577.I word
578is not a valid time interval specification. Acceptable time
579specifications are nonnegative integers followed optionally by
580.BR d ,
581.BR h ,
582.BR m ,
584.BR s ,
585for days, hours, minutes, or seconds, respectively.
13a55605 586.SP
3cdc3f3a 587.BI "bad-trace-option " char
589.BR TRACE .)
590An unknown trace option was requested.
13a55605 591.SP
3cdc3f3a 592.BI "bad-watch-option " char
594.BR WATCH .)
595An unknown watch option was requested.
13a55605 596.SP
f43df819 597.BI "daemon-error " ecode " " message
3cdc3f3a 598(For
599.BR DAEMON .)
600An error occurred during the attempt to become a daemon, as reported by
601.IR message .
13a55605 602.SP
3cdc3f3a 603.BI "invalid-port " number
605.BR ADD .)
606The given port number is out of range.
13a55605 607.SP
3cdc3f3a 608.BI "peer-create-fail " peer
610.BR ADD .)
612.I peer
613failed for some reason. A warning should have been emitted explaining
13a55605 615.SP
3cdc3f3a 616.BI "peer-exists " peer
618.BR ADD .)
619There is already a peer named
d6623498 620.IR peer .
13a55605 621.SP
0ba8de86 622.B "ping-send-failed"
623The attempt to send a ping packet failed, probably due to lack of
624encryption keys.
13a55605 625.SP
3cdc3f3a 626.BI "resolve-error " hostname
628.BR ADD .)
629The DNS name
630.I hostname
631could not be resolved.
13a55605 632.SP
3cdc3f3a 633.BI "resolver-timeout " hostname
635.BR ADD .)
636The DNS name
637.I hostname
638took too long to resolve.
13a55605 639.SP
3cdc3f3a 640.BI "unknown-command " token
641The command
642.B token
643was not recognised.
13a55605 644.SP
3cdc3f3a 645.BI "unknown-peer " name
647.BR ADDR ,
649.BR KILL ,
651.BR STATS .)
652There is no peer called
653.IR name .
13a55605 654.SP
3cdc3f3a 655.BI "unknown-service " service
657.BR ADD .)
658The service name
659.I service
660couldn't be found in
661.BR /etc/services .
13a55605 663.\"* 30 Notification broadcasts (NOTE codes)
3cdc3f3a 664The following notifications are sent to clients who request them.
13a55605 665.SP
42da2a58 666.BI "ADD " peer " " ifname " " address \fR...
3cdc3f3a 667A new peer has been added. The peer's name is
42da2a58 668.IR peer ,
669its tunnel is network interface
670.IR ifname ,
3cdc3f3a 671and its network address is
672.IR address .
13a55605 673.SP
3cdc3f3a 674.BI "DAEMON"
675The server has forked off into the sunset and become a daemon.
13a55605 676.SP
37941236 677.BI "GREET " challenge " " address \fR...
678A valid greeting was received, with the given challenge (exactly as it
679was returned by
13a55605 682.SP
d6623498 683.BI "KILL " peer
3cdc3f3a 684The peer
685.I peer
686has been killed.
13a55605 687.SP
3cdc3f3a 688.BI "KXDONE " peer
689Key exchange with
690.I peer
691finished successfully.
13a55605 692.SP
3cdc3f3a 693.BI "KXSTART " peer
694Key exchange with
695.I peer
696has begun or restarted. If key exchange keeps failing, this message
697will be repeated periodically.
13a55605 698.SP
bd58d532 699.BI "USER " tokens\fR...
700An administration client issued a notification using the
3cdc3f3a 703.SH "WARNINGS"
704.\"* 40 Warning broadcasts (WARN codes)
3cdc3f3a 706There are many possible warnings. They are categorized according to
707their first tokens.
709Many of these warnings report system errors. These are reported as a
710pair of tokens, described below as
711.I ecode
713.IR message .
715.I ecode
716is a string of the form
717.BI E number
718giving the
719.BR errno (3)
720value of the error; the
721.I message
722is the `human-readable' form of the message, as reported by
723.BR strerror (3).
3cdc3f3a 724.SS "ABORT warnings"
725These all indicate that the
d6623498 726.B tripe
3cdc3f3a 727server has become unable to continue. If enabled, the server will dump
728core in its configuration directory.
13a55605 729.SP
3cdc3f3a 730.BI "ABORT repeated-select-errors"
731The main event loop is repeatedly failing. If the server doesn't quit,
732it will probably waste all available CPU doing nothing.
733.SS "ADMIN warnings"
734These indicate a problem with the administration socket interface.
13a55605 735.SP
f43df819 736.BI "ADMIN accept-error " ecode " " message
3cdc3f3a 737There was an error while attempting to accept a connection from a new
13a55605 739.SP
f43df819 740.BI "ADMIN client-write-error " ecode " " message
3cdc3f3a 741There was an error sending data to a client. The connection to the
742client has been closed.
37941236 743.SS "CHAL warnings"
744These indicate errors in challenges, either in the
746command or in greeting packets.
13a55605 747.SP
37941236 748.B "CHAL impossible-challenge"
749The server hasn't issued any challenges yet. Quite how anyone else
750thought he could make one up is hard to imagine.
13a55605 751.SP
37941236 752.B "CHAL incorrect-tag"
753Challenge received contained the wrong authentication data. It might be
754very stale, or a forgery.
13a55605 755.SP
37941236 756.B "CHAL invalid-challenge"
757Challenge received was the wrong length. We might have changed MAC
758algorithms since the challenge was issued, or it might just be rubbish.
13a55605 759.SP
37941236 760.B "CHAL replay duplicated-sequence"
761Challenge received was a definite replay of an old challenge. Someone's
762up to something!
13a55605 763.SP
37941236 764.B "CHAL replay old-sequence"
765Challenge received was old, but maybe not actually a replay. Try again.
3cdc3f3a 766.SS "KEYMGMT warnings"
767These indicate a problem with the keyring files, or the keys stored in
13a55605 769.SP
f43df819 770.BI "KEYMGMT bad-private-key " message
3cdc3f3a 771The private key could not be read, or failed a consistency check. If
772there was a problem with the file, usually there will have been
773.B key-file-error
774warnings before this.
13a55605 775.SP
f43df819 776.BI "KEYMGMT bad-public-keyring " message
3cdc3f3a 777The public keyring couldn't be read. Usually, there will have been
778.B key-file-error
779warnings before this.
13a55605 780.SP
f43df819 781.BI "KEYMGMT key-file-error " file ":" line " " message
3cdc3f3a 782Reports a specific error with the named keyring file. This probably
783indicates a bug in
784.BR key (1).
13a55605 785.SP
3cdc3f3a 786.BI "KEYMGMT public-key " tag " " tokens\fR...
787These messages all indicate a problem with the public key named
788.IR tag .
13a55605 789.SP
3cdc3f3a 790.BI "KEYMGMT public-key " tag " algorithm-mismatch"
791The algorithms specified on the public key don't match the ones for our
792private key. All the peers in a network have to use the same
13a55605 794.SP
f43df819 795.BI "KEYMGMT public-key " tag " bad " message
3cdc3f3a 796The public key couldn't be read, or is invalid.
13a55605 797.SP
3cdc3f3a 798.BI "KEYMGMT public-key " tag " bad-public-group-element"
799The public key is invalid. This may indicate a malicious attempt to
800introduce a bogus key.
13a55605 801.SP
3cdc3f3a 802.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
803The algorithms listed on the public key couldn't be understood. The
804algorithm selection attributes are probably malformed and need fixing.
13a55605 805.SP
3cdc3f3a 806.BI "KEYMGMT public-key " tag " incorrect-group"
807The public key doesn't use the same group as our private key. All the
808peers in a network have to use the same group.
13a55605 809.SP
3cdc3f3a 810.BI "KEYMGMT public-key " tag " not-found"
811The public key for peer
812.I tag
813wasn't in the public keyring.
13a55605 814.SP
3cdc3f3a 815.BI "KEYMGMT public-key " tag " unknown-type"
816The type of the public key isn't understood. Maybe you need to upgrade
817your copy of
818.BR tripe .
819(Even if you do, you'll have to regenerate your keys.)
820.SS "KX warnings"
821These indicate problems during key-exchange. Many indicate either a bug
822in the server (either yours or the remote one), or some kind of attack
823in progress. All name a
824.I peer
825as the second token: this is the peer the packet is apparently from,
826though it may have been sent by an attacker instead.
828In the descriptions below,
829.I msgtoken
830is one of the tokens
831.BR pre-challenge ,
832.BR cookie ,
833.BR challenge ,
834.BR reply ,
835.BR switch-rq ,
837.BR switch-ok .
13a55605 838.SP
3cdc3f3a 839.BI "KX " peer " bad-expected-reply-log"
840The challenges
841.B tripe
842uses in its protocol contain a check value which proves that the
843challenge is honest. This message indicates that the check value
844supplied is wrong: someone is attempting to use bogus challenges to
845persuade your
846.B tripe
847server to leak private key information. No chance!
13a55605 848.SP
bd58d532 849.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
3cdc3f3a 850A symmetrically-encrypted portion of a key-exchange message failed to
13a55605 852.SP
3cdc3f3a 853.BI "KX " peer " invalid " msgtoken
854A key-exchange message was malformed. This almost certainly indicates a
855bug somewhere.
13a55605 856.SP
bd58d532 857.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
3cdc3f3a 858A message didn't contain the right magic data. This may be a replay of
859some old exchange, or random packets being sent in an attempt to waste
13a55605 861.SP
3cdc3f3a 862.BI "KX " peer " public-key-expired"
863The peer's public key has expired. It's maintainer should have given
864you a replacement before now.
13a55605 865.SP
3cdc3f3a 866.BI "KX " peer " sending-cookie"
867We've received too many bogus pre-challenge messages. Someone is trying
868to flood us with key-exchange messages and make us waste CPU on doing
869hard asymmetric crypto sums.
13a55605 870.SP
3cdc3f3a 871.BI "KX " peer " unexpected " msgtoken
872The message received wasn't appropriate for this stage of the key
873exchange process. This may mean that one of our previous packets got
874lost. For
875.BR pre-challenge ,
876it may simply mean that the peer has recently restarted.
13a55605 877.SP
3cdc3f3a 878.BI "KX " peer " unknown-challenge"
879The peer is asking for an answer to a challenge which we don't know
880about. This may mean that we've been inundated with challenges from
881some malicious source
882.I who can read our messages
883and discarded the valid one.
13a55605 884.SP
3cdc3f3a 885.BI "KX " peer " unknown-message 0x" nn
886An unknown key-exchange message arrived.
887.SS "PEER warnings"
888These are largely concerned with management of peers and the low-level
889details of the network protocol. The second word is usually the name of
890a peer, or
891.RB ` \- '
892if none is relevant.
13a55605 893.SP
3cdc3f3a 894.BI "PEER " peer " bad-packet no-type"
895An empty packet arrived. This is very strange.
13a55605 896.SP
3cdc3f3a 897.BI "PEER " peer " bad-packet unknown-category 0x" nn
898The message category
899.I nn
900(in hex) isn't understood. Probably a strange random packet from
901somewhere; could be an unlikely bug.
13a55605 902.SP
3cdc3f3a 903.BI "PEER " peer " bad-packet unknown-type 0x" nn
904The message type
905.I nn
906(in hex) isn't understood. Probably a strange random packet from
907somewhere; could be an unlikely bug.
13a55605 908.SP
0ba8de86 909.BI "PEER " peer " corrupt-encrypted-ping"
910The peer sent a ping response which matches an outstanding ping, but its
911payload is wrong. There's definitely a bug somewhere.
13a55605 912.SP
0ba8de86 913.BI "PEER " peer " corrupt-transport-ping"
914The peer (apparently) sent a ping response which matches an outstanding
915ping, but its payload is wrong. Either there's a bug, or the bad guys
916are playing tricks on you.
13a55605 917.SP
3cdc3f3a 918.BI "PEER " peer " decrypt-failed"
919An encrypted IP packet failed to decrypt. It may have been mangled in
920transit, or may be a very old packet from an expired previous session
921key. There is usually a considerable overlap in the validity periods of
922successive session keys, so this shouldn't occur unless the key exchange
923takes ages or fails.
13a55605 924.SP
0ba8de86 925.BI "PEER " peer " malformed-encrypted-ping"
926The peer sent a ping response which is hopelessly invalid. There's
927definitely a bug somewhere.
13a55605 928.SP
0ba8de86 929.BI "PEER " peer " malformed-transport-ping"
930The peer (apparently) sent a ping response which is hopelessly invalid.
931Either there's a bug, or the bad guys are playing tricks on you.
13a55605 932.SP
3cdc3f3a 933.BI "PEER " peer " packet-build-failed"
934There wasn't enough space in our buffer to put the packet we wanted to
935send. Shouldn't happen.
13a55605 936.SP
f43df819 937.BI "PEER \- socket-read-error " ecode " " message
3cdc3f3a 938An error occurred trying to read an incoming packet.
13a55605 939.SP
f43df819 940.BI "PEER " peer " socket-write-error " ecode " " message
3cdc3f3a 941An error occurred attempting to send a network packet. We lost that
13a55605 943.SP
0ba8de86 944.BI "PEER " peer " unexpected-encrypted-ping 0x" id
945The peer sent an encrypted ping response whose id doesn't match any
946outstanding ping. Maybe it was delayed for longer than the server was
947willing to wait, or maybe the peer has gone mad.
13a55605 948.SP
0ba8de86 949.BI "PEER \- unexpected-source " address\fR...
950A packet arrived from
951.I address
952(a network address \(en see above), but no peer is known at that
953address. This may indicate a misconfiguration, or simply be a result of
954one end of a connection being set up before the other.
13a55605 955.SP
0ba8de86 956.BI "PEER " peer " unexpected-transport-ping 0x" id
957The peer (apparently) sent a transport ping response whose id doesn't
958match any outstanding ping. Maybe it was delayed for longer than the
959server was willing to wait, or maybe the peer has gone mad; or maybe
960there are bad people trying to confuse you.
3cdc3f3a 961.SS "SERVER warnings"
962These indicate problems concerning the server process as a whole.
13a55605 963.SP
3cdc3f3a 964.BI "SERVER ignore signal " name
965A signal arrived, but the server ignored it. Currently this happens for
967because that's a popular way of telling daemons to re-read their
968configuration files. Since
969.B tripe
970re-reads its keyrings automatically and has no other configuration
971files, it's not relevant, but it seemed better to ignore the signal than
972let the server die.
13a55605 973.SP
3cdc3f3a 974.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
975A signal arrived and
976.B tripe
977is going to quit.
13a55605 978.SP
3cdc3f3a 979.BI "SERVER quit admin-request"
980A client of the administration interface issued a
981.B QUIT
13a55605 983.SP
f43df819 984.BI "SERVER select-error " ecode " " message
3cdc3f3a 985An error occurred in the server's main event loop. This is bad: if it
986happens too many times, the server will abort.
987.SS "SYMM warnings"
988These are concerned with the symmetric encryption and decryption
13a55605 990.SP
3cdc3f3a 991.BI "SYMM replay old-sequence"
992A packet was received with an old sequence number. It may just have
993been delayed or duplicated, or it may have been an attempt at a replay
13a55605 995.SP
3cdc3f3a 996.BI "SYMM replay duplicated-sequence"
997A packet was received with a sequence number we've definitely seen
998before. It may be an accidental duplication because the 'net is like
999that, or a deliberate attempt at a replay.
1000.SS "TUN warnings"
1001These concern the workings of the system-specific tunnel driver. The
1002second word is the name of the tunnel interface in question, or
1003.RB ` \- '
1004if none.
13a55605 1005.SP
3cdc3f3a 1006.BI "TUN \- bsd no-tunnel-devices"
1007The driver couldn't find an available tunnel device. Maybe if you
1008create some more
1009.BI /dev/tun nn
1010files, it will work.
13a55605 1011.SP
f43df819 1012.BI "TUN - " tun-name " open-error " device " " ecode " " message
3cdc3f3a 1013An attempt to open the tunnel device file
1014.I device
13a55605 1016.SP
f43df819 1017.BI "TUN \- linux config-error " ecode " " message
3cdc3f3a 1018Configuring the Linux TUN/TAP interface failed.
13a55605 1019.SP
f43df819 1020.BI "TUN " ifname " " tun-name " read-error " ecode " " message
42da2a58 1021Reading from the tunnel device failed.
13a55605 1022.SP
42da2a58 1023.BI "TUN " ifname " slip bad-escape"
1024The SLIP driver encountered a escaped byte it wasn't expecting to see.
1025The erroneous packet will be ignored.
13a55605 1026.SP
b9066fbb 1027.BI "TUN " ifname " slip eof"
1028The SLIP driver encountered end-of-file on its input descriptor.
1029Pending data is discarded, and no attempt is made to read any more data
1030from that interface ever.
13a55605 1031.SP
b9066fbb 1032.BI "TUN " ifname " slip escape-end"
1033The SLIP driver encountered an escaped `end' marker. This probably
1034means that someone's been sending it junk. The erroneous packet is
1035discarded, and we hope that we've rediscovered synchronization.
13a55605 1036.SP
f43df819 1037.BI "TUN \- slip fork-error " ecode " " message
42da2a58 1038The SLIP driver encountered an error forking a child process while
1039allocating a new dynamic interface.
13a55605 1040.SP
42da2a58 1041.BI "TUN \- slip no-slip-interfaces"
1042The driver ran out of static SLIP interfaces. Either preallocate more,
1043or use dynamic SLIP interface allocation.
13a55605 1044.SP
b9066fbb 1045.BI "TUN " ifname " slip overflow"
1046The SLIP driver gave up reading a packet because it got too large.
13a55605 1047.SP
f43df819 1048.BI "TUN \- slip pipe-error " ecode " " message
42da2a58 1049The SLIP driver encountered an error creating pipes while allocating a
1050new dynamic interface.
13a55605 1051.SP
f43df819 1052.BI "TUN \- slip read-ifname-failed " ecode " " message
42da2a58 1053The SLIP driver encountered an error reading the name of a dynamically
1054allocated interface. Maybe the allocation script is broken.
13a55605 1055.SP
f43df819 1056.BI "TUN \- unet config-error " ecode " " message
42da2a58 1057Configuring the Linux Unet interface failed. Unet is obsolete and
1058shouldn't be used any more.
13a55605 1059.SP
f43df819 1060.BI "TUN \- unet getinfo-error " ecode " " message
42da2a58 1061Reading information about the Unet interface failed. Unet is obsolete
1062and shouldn't be used any more.
13a55605 1063.SP
f43df819 1064.BI "TUN \- unet ifname-too-long"
42da2a58 1065The Unet interface's name overflowed, so we couldn't read it properly.
1066Unet is obsolete and shouldn't be used any more.
bd58d532 1067.SS "USER warnings"
1068These are issued by administration clients using the
1069.B WARN
13a55605 1071.SP
bd58d532 1072.BI "USER " tokens\fR...
1073An administration client issued a warning.
1076.SS "Command responses"
1078.BI "BGFAIL " tag " " tokens \fR...
1079.BI "BGINFO " tag " " tokens \fR...
1080.BI "BGOK " tag
1081.BI "FAIL " tokens \fR...
1082.BI "INFO " tokens \fR...
1083.B OK
1085.\"= summary
d6623498 1086.SH "SEE ALSO"
1087.BR tripectl (1),
1088.BR tripe (8).
3cdc3f3a 1090.IR "The Trivial IP Encryption Protocol" .
d6623498 1091.SH "AUTHOR"
d36eda2a 1092Mark Wooding, <>