chiark / gitweb /
cleanup: Various simple whitespace changes.
[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
428.BI "SETIFNAME " peer " " new-name
429Informs the server that the
430.IR peer 's
431tunnel-interface name has been changed to
432.IR new-name .
433This is useful if firewalling decisions are made based on interface
434names: a setup script for a particular peer can change the name, and
435then update the server's records so that they're accurate.
3cdc3f3a 437.BI "STATS " peer
438Emits a number of
439.B INFO
440lines, each containing one or more statistics in the form
441.IB name = value \fR.
442The statistics-gathering is experimental and subject to change.
13a55605 443.SP
d6623498 444.BR "TRACE " [\fIoptions\fP]
060ca767 445Selects trace outputs: see
446.B "Trace lists"
447above. Message types provided are:
d6623498 448.RS
2d752320 449.PP
d6623498 450Currently, the following tracing options are supported:
452.B t
453Tunnel events: reception of packets to be encrypted, and injection of
454successfully-decrypted packets.
456.B r
457Peer management events: creation and destruction of peer attachments,
458and arrival of messages.
460.B a
461Administration interface: acceptance of new connections, and handling of
462the backgroud name-resolution required by the
463.B ADD
d6623498 466.B s
467Handling of symmetric keysets: creation and expiry of keysets, and
468encryption and decryption of messages.
470.B x
471Key exchange: reception, parsing and emission of key exchange messages.
473.B m
474Key management: loading keys and checking for file modifications.
37941236 475.TP
476.B l
477Display information about challenge issuing and verification.
479.B p
480Display contents of packets sent and received by the tunnel and/or peer
483.B c
484Display inputs, outputs and intermediate results of cryptographic
485operations. This includes plaintext and key material. Use with
488.B A
489All of the above.
d6623498 490.PP
491Note that the
492.B p
493(packet contents)
495.B c
496(crypto details)
497outputs provide extra detail for other outputs. Specifying
498.B p
37941236 500.BR r
d6623498 501or
502.B t
503isn't useful; neither is specifying
504.B c
505without one of
506.BR s ,
37941236 507.BR l ,
d6623498 508.B x
510.BR m .
13a55605 512.SP
060ca767 513.B "TUNNELS"
514For each available tunnel driver, an
515.B INFO
516line is printed giving its name.
13a55605 517.SP
060ca767 518.B "VERSION"
519Causes the server to emit an
520.B INFO
521line stating its software version, as two words: the server name, and
522its version string. The server name
523.B tripe
524is reserved to the Straylight/Edgeware implementation.
13a55605 525.SP
3cdc3f3a 526.BR "WATCH " [\fIoptions\fP]
527Enables or disables asynchronous messages
528.IR "for the current connection only" .
060ca767 529See
530.B "Trace lists"
3cdc3f3a 531above. The default watch state for the connection the server opens
532automatically on stdin/stdout is to show warnings and trace messages;
533other connections show no asynchronous messages. (This is done in order
534to guarantee that a program reading the server's stdout does not miss
535any warnings.)
060ca767 538Message types provided are:
3cdc3f3a 539.TP
540.B t
544.B n
545.B NOTE
548.B w
549.B WARN
37941236 552.B A
3cdc3f3a 553All of the above.
13a55605 555.SP
bd58d532 556.BI "WARN " tokens\fR...
557Issues a
558.B USER
559warning to all interested administration clients.
3cdc3f3a 560.SH "ERROR MESSAGES"
13a55605 561.\"* 20 Error messages (FAIL codes)
3cdc3f3a 562The following
563.B FAIL
de014da6 564(or
3cdc3f3a 566messages are sent to clients as a result of errors during command
13a55605 568.SP
3cdc3f3a 569.BI "already-daemon"
571.BR DAEMON .)
573.B tripe
574server is already running as a daemon.
13a55605 575.SP
f43df819 576.BI "bad-addr-syntax " message
37941236 577(For commands accepting socket addresses.) The address couldn't be
13a55605 579.SP
f43df819 580.BI "bad-syntax " cmd " " message
3cdc3f3a 581(For any command.) The command couldn't be understood: e.g., the number
582of arguments was wrong.
13a55605 583.SP
0ba8de86 584.BI "bad-time-spec " word
586.I word
587is not a valid time interval specification. Acceptable time
588specifications are nonnegative integers followed optionally by
589.BR d ,
590.BR h ,
591.BR m ,
593.BR s ,
594for days, hours, minutes, or seconds, respectively.
13a55605 595.SP
3cdc3f3a 596.BI "bad-trace-option " char
598.BR TRACE .)
599An unknown trace option was requested.
13a55605 600.SP
3cdc3f3a 601.BI "bad-watch-option " char
603.BR WATCH .)
604An unknown watch option was requested.
13a55605 605.SP
f43df819 606.BI "daemon-error " ecode " " message
3cdc3f3a 607(For
608.BR DAEMON .)
609An error occurred during the attempt to become a daemon, as reported by
610.IR message .
13a55605 611.SP
3cdc3f3a 612.BI "invalid-port " number
614.BR ADD .)
615The given port number is out of range.
13a55605 616.SP
3cdc3f3a 617.BI "peer-create-fail " peer
619.BR ADD .)
621.I peer
622failed for some reason. A warning should have been emitted explaining
13a55605 624.SP
3cdc3f3a 625.BI "peer-exists " peer
627.BR ADD .)
628There is already a peer named
d6623498 629.IR peer .
13a55605 630.SP
0ba8de86 631.B "ping-send-failed"
632The attempt to send a ping packet failed, probably due to lack of
633encryption keys.
13a55605 634.SP
3cdc3f3a 635.BI "resolve-error " hostname
637.BR ADD .)
638The DNS name
639.I hostname
640could not be resolved.
13a55605 641.SP
3cdc3f3a 642.BI "resolver-timeout " hostname
644.BR ADD .)
645The DNS name
646.I hostname
647took too long to resolve.
13a55605 648.SP
3cdc3f3a 649.BI "unknown-command " token
650The command
651.B token
652was not recognised.
13a55605 653.SP
3cdc3f3a 654.BI "unknown-peer " name
656.BR ADDR ,
658.BR KILL ,
64cf2223 659.BR SETIFNAME ,
3cdc3f3a 660and
661.BR STATS .)
662There is no peer called
663.IR name .
13a55605 664.SP
3cdc3f3a 665.BI "unknown-service " service
667.BR ADD .)
668The service name
669.I service
670couldn't be found in
671.BR /etc/services .
13a55605 673.\"* 30 Notification broadcasts (NOTE codes)
3cdc3f3a 674The following notifications are sent to clients who request them.
13a55605 675.SP
42da2a58 676.BI "ADD " peer " " ifname " " address \fR...
3cdc3f3a 677A new peer has been added. The peer's name is
42da2a58 678.IR peer ,
679its tunnel is network interface
680.IR ifname ,
3cdc3f3a 681and its network address is
682.IR address .
13a55605 683.SP
3cdc3f3a 684.BI "DAEMON"
685The server has forked off into the sunset and become a daemon.
13a55605 686.SP
37941236 687.BI "GREET " challenge " " address \fR...
688A valid greeting was received, with the given challenge (exactly as it
689was returned by
13a55605 692.SP
d6623498 693.BI "KILL " peer
3cdc3f3a 694The peer
695.I peer
696has been killed.
13a55605 697.SP
3cdc3f3a 698.BI "KXDONE " peer
699Key exchange with
700.I peer
701finished successfully.
13a55605 702.SP
3cdc3f3a 703.BI "KXSTART " peer
704Key exchange with
705.I peer
706has begun or restarted. If key exchange keeps failing, this message
707will be repeated periodically.
13a55605 708.SP
709.BI "NEWIFNAME " peer " " old-name " " new-name
710The given
711.IR peer 's
712tunnel interface name has been changed from
713.I old-name
715.IR new-name ,
716as a result of a
bd58d532 720.BI "USER " tokens\fR...
721An administration client issued a notification using the
3cdc3f3a 724.SH "WARNINGS"
725.\"* 40 Warning broadcasts (WARN codes)
3cdc3f3a 727There are many possible warnings. They are categorized according to
728their first tokens.
730Many of these warnings report system errors. These are reported as a
731pair of tokens, described below as
732.I ecode
734.IR message .
736.I ecode
737is a string of the form
738.BI E number
739giving the
740.BR errno (3)
741value of the error; the
742.I message
743is the `human-readable' form of the message, as reported by
744.BR strerror (3).
3cdc3f3a 745.SS "ABORT warnings"
746These all indicate that the
d6623498 747.B tripe
3cdc3f3a 748server has become unable to continue. If enabled, the server will dump
749core in its configuration directory.
13a55605 750.SP
3cdc3f3a 751.BI "ABORT repeated-select-errors"
752The main event loop is repeatedly failing. If the server doesn't quit,
753it will probably waste all available CPU doing nothing.
754.SS "ADMIN warnings"
755These indicate a problem with the administration socket interface.
13a55605 756.SP
f43df819 757.BI "ADMIN accept-error " ecode " " message
3cdc3f3a 758There was an error while attempting to accept a connection from a new
13a55605 760.SP
f43df819 761.BI "ADMIN client-write-error " ecode " " message
3cdc3f3a 762There was an error sending data to a client. The connection to the
763client has been closed.
37941236 764.SS "CHAL warnings"
765These indicate errors in challenges, either in the
767command or in greeting packets.
13a55605 768.SP
37941236 769.B "CHAL impossible-challenge"
770The server hasn't issued any challenges yet. Quite how anyone else
771thought he could make one up is hard to imagine.
13a55605 772.SP
37941236 773.B "CHAL incorrect-tag"
774Challenge received contained the wrong authentication data. It might be
775very stale, or a forgery.
13a55605 776.SP
37941236 777.B "CHAL invalid-challenge"
778Challenge received was the wrong length. We might have changed MAC
779algorithms since the challenge was issued, or it might just be rubbish.
13a55605 780.SP
37941236 781.B "CHAL replay duplicated-sequence"
782Challenge received was a definite replay of an old challenge. Someone's
783up to something!
13a55605 784.SP
37941236 785.B "CHAL replay old-sequence"
786Challenge received was old, but maybe not actually a replay. Try again.
3cdc3f3a 787.SS "KEYMGMT warnings"
788These indicate a problem with the keyring files, or the keys stored in
13a55605 790.SP
f43df819 791.BI "KEYMGMT bad-private-key " message
3cdc3f3a 792The private key could not be read, or failed a consistency check. If
793there was a problem with the file, usually there will have been
794.B key-file-error
795warnings before this.
13a55605 796.SP
f43df819 797.BI "KEYMGMT bad-public-keyring " message
3cdc3f3a 798The public keyring couldn't be read. Usually, there will have been
799.B key-file-error
800warnings before this.
13a55605 801.SP
f43df819 802.BI "KEYMGMT key-file-error " file ":" line " " message
3cdc3f3a 803Reports a specific error with the named keyring file. This probably
804indicates a bug in
805.BR key (1).
13a55605 806.SP
3cdc3f3a 807.BI "KEYMGMT public-key " tag " " tokens\fR...
808These messages all indicate a problem with the public key named
809.IR tag .
13a55605 810.SP
3cdc3f3a 811.BI "KEYMGMT public-key " tag " algorithm-mismatch"
812The algorithms specified on the public key don't match the ones for our
813private key. All the peers in a network have to use the same
13a55605 815.SP
f43df819 816.BI "KEYMGMT public-key " tag " bad " message
3cdc3f3a 817The public key couldn't be read, or is invalid.
13a55605 818.SP
3cdc3f3a 819.BI "KEYMGMT public-key " tag " bad-public-group-element"
820The public key is invalid. This may indicate a malicious attempt to
821introduce a bogus key.
13a55605 822.SP
3cdc3f3a 823.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
824The algorithms listed on the public key couldn't be understood. The
825algorithm selection attributes are probably malformed and need fixing.
13a55605 826.SP
3cdc3f3a 827.BI "KEYMGMT public-key " tag " incorrect-group"
828The public key doesn't use the same group as our private key. All the
829peers in a network have to use the same group.
13a55605 830.SP
3cdc3f3a 831.BI "KEYMGMT public-key " tag " not-found"
832The public key for peer
833.I tag
834wasn't in the public keyring.
13a55605 835.SP
3cdc3f3a 836.BI "KEYMGMT public-key " tag " unknown-type"
837The type of the public key isn't understood. Maybe you need to upgrade
838your copy of
839.BR tripe .
840(Even if you do, you'll have to regenerate your keys.)
841.SS "KX warnings"
842These indicate problems during key-exchange. Many indicate either a bug
843in the server (either yours or the remote one), or some kind of attack
844in progress. All name a
845.I peer
846as the second token: this is the peer the packet is apparently from,
847though it may have been sent by an attacker instead.
849In the descriptions below,
850.I msgtoken
851is one of the tokens
852.BR pre-challenge ,
853.BR cookie ,
854.BR challenge ,
855.BR reply ,
856.BR switch-rq ,
858.BR switch-ok .
13a55605 859.SP
3cdc3f3a 860.BI "KX " peer " bad-expected-reply-log"
861The challenges
862.B tripe
863uses in its protocol contain a check value which proves that the
864challenge is honest. This message indicates that the check value
865supplied is wrong: someone is attempting to use bogus challenges to
866persuade your
867.B tripe
868server to leak private key information. No chance!
13a55605 869.SP
bd58d532 870.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
3cdc3f3a 871A symmetrically-encrypted portion of a key-exchange message failed to
13a55605 873.SP
3cdc3f3a 874.BI "KX " peer " invalid " msgtoken
875A key-exchange message was malformed. This almost certainly indicates a
876bug somewhere.
13a55605 877.SP
bd58d532 878.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
3cdc3f3a 879A message didn't contain the right magic data. This may be a replay of
880some old exchange, or random packets being sent in an attempt to waste
13a55605 882.SP
3cdc3f3a 883.BI "KX " peer " public-key-expired"
884The peer's public key has expired. It's maintainer should have given
885you a replacement before now.
13a55605 886.SP
3cdc3f3a 887.BI "KX " peer " sending-cookie"
888We've received too many bogus pre-challenge messages. Someone is trying
889to flood us with key-exchange messages and make us waste CPU on doing
890hard asymmetric crypto sums.
13a55605 891.SP
3cdc3f3a 892.BI "KX " peer " unexpected " msgtoken
893The message received wasn't appropriate for this stage of the key
894exchange process. This may mean that one of our previous packets got
895lost. For
896.BR pre-challenge ,
897it may simply mean that the peer has recently restarted.
13a55605 898.SP
3cdc3f3a 899.BI "KX " peer " unknown-challenge"
900The peer is asking for an answer to a challenge which we don't know
901about. This may mean that we've been inundated with challenges from
902some malicious source
903.I who can read our messages
904and discarded the valid one.
13a55605 905.SP
3cdc3f3a 906.BI "KX " peer " unknown-message 0x" nn
907An unknown key-exchange message arrived.
908.SS "PEER warnings"
909These are largely concerned with management of peers and the low-level
910details of the network protocol. The second word is usually the name of
911a peer, or
912.RB ` \- '
913if none is relevant.
13a55605 914.SP
3cdc3f3a 915.BI "PEER " peer " bad-packet no-type"
916An empty packet arrived. This is very strange.
13a55605 917.SP
3cdc3f3a 918.BI "PEER " peer " bad-packet unknown-category 0x" nn
919The message category
920.I nn
921(in hex) isn't understood. Probably a strange random packet from
922somewhere; could be an unlikely bug.
13a55605 923.SP
3cdc3f3a 924.BI "PEER " peer " bad-packet unknown-type 0x" nn
925The message type
926.I nn
927(in hex) isn't understood. Probably a strange random packet from
928somewhere; could be an unlikely bug.
13a55605 929.SP
0ba8de86 930.BI "PEER " peer " corrupt-encrypted-ping"
931The peer sent a ping response which matches an outstanding ping, but its
932payload is wrong. There's definitely a bug somewhere.
13a55605 933.SP
0ba8de86 934.BI "PEER " peer " corrupt-transport-ping"
935The peer (apparently) sent a ping response which matches an outstanding
936ping, but its payload is wrong. Either there's a bug, or the bad guys
937are playing tricks on you.
13a55605 938.SP
3cdc3f3a 939.BI "PEER " peer " decrypt-failed"
940An encrypted IP packet failed to decrypt. It may have been mangled in
941transit, or may be a very old packet from an expired previous session
942key. There is usually a considerable overlap in the validity periods of
943successive session keys, so this shouldn't occur unless the key exchange
944takes ages or fails.
13a55605 945.SP
0ba8de86 946.BI "PEER " peer " malformed-encrypted-ping"
947The peer sent a ping response which is hopelessly invalid. There's
948definitely a bug somewhere.
13a55605 949.SP
0ba8de86 950.BI "PEER " peer " malformed-transport-ping"
951The peer (apparently) sent a ping response which is hopelessly invalid.
952Either there's a bug, or the bad guys are playing tricks on you.
13a55605 953.SP
3cdc3f3a 954.BI "PEER " peer " packet-build-failed"
955There wasn't enough space in our buffer to put the packet we wanted to
956send. Shouldn't happen.
13a55605 957.SP
f43df819 958.BI "PEER \- socket-read-error " ecode " " message
3cdc3f3a 959An error occurred trying to read an incoming packet.
13a55605 960.SP
f43df819 961.BI "PEER " peer " socket-write-error " ecode " " message
3cdc3f3a 962An error occurred attempting to send a network packet. We lost that
13a55605 964.SP
0ba8de86 965.BI "PEER " peer " unexpected-encrypted-ping 0x" id
966The peer sent an encrypted ping response whose id doesn't match any
967outstanding ping. Maybe it was delayed for longer than the server was
968willing to wait, or maybe the peer has gone mad.
13a55605 969.SP
0ba8de86 970.BI "PEER \- unexpected-source " address\fR...
971A packet arrived from
972.I address
973(a network address \(en see above), but no peer is known at that
974address. This may indicate a misconfiguration, or simply be a result of
975one end of a connection being set up before the other.
13a55605 976.SP
0ba8de86 977.BI "PEER " peer " unexpected-transport-ping 0x" id
978The peer (apparently) sent a transport ping response whose id doesn't
979match any outstanding ping. Maybe it was delayed for longer than the
980server was willing to wait, or maybe the peer has gone mad; or maybe
981there are bad people trying to confuse you.
3cdc3f3a 982.SS "SERVER warnings"
983These indicate problems concerning the server process as a whole.
13a55605 984.SP
3cdc3f3a 985.BI "SERVER ignore signal " name
986A signal arrived, but the server ignored it. Currently this happens for
988because that's a popular way of telling daemons to re-read their
989configuration files. Since
990.B tripe
991re-reads its keyrings automatically and has no other configuration
992files, it's not relevant, but it seemed better to ignore the signal than
993let the server die.
13a55605 994.SP
3cdc3f3a 995.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
996A signal arrived and
997.B tripe
998is going to quit.
13a55605 999.SP
3cdc3f3a 1000.BI "SERVER quit admin-request"
1001A client of the administration interface issued a
1002.B QUIT
13a55605 1004.SP
f43df819 1005.BI "SERVER select-error " ecode " " message
3cdc3f3a 1006An error occurred in the server's main event loop. This is bad: if it
1007happens too many times, the server will abort.
1008.SS "SYMM warnings"
1009These are concerned with the symmetric encryption and decryption
13a55605 1011.SP
3cdc3f3a 1012.BI "SYMM replay old-sequence"
1013A packet was received with an old sequence number. It may just have
1014been delayed or duplicated, or it may have been an attempt at a replay
13a55605 1016.SP
3cdc3f3a 1017.BI "SYMM replay duplicated-sequence"
1018A packet was received with a sequence number we've definitely seen
1019before. It may be an accidental duplication because the 'net is like
1020that, or a deliberate attempt at a replay.
1021.SS "TUN warnings"
1022These concern the workings of the system-specific tunnel driver. The
1023second word is the name of the tunnel interface in question, or
1024.RB ` \- '
1025if none.
13a55605 1026.SP
3cdc3f3a 1027.BI "TUN \- bsd no-tunnel-devices"
1028The driver couldn't find an available tunnel device. Maybe if you
1029create some more
1030.BI /dev/tun nn
1031files, it will work.
13a55605 1032.SP
f43df819 1033.BI "TUN - " tun-name " open-error " device " " ecode " " message
3cdc3f3a 1034An attempt to open the tunnel device file
1035.I device
13a55605 1037.SP
f43df819 1038.BI "TUN \- linux config-error " ecode " " message
3cdc3f3a 1039Configuring the Linux TUN/TAP interface failed.
13a55605 1040.SP
f43df819 1041.BI "TUN " ifname " " tun-name " read-error " ecode " " message
42da2a58 1042Reading from the tunnel device failed.
13a55605 1043.SP
42da2a58 1044.BI "TUN " ifname " slip bad-escape"
1045The SLIP driver encountered a escaped byte it wasn't expecting to see.
1046The erroneous packet will be ignored.
13a55605 1047.SP
b9066fbb 1048.BI "TUN " ifname " slip eof"
1049The SLIP driver encountered end-of-file on its input descriptor.
1050Pending data is discarded, and no attempt is made to read any more data
1051from that interface ever.
13a55605 1052.SP
b9066fbb 1053.BI "TUN " ifname " slip escape-end"
1054The SLIP driver encountered an escaped `end' marker. This probably
1055means that someone's been sending it junk. The erroneous packet is
1056discarded, and we hope that we've rediscovered synchronization.
13a55605 1057.SP
f43df819 1058.BI "TUN \- slip fork-error " ecode " " message
42da2a58 1059The SLIP driver encountered an error forking a child process while
1060allocating a new dynamic interface.
13a55605 1061.SP
42da2a58 1062.BI "TUN \- slip no-slip-interfaces"
1063The driver ran out of static SLIP interfaces. Either preallocate more,
1064or use dynamic SLIP interface allocation.
13a55605 1065.SP
b9066fbb 1066.BI "TUN " ifname " slip overflow"
1067The SLIP driver gave up reading a packet because it got too large.
13a55605 1068.SP
f43df819 1069.BI "TUN \- slip pipe-error " ecode " " message
42da2a58 1070The SLIP driver encountered an error creating pipes while allocating a
1071new dynamic interface.
13a55605 1072.SP
f43df819 1073.BI "TUN \- slip read-ifname-failed " ecode " " message
42da2a58 1074The SLIP driver encountered an error reading the name of a dynamically
1075allocated interface. Maybe the allocation script is broken.
13a55605 1076.SP
f43df819 1077.BI "TUN \- unet config-error " ecode " " message
42da2a58 1078Configuring the Linux Unet interface failed. Unet is obsolete and
1079shouldn't be used any more.
13a55605 1080.SP
f43df819 1081.BI "TUN \- unet getinfo-error " ecode " " message
42da2a58 1082Reading information about the Unet interface failed. Unet is obsolete
1083and shouldn't be used any more.
13a55605 1084.SP
f43df819 1085.BI "TUN \- unet ifname-too-long"
42da2a58 1086The Unet interface's name overflowed, so we couldn't read it properly.
1087Unet is obsolete and shouldn't be used any more.
bd58d532 1088.SS "USER warnings"
1089These are issued by administration clients using the
1090.B WARN
13a55605 1092.SP
bd58d532 1093.BI "USER " tokens\fR...
1094An administration client issued a warning.
1097.SS "Command responses"
1099.BI "BGFAIL " tag " " tokens \fR...
1100.BI "BGINFO " tag " " tokens \fR...
1101.BI "BGOK " tag
1102.BI "FAIL " tokens \fR...
1103.BI "INFO " tokens \fR...
1104.B OK
1106.\"= summary
d6623498 1107.SH "SEE ALSO"
1108.BR tripectl (1),
1109.BR tripe (8).
3cdc3f3a 1111.IR "The Trivial IP Encryption Protocol" .
d6623498 1112.SH "AUTHOR"
d36eda2a 1113Mark Wooding, <>