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