chiark / gitweb /
configure.ac: Abolish use of `libtool'.
[tripe] / server / tripe-admin.5.in
1 .\" -*-nroff-*-
2 .\".
3 .\" Manual for the administration protocol
4 .\"
5 .\" (c) 2008 Straylight/Edgeware
6 .\"
7 .
8 .\"----- Licensing notice ---------------------------------------------------
9 .\"
10 .\" This file is part of Trivial IP Encryption (TrIPE).
11 .\"
12 .\" TrIPE is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
16 .\"
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20 .\" GNU General Public License for more details.
21 .\"
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25 .
26 .\"--------------------------------------------------------------------------
27 .so ../common/defs.man \" @@@PRE@@@
28 .
29 .\"--------------------------------------------------------------------------
30 .TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 tripe-admin \- administrator commands for TrIPE
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "DESCRIPTION"
39 .
40 This manual page describes the administration interface provided by the
41 .BR tripe (8)
42 daemon.
43 .PP
44 The
45 .BR tripectl (8)
46 program can be used either interactively or in scripts to communicate
47 with the server using this interface.  Alternatively, simple custom
48 clients can be written in scripting languages such as Perl, Python or
49 Tcl, or more advanced clients such as GUI monitors can be written in C
50 with little difficulty.
51 .PP
52 Administration commands use a textual protocol.  Each client command or
53 server response consists of a line of ASCII text terminated by a single
54 linefeed character.  No command may be longer than 255 characters.
55 .SS "General structure"
56 Each command or response line consists of a sequence of
57 whitespace-separated tokens.  The number and nature of whitespace
58 characters separating two tokens in a client command is not significant;
59 the server always uses a single space character.  The first token in a
60 line is a
61 .I keyword
62 identifying the type of command or response contained.  Keywords in
63 client commands are not case-sensitive; the server always uses uppercase
64 for its keywords.
65 .PP
66 In order to allow tokens to contain internal whitespace, a quoting
67 mechanism is provided.  Whitespace within matched pairs of quotes \(en
68 either single
69 .RB ` ' '
70 or double
71 .RB ` """" '
72 \(en is considered to be internal.  Any character (other than newline)
73 may be escaped by preceding it with a backslash
74 .RB ` \e ':
75 in particular, this can be used to include quote characters.  It is
76 impossible for a token to contain a newline character.
77 .PP
78 On output, the server will use double quotes when necessary.
79 .SS "Simple commands"
80 For simple client command, the server responds with zero or more
81 .B INFO
82 lines, followed by either an
83 .B OK
84 line or a
85 .B FAIL
86 line.  Each
87 .B INFO
88 provides information requested in the command.  An
89 .B OK
90 response contains no further data.  A
91 .B FAIL
92 code is followed by a machine-readable explanation of why the command
93 failed.
94 .PP
95 Simple command processing is strictly synchronous: the server reads a
96 command, processes it, and responds, before reading the next command.
97 All commands can be run as simple commands.  Long-running commands
98 (e.g.,
99 .B ADD
100 and
101 .BR PING )
102 block the client until they finish, but the rest of the server continues
103 running.  See
104 .B "Background commands"
105 to find out how to issue long-running commands without blocking.
106 .SS "Asynchronous broadcasts"
107 There are three types of asynchronous broadcast messages which aren't
108 associated with any particular command.  Clients can select which
109 broadcast messages they're interested in using the
110 .B WATCH
111 command.
112 .PP
113 The
114 .B WARN
115 message contains a machine-readable message warning of an error
116 encountered while processing a command, unexpected or unusual behaviour
117 by a peer, or a possible attack by an adversary.  Under normal
118 conditions, the server shouldn't emit any warnings.
119 .PP
120 The
121 .B TRACE
122 message contains a human-readable tracing message containing diagnostic
123 information.  Trace messages are controlled using the
124 .B \-T
125 command-line option to the server, or the
126 .B TRACE
127 administration command (see below).  Support for tracing can be disabled
128 when the package is being configured, and may not be available in your
129 version.
130 .PP
131 Finally, the
132 .B NOTE
133 message is a machine-readable notification about some routine but
134 interesting event such as creation or destruction of peers.
135 .SS "Background commands"
136 Some commands (e.g.,
137 .B ADD
138 and
139 .BR PING )
140 take a long time to complete.  To prevent these long-running commands
141 from tying up a server connection, they can be run in the background.
142 Not all commands can be run like this: the ones that can provide a
143 .B \-background
144 option, which must be supplied with a
145 .IR tag .
146 .PP
147 A command may fail before it starts running in the background.  In this
148 case, the server emits a
149 .B FAIL
150 response, as usual.  To indicate that a command has started running in
151 the background, the server emits a response of the form
152 .BI "BGDETACH " tag \fR,
153 where
154 .I tag
155 is the value passed to the
156 .B \-background
157 option.  From this point on, the server is ready to process more
158 commands and reply to them.
159 .PP
160 Responses to background commands are indicated by a line beginning with
161 one of the tokens
162 .BR BGOK ,
163 .BR BGFAIL ,
164 or
165 .BR BGINFO ,
166 followed by the command tag.  These correspond to the
167 .BR OK ,
168 .BR FAIL ,
169 and
170 .B INFO
171 responses for simple commands:
172 .B BGINFO
173 indicates information from a background command which has not completed
174 yet; and
175 .B BGOK
176 and
177 .B BGFAIL
178 indicates that a background command succeeded or failed, respectively.
179 .PP
180 A background command will never issue an
181 .B OK
182 or
183 .B INFO
184 response: it will always detach and then issue any
185 .B BGINFO
186 lines followed by
187 .B BGOK
188 response.
189 .SS "Client-provided services"
190 .\"* 25 Service-related messages
191 An administration client can provide services to other clients.
192 Services are given names and versions.  A client can attempt to
193 .I claim
194 a particular service by issuing the
195 .B SVCCLAIM
196 command.  This may fail, for example, if some other client already
197 provides the same or later version of the service.
198 .PP
199 Other clients can issue
200 .I "service commands"
201 using the
202 .B "SVCSUBMIT"
203 command; the service provider is expected to handle these commands and
204 reply to them.
205 .PP
206 There are three important asynchronous messages which will be sent to
207 service providers.
208 .SP
209 .BI "SVCCANCEL " jobid
210 The named job has been cancelled, either because the issuing client has
211 disconnected or explicitly cancelled the job using the
212 .B BGCANCEL
213 command.
214 .SP
215 .BI "SVCCLAIM " service " " version
216 Another client has claimed a later version of the named
217 .IR service .
218 The recipient is no longer the provider of this service.
219 .SP
220 .BI "SVCJOB " jobid " " service " " command " " args \fR...
221 Announces the arrival of a new job.  The
222 .I jobid
223 is a simple token consisting of alphanumeric characters which
224 .B tripe
225 uses to identify this job.
226 .PP
227 The service provider can reply to the job using the commands
228 .BR SVCINFO ,
229 .B SVCOK
230 and
231 .BR SVCFAIL .
232 The first of these sends an
233 .B INFO
234 response and leaves the job active; the other two send an
235 .B OK
236 or
237 .B FAIL
238 response respectively, and mark the job as being complete.
239 .PP
240 (Since
241 .B SVCSUBMIT
242 is a potentially long-running command, it can be run in the background.
243 This detail is hidden from service providers:
244 .B tripe
245 will issue the corresponding
246 .BR BG ...
247 responses when appropriate.)
248 .SS "Network addresses"
249 A network address is a sequence of tokens.  The first is a token
250 identifying the network address family.  The length of an address and
251 the meanings of the subsequent tokens depend on the address family.
252 Address family tokens are not case-sensitive on input; on output, they
253 are always in upper-case.
254 .PP
255 At present, only one address family is understood.
256 .TP
257 .BI "INET " address " \fR[" port \fR]
258 An Internet socket, naming an IPv4 address and UDP port.  On output, the
259 address is always in numeric dotted-quad form, and the port is given as
260 a plain number.  On input, DNS hostnames and symbolic port names are
261 permitted; if omitted, the default port 4070 is used.  Name resolution
262 does not block the main server, but will block the requesting client,
263 unless the command is run in the background.
264 .PP
265 If, on input, no recognized address family token is found, the following
266 tokens are assumed to represent an
267 .B INET
268 address.  Addresses output by the server always have an address family
269 token.
270 .SS "Key-value output"
271 Some commands (e.g.,
272 .B STATS
273 and
274 .BR SERVINFO )
275 produce output in the form of
276 .IB key = value
277 pairs, one per token.  Neither the
278 .I key
279 nor the
280 .I value
281 contain spaces.
282 .SS "Trace lists"
283 Commands which enable or disable kinds of output (e.g.,
284 .B TRACE
285 and
286 .BR WATCH )
287 work in similar ways.  They take a single optional argument, which
288 consists of a string of letters selecting message types, optionally
289 interspersed with
290 .RB ` + '
291 to enable, or
292 .RB ` \- '
293 to disable, the subsequently listed types.
294 .PP
295 If the argument is omitted, the available message types are displayed,
296 one to an
297 .B INFO
298 line, in a fixed-column format.  Column zero contains the key letter for
299 selecting that message type; column one contains either a space or a
300 .RB ` + '
301 sign, if the message type is disabled or enabled respectively; and a
302 textual description of the message type begins at column 3 and continues
303 to the end of the line.
304 .PP
305 Lowercase key letters control individual message types.  Uppercase key
306 letters control collections of message types.
307 .
308 .\"--------------------------------------------------------------------------
309 .SH "COMMAND REFERENCE"
310 .
311 .\"* 10 Commands
312 The commands provided are:
313 .SP
314 .BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
315 Adds a new peer.  The peer is given the name
316 .IR peer ;
317 the peer's public key is assumed to be in the file
318 .B keyring.pub
319 (or whatever alternative file was specified in the
320 .B \-K
321 option on the command line).  The
322 .I address
323 is the network address (see above for the format) at which the peer can
324 be contacted.  The following options are recognized.
325 .RS
326 .\"+opts
327 .TP
328 .BI "\-background " tag
329 Run the command in the background, using the given
330 .IR tag .
331 .TP
332 .B "\-cork"
333 Don't send an immediate challenge to the peer; instead, wait until it
334 sends us something before responding.
335 .TP
336 .BI "\-keepalive " time
337 Send a no-op packet if we've not sent a packet to the peer in the last
338 .I time
339 interval.  This is useful for persuading port-translating firewalls to
340 believe that the `connection' is still active.  The
341 .I time
342 is expressed as a nonnegative integer followed optionally by
343 .BR d ,
344 .BR h ,
345 .BR m ,
346 or
347 .BR s
348 for days, hours, minutes, or seconds respectively; if no suffix is
349 given, seconds are assumed.
350 .TP
351 .BI "\-key " tag
352 Use the public key
353 .I tag
354 to authenticate the peer.  The default is to use the key tagged
355 .IR peer .
356 .TP
357 .B "\-mobile"
358 The peer is a mobile device, and is likely to change address rapidly.
359 If a packet arrives from an unknown address, the server's usual response
360 is to log a warning and discard it.  If the server knows of any mobile
361 peers, however, it will attempt to decrypt the packet using their keys,
362 and if one succeeds, the server will update its idea of the peer's
363 address and emit an
364 .B NEWADDR
365 notification.
366 .TP
367 .BI "\-priv " tag
368 Use the private key
369 .I tag
370 to authenticate to the peer.  The default is to use the key named in the
371 .RB ` \-t '
372 command-line option, or a key with type
373 .B tripe
374 or
375 .BR tripe-dh :
376 see
377 .BR tripe (8)
378 for the details.
379 .TP
380 .BI "\-tunnel " tunnel
381 Use the named tunnel driver, rather than the default.
382 .\"-opts
383 .RE
384 .SP
385 .BI "ADDR " peer
386 Emits an
387 .B INFO
388 line reporting the IP address and port number stored for
389 .IR peer .
390 .SP
391 .BI "ALGS \fR[" peer \fR]
392 Emits information about the cryptographic algorithms in use, in
393 key-value form.  If a
394 .I peer
395 is given, then describe the algorithms used in the association with that
396 peer; otherwise describe the default algorithms.
397 .RS
398 .PP
399 The keys are as follows.
400 .TP
401 .B kx-group
402 Type of key-exchange group in use, currently either
403 .B ec
404 or
405 .BR prime .
406 .TP
407 .B kx-group-order-bits
408 Length of the group order, in bits.  This gives an approximate measure
409 of the group strength.
410 .TP
411 .B kx-group-elt-bits
412 Length of a group element, in bits.  This may be useful when analyzing
413 protocol traces.
414 .TP
415 .B hash
416 The hash function in use, e.g.,
417 .BR sha256 .
418 .TP
419 .B mgf
420 The mask-generating function in use, e.g.,
421 .BR whirlpool-mgf .
422 .TP
423 .B hashsz
424 The size of the hash function's output, in octets.
425 .TP
426 .B bulk-transform
427 The name of the bulk-crypto transform.
428 .TP
429 .B bulk-overhead
430 The amount of overhead, in bytes, caused by the crypto transform.
431 .TP
432 .B cipher
433 The name of the bulk data cipher in use, e.g.,
434 .BR blowfish-cbc .
435 .TP
436 .B cipher-keysz
437 The length of key used by the bulk data cipher, in octets.
438 .TP
439 .B cipher-blksz
440 The block size of the bulk data cipher, or zero if it's not based on a
441 block cipher.
442 .TP
443 .B cipher-data-limit
444 The maximum amount of data to be encrypted using a single key.  (A new
445 key exchange is instigated well before the limit is reached, in order to
446 allow for a seamless changeover of keys.)
447 .TP
448 .B mac
449 The message authentication algorithm in use, e.g.,
450 .BR ripemd160-hmac .
451 .TP
452 .B mac-keysz
453 The length of the key used by the message authentication algorithm, in
454 octets.
455 .TP
456 .B mac-tagsz
457 The length of the message authentication tag, in octets.
458 .TP
459 .B blkc
460 The block cipher in use, e.g.,
461 .BR blowfish .
462 .TP
463 .B blkc-keysz
464 The length of key used by the block cipher, in octets.
465 .TP
466 .B blkc-blksz
467 The block size of the block cipher.
468 .PP
469 The various sizes are useful, for example, when computing the MTU for a
470 tunnel interface.  If
471 .I MTU
472 is the MTU of the path to the peer, then the tunnel MTU should be
473 .IP
474 .I MTU
475 \- 29 \-
476 .I bulk-overhead
477 .PP
478 allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
479 octet, and the bulk-crypto transform overhead (which includes the
480 sequence number).
481 .RE
482 .SP
483 .BI "BGCANCEL " tag
484 Cancels the background job with the named
485 .IR tag .
486 .SP
487 .BI "CHECKCHAL " challenge
488 Verifies a challenge as being one earlier issued by
489 .B GETCHAL
490 and not previously either passed to
491 .B CHECKCHAL
492 or in a greeting message.
493 .SP
494 .B "DAEMON"
495 Causes the server to disassociate itself from its terminal and become a
496 background task.  This only works once.  A notification is issued.
497 .SP
498 .BI "EPING \fR[" options "\fR] " peer
499 Sends an encrypted ping to the peer, and expects an encrypted response.
500 This checks that the peer is running (and not being impersonated), and
501 that it can encrypt and decrypt packets correctly.  Options and
502 responses are the same as for the
503 .B PING
504 command.
505 .SP
506 .BI "FORCEKX " peer
507 Requests the server to begin a new key exchange with
508 .I peer
509 immediately.
510 .SP
511 .B "GETCHAL"
512 Requests a challenge.  The challenge is returned in an
513 .B INFO
514 line, as a base64-encoded string.  See
515 .BR CHECKCHAL .
516 .SP
517 .BI "GREET " peer " " challenge
518 Sends a greeting packet containing the
519 .I challenge
520 (base-64 encoded) to the named
521 .IR peer .
522 The expectation is that this will cause the peer to recognize us and
523 begin a key-exchange.
524 .SP
525 .B "HELP"
526 Causes the server to emit an
527 .B INFO
528 line for each command it supports.  Each line lists the command name,
529 followed by the names of the arguments.  This may be helpful as a memory
530 aid for interactive use, or for program clients probing for features.
531 .SP
532 .BI "IFNAME " peer
533 Emits an
534 .B INFO
535 line containing the name of the network interface used to collect IP
536 packets which are to be encrypted and sent to
537 .IR peer .
538 Used by configuration scripts so that they can set up routing tables
539 appropriately after adding new peers.
540 .SP
541 .B "JOBS"
542 Emits an
543 .B INFO
544 line giving the tag for each outstanding background job.
545 .SP
546 .BI "KILL " peer
547 Causes the server to forget all about
548 .IR peer .
549 All keys are destroyed, and no more packets are sent.  No notification
550 is sent to the peer: if it's important that the peer be notified, you
551 must think of a way to do that yourself.
552 .SP
553 .B "LIST"
554 For each currently-known peer, an
555 .B INFO
556 line is written containing the peer's name, as given to
557 .BR ADD .
558 .SP
559 .BI "NOTIFY " tokens\fR...
560 Issues a
561 .B USER
562 notification to all interested administration clients.
563 .SP
564 .BI "PEERINFO " peer
565 Returns information about a peer, in key-value form.  The following keys
566 are returned.
567 .RS
568 .TP
569 .B tunnel
570 The tunnel driver used for this peer.
571 .TP
572 .B keepalive
573 The keepalive interval, in seconds, or zero if no keepalives are to be
574 sent.
575 .TP
576 .B key
577 The (short) key tag being used for the peer, as passed to the
578 .B ADD
579 command.
580 .TP
581 .B current-key
582 The full key tag of the peer's public key currently being used.  This
583 may change during the life of the association.
584 .TP
585 .B private-key
586 The private key tag being used for the peer, as passed to the
587 .B ADD
588 command, or the
589 .RB ` \-t '
590 command-line option.  If neither of these was given explicitly, the
591 private key tag is shown as
592 .RB ` (default) ',
593 since there is no fixed tag used under these circumstances.
594 .TP
595 .B current-private-key
596 The full key tag of the private key currently being used for this
597 association.  This may change during the life of the association.
598 .RE
599 .SP
600 .BI "PING \fR[" options "\fR] " peer
601 Send a transport-level ping to the peer.  The ping and its response are
602 not encrypted or authenticated.  This command, possibly in conjunction
603 with tracing, is useful for ensuring that UDP packets are actually
604 flowing in both directions.  See also the
605 .B EPING
606 command.
607 .IP
608 An
609 .B INFO
610 line is printed describing the outcome:
611 .RS
612 .TP
613 .BI "ping-ok " millis
614 A response was received
615 .I millis
616 after the ping was sent.
617 .TP
618 .BI "ping-timeout"
619 No response was received within the time allowed.
620 .TP
621 .BI "ping-peer-died"
622 The peer was killed (probably by another admin connection) before a
623 response was received.
624 .RE
625 .IP
626 Options recognized for this command are:
627 .RS
628 .\"+opts
629 .TP
630 .BI "\-background " tag
631 Run the command in the background, using the given
632 .IR tag .
633 .TP
634 .BI "\-timeout " time
635 Wait for
636 .I time
637 seconds before giving up on a response.  The default is 5 seconds.  The
638 .I time
639 is expressed as a nonnegative integer followed optionally by
640 .BR d ,
641 .BR h ,
642 .BR m ,
643 or
644 .BR s
645 for days, hours, minutes, or seconds respectively; if no suffix is
646 given, seconds are assumed.
647 .\"-opts
648 .RE
649 .SP
650 .B "PORT"
651 Emits an
652 .B INFO
653 line containing just the number of the UDP port used by the
654 .B tripe
655 server.  If you've allowed your server to allocate a port dynamically,
656 this is how to find out which one it chose.
657 .SP
658 .B "RELOAD"
659 Instructs the server to recheck its keyring files.  The server checks
660 these periodically anyway but it may be necessary to force a recheck,
661 for example after adding a new peer key.
662 .SP
663 .B "QUIT"
664 Instructs the server to exit immediately.  A warning is sent.
665 .SP
666 .B "SERVINFO"
667 Returns information about the server, in the form of key-value pairs.
668 The following keys are used.
669 .RS
670 .TP
671 .B implementation
672 A keyword naming the implementation of the
673 .BR tripe (8)
674 server.  The current implementation is called
675 .BR edgeware-tripe .
676 .TP
677 .B version
678 The server's version number, as reported by
679 .BR VERSION .
680 .TP
681 .B daemon
682 Either
683 .B t
684 or
685 .BR nil ,
686 if the server has or hasn't (respectively) become a daemon.
687 .RE
688 .SP
689 .BI "SETIFNAME " peer " " new-name
690 Informs the server that the
691 .IR peer 's
692 tunnel-interface name has been changed to
693 .IR new-name .
694 This is useful if firewalling decisions are made based on interface
695 names: a setup script for a particular peer can change the name, and
696 then update the server's records so that they're accurate.
697 .SP
698 .BI "SVCCLAIM " service " " version
699 Attempts to claim the named
700 .IR service ,
701 offering the given
702 .IR version .
703 The claim is successful if the service is currently unclaimed, or if
704 a version earlier than
705 .I version
706 is provided; otherwise the command fails with the error
707 .BR "service-exists" .
708 .SP
709 .BI "SVCENSURE " service " \fR[" version \fR]
710 Ensure that
711 .I service
712 is provided, and (if specified) to at least the given
713 .IR version .
714 An error is reported if these conditions are not met; otherwise the
715 command succeeds silently.
716 .SP
717 .BI "SVCFAIL " jobid " " tokens \fR...
718 Send a
719 .B FAIL
720 (or
721 .BR BGFAIL )
722 response to the service job with the given
723 .IR jobid ,
724 passing the
725 .I tokens
726 as the reason for failure.  The job is closed.
727 .SP
728 .BI "SVCINFO " jobid " " tokens \fR...
729 Send an
730 .B INFO
731 (or
732 .BR BGINFO )
733 response to the service job with the given
734 .IR jobid ,
735 passing the
736 .I tokens
737 as the info message.  The job remains open.
738 .SP
739 .B "SVCLIST"
740 Output a line of the form
741 .RS
742 .IP
743 .B INFO
744 .I service
745 .I version
746 .PP
747 for each service currently provided.
748 .RE
749 .SP
750 .BI "SVCOK " jobid
751 Send an
752 .B OK
753 (or
754 .BR BGINFO )
755 response to the service job with the given
756 .IR jobid .
757 The job is closed.
758 .SP
759 .BI "SVCQUERY " service
760 Emits a number of
761 .B info
762 lines in key-value format, describing the named
763 .IR service.
764 The following keys are used.
765 .RS
766 .TP
767 .B name
768 The service's name.
769 .TP
770 .B version
771 The service's version string.
772 .RE
773 .SP
774 .BI "SVCRELEASE " service
775 Announce that the client no longer wishes to provide the named
776 .IR service .
777 .SP
778 .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
779 Submit a job to the provider of the given
780 .IR service ,
781 passing it the named
782 .I command
783 and the given
784 .IR arguments .
785 The following options are accepted.
786 .RS
787 .\"+opts
788 .TP
789 .BI "\-background " tag
790 Run the command in the background, using the given
791 .IR tag .
792 .TP
793 .BI "\-version " version
794 Ensure that at least the given
795 .I version
796 of the service is available before submitting the job.
797 .RE
798 .\"-opts
799 .SP
800 .BI "STATS " peer
801 Emits a number of
802 .B INFO
803 lines, each containing one or more statistics in the form
804 .IB name = value \fR.
805 The statistics-gathering is experimental and subject to change.
806 .SP
807 .BR "TRACE " [\fIoptions\fP]
808 Selects trace outputs: see
809 .B "Trace lists"
810 above.  Message types provided are:
811 .RS
812 .PP
813 Currently, the following tracing options are supported:
814 .TP
815 .B t
816 Tunnel events: reception of packets to be encrypted, and injection of
817 successfully-decrypted packets.
818 .TP
819 .B r
820 Peer management events: creation and destruction of peer attachments,
821 and arrival of messages.
822 .TP
823 .B a
824 Administration interface: acceptance of new connections, and handling of
825 the backgroud name-resolution required by the
826 .B ADD
827 command.
828 .TP
829 .B s
830 Handling of symmetric keysets: creation and expiry of keysets, and
831 encryption and decryption of messages.
832 .TP
833 .B x
834 Key exchange: reception, parsing and emission of key exchange messages.
835 .TP
836 .B m
837 Key management: loading keys and checking for file modifications.
838 .TP
839 .B l
840 Display information about challenge issuing and verification.
841 .TP
842 .B p
843 Display contents of packets sent and received by the tunnel and/or peer
844 modules.
845 .TP
846 .B c
847 Display inputs, outputs and intermediate results of cryptographic
848 operations.  This includes plaintext and key material.  Use with
849 caution.
850 .TP
851 .B A
852 All of the above.
853 .PP
854 Note that the
855 .B p
856 (packet contents)
857 and
858 .B c
859 (crypto details)
860 outputs provide extra detail for other outputs.  Specifying
861 .B p
862 without
863 .BR r
864 or
865 .B t
866 isn't useful; neither is specifying
867 .B c
868 without one of
869 .BR s ,
870 .BR l ,
871 .B x
872 or
873 .BR m .
874 .RE
875 .SP
876 .B "TUNNELS"
877 For each available tunnel driver, an
878 .B INFO
879 line is printed giving its name.
880 .SP
881 .B "VERSION"
882 Causes the server to emit an
883 .B INFO
884 line stating its software version, as two tokens: the server name, and
885 its version string.  The server name
886 .B tripe
887 is reserved to the Straylight/Edgeware implementation.
888 .SP
889 .BR "WATCH " [\fIoptions\fP]
890 Enables or disables asynchronous broadcasts
891 .IR "for the current connection only" .
892 See
893 .B "Trace lists"
894 above.  The default watch state for the connection the server opens
895 automatically on stdin/stdout is to show warnings and trace messages;
896 other connections show no asynchronous broadcast messages.  (This is
897 done in order to guarantee that a program reading the server's stdout
898 does not miss any warnings.)
899 .RS
900 .PP
901 Message types provided are:
902 .TP
903 .B t
904 .B TRACE
905 messages.
906 .TP
907 .B n
908 .B NOTE
909 messages.
910 .TP
911 .B w
912 .B WARN
913 messages.
914 .TP
915 .B A
916 All of the above.
917 .RE
918 .SP
919 .BI "WARN " tokens\fR...
920 Issues a
921 .B USER
922 warning to all interested administration clients.
923 .
924 .\"--------------------------------------------------------------------------
925 .SH "ERROR MESSAGES"
926 .
927 .\"* 20 Error messages (FAIL codes)
928 The following
929 .B FAIL
930 (or
931 .BR BGFAIL )
932 messages are sent to clients as a result of errors during command
933 processing.
934 .SP
935 .BI "already-daemon"
936 (For
937 .BR DAEMON .)
938 The
939 .B tripe
940 server is already running as a daemon.
941 .SP
942 .BI "bad-addr-syntax " message
943 (For commands accepting socket addresses.)  The address couldn't be
944 understood.
945 .SP
946 .BI "bad-syntax " cmd " " message
947 (For any command.)  The command couldn't be understood: e.g., the number
948 of arguments was wrong.
949 .SP
950 .BI "bad-time-spec " token
951 The
952 .I token
953 is not a valid time interval specification.  Acceptable time
954 specifications are nonnegative integers followed optionally by
955 .BR d ,
956 .BR h ,
957 .BR m ,
958 or
959 .BR s ,
960 for days, hours, minutes, or seconds, respectively.
961 .SP
962 .BI "bad-trace-option " char
963 (For
964 .BR TRACE .)
965 An unknown trace option was requested.
966 .SP
967 .BI "bad-watch-option " char
968 (For
969 .BR WATCH .)
970 An unknown watch option was requested.
971 .SP
972 .BI "daemon-error " ecode " " message
973 (For
974 .BR DAEMON .)
975 An error occurred during the attempt to become a daemon, as reported by
976 .IR message .
977 .SP
978 .BI "invalid-port " number
979 (For
980 .BR ADD .)
981 The given port number is out of range.
982 .SP
983 .BI "not-service-provider " service
984 (For
985 .BR SVCRELEASE .)
986 The invoking client is not the current provider of the named
987 .IR service ,
988 and is therefore not allowed to release it.
989 .SP
990 .BI "peer-create-fail " peer
991 (For
992 .BR ADD .)
993 Adding
994 .I peer
995 failed for some reason.  A warning should have been emitted explaining
996 why.
997 .SP
998 .BI "peer-addr-exists " address\fR...
999 (For
1000 .BR ADD .)
1001 There is already a peer with the given
1002 .IR address .
1003 .SP
1004 .BI "peer-exists " peer
1005 (For
1006 .BR ADD .)
1007 There is already a peer named
1008 .IR peer .
1009 .SP
1010 .B "ping-send-failed"
1011 The attempt to send a ping packet failed, probably due to lack of
1012 encryption keys.
1013 .SP
1014 .BI "resolve-error " hostname
1015 (For
1016 .BR ADD .)
1017 The DNS name
1018 .I hostname
1019 could not be resolved.
1020 .SP
1021 .BI "resolver-timeout " hostname
1022 (For
1023 .BR ADD .)
1024 The DNS name
1025 .I hostname
1026 took too long to resolve.
1027 .SP
1028 .BI "service-exists " service " " version
1029 (For
1030 .BR SVCCLAIM .)
1031 Another client is already providing the stated
1032 .I version
1033 of the
1034 .IR service .
1035 .SP
1036 .BI "service-too-old " service " " version
1037 (For
1038 .B SVCENSURE
1039 and
1040 .BR SVCSUBMIT .)
1041 Only the given
1042 .I version
1043 of the requested
1044 .I service
1045 is available, which does not meet the stated requirements.
1046 .SP
1047 .BI "tag-exists " tag
1048 (For long-running commands.)  The named
1049 .I tag
1050 is already the tag of an outstanding job.
1051 .SP
1052 .BI "unknown-command " token
1053 The command
1054 .I token
1055 was not recognized.
1056 .SP
1057 .BI "unknown-jobid " jobid
1058 (For
1059 .BR SVCOK ,
1060 .BR SVCFAIL ,
1061 and
1062 .BR SVCINFO .)
1063 The token
1064 .I jobid
1065 is not recognized as identifying an outstanding job.  It may have just
1066 been cancelled.
1067 .SP
1068 .BI "unknown-peer " name
1069 (For
1070 .BR ADDR ,
1071 .BR IFNAME ,
1072 .BR KILL ,
1073 .BR SETIFNAME ,
1074 and
1075 .BR STATS .)
1076 There is no peer called
1077 .IR name .
1078 .SP
1079 .BI "unknown-port " port
1080 (For
1081 .BR ADD .)
1082 The port name
1083 .I port
1084 couldn't be found in
1085 .BR /etc/services .
1086 .TP
1087 .BI "unknown-service " service
1088 (For
1089 .BR SVCENSURE ,
1090 .BR SVCQUERY ,
1091 .BR SVCRELEASE ,
1092 and
1093 .BR SVCSUBMIT .)
1094 The token
1095 .I service
1096 is not recognized as the name of a client-provided service.
1097 .TP
1098 .BI "unknown-tag " tag
1099 (For
1100 .BR BGCANCEL .)
1101 The given
1102 .I tag
1103 is not the tag for any outstanding background job.  It may have just
1104 finished.
1105 .
1106 .\"--------------------------------------------------------------------------
1107 .SH "NOTIFICATIONS"
1108 .
1109 .\"* 30 Notification broadcasts (NOTE codes)
1110 The following notifications are sent to clients who request them.
1111 .SP
1112 .BI "ADD " peer " " ifname " " address \fR...
1113 A new peer has been added.  The peer's name is
1114 .IR peer ,
1115 its tunnel is network interface
1116 .IR ifname ,
1117 and its network address is
1118 .IR address .
1119 .SP
1120 .BI "DAEMON"
1121 The server has forked off into the sunset and become a daemon.
1122 .SP
1123 .BI "GREET " challenge " " address \fR...
1124 A valid greeting was received, with the given challenge (exactly as it
1125 was returned by
1126 .B GETCHAL
1127 earlier).
1128 .SP
1129 .BI "KILL " peer
1130 The peer
1131 .I peer
1132 has been killed.
1133 .SP
1134 .BI "KXDONE " peer
1135 Key exchange with
1136 .I peer
1137 finished successfully.
1138 .SP
1139 .BI "KXSTART " peer
1140 Key exchange with
1141 .I peer
1142 has begun or restarted.  If key exchange keeps failing, this message
1143 will be repeated periodically.
1144 .SP
1145 .BI "NEWADDR " peer " " address
1146 The given mobile
1147 .IR peer 's
1148 IP address has been changed to
1149 .IR address .
1150 .SP
1151 .BI "NEWIFNAME " peer " " old-name " " new-name
1152 The given
1153 .IR peer 's
1154 tunnel interface name has been changed from
1155 .I old-name
1156 to
1157 .IR new-name ,
1158 as a result of a
1159 .B SETIFNAME
1160 command.
1161 .SP
1162 .BI "SVCCLAIM " service " " version
1163 The named
1164 .I service
1165 is now available, at the stated
1166 .IR version .
1167 .SP
1168 .BI "SVCRELEASE " service
1169 The named
1170 .I service
1171 is no longer available.
1172 .SP
1173 .BI "USER " tokens\fR...
1174 An administration client issued a notification using the
1175 .B NOTIFY
1176 command.
1177 .
1178 .\"--------------------------------------------------------------------------
1179 .SH "WARNINGS"
1180 .
1181 .\"* 40 Warning broadcasts (WARN codes)
1182 .\"+sep
1183 There are many possible warnings.  They are categorized according to
1184 their first tokens.
1185 .PP
1186 Many of these warnings report system errors.  These are reported as a
1187 pair of tokens, described below as
1188 .I ecode
1189 and
1190 .IR message .
1191 The
1192 .I ecode
1193 is a string of the form
1194 .BI E number
1195 giving the
1196 .BR errno (3)
1197 value of the error; the
1198 .I message
1199 is the `human-readable' form of the message, as reported by
1200 .BR strerror (3).
1201 .SS "ABORT warnings"
1202 These all indicate that the
1203 .B tripe
1204 server has become unable to continue.  If enabled, the server will dump
1205 core in its configuration directory.
1206 .SP
1207 .BI "ABORT repeated-select-errors"
1208 The main event loop is repeatedly failing.  If the server doesn't quit,
1209 it will probably waste all available CPU doing nothing.
1210 .SS "ADMIN warnings"
1211 These indicate a problem with the administration socket interface.
1212 .SP
1213 .BI "ADMIN accept-error " ecode " " message
1214 There was an error while attempting to accept a connection from a new
1215 client.
1216 .SP
1217 .BI "ADMIN client-write-error " ecode " " message
1218 There was an error sending data to a client.  The connection to the
1219 client has been closed.
1220 .SS "CHAL warnings"
1221 These indicate errors in challenges, either in the
1222 .B CHECKCHAL
1223 command or in greeting packets.
1224 .SP
1225 .B "CHAL impossible-challenge"
1226 The server hasn't issued any challenges yet.  Quite how anyone else
1227 thought he could make one up is hard to imagine.
1228 .SP
1229 .B "CHAL incorrect-tag"
1230 Challenge received contained the wrong authentication data.  It might be
1231 very stale, or a forgery.
1232 .SP
1233 .B "CHAL invalid-challenge"
1234 Challenge received was the wrong length.  We might have changed MAC
1235 algorithms since the challenge was issued, or it might just be rubbish.
1236 .SP
1237 .B "CHAL replay duplicated-sequence"
1238 Challenge received was a definite replay of an old challenge.  Someone's
1239 up to something!
1240 .SP
1241 .B "CHAL replay old-sequence"
1242 Challenge received was old, but maybe not actually a replay.  Try again.
1243 .SS "KEYMGMT warnings"
1244 These indicate a problem with the keyring files, or the keys stored in
1245 them.  The first token is either
1246 .B private-keyring
1247 or
1248 .B public-keyring
1249 (notated
1250 .IB which -keyring
1251 in the descriptions below) indicating which keyring file is problematic,
1252 and the second token is the filename of the keyring.  Frequently a key
1253 tag may be given next, preceded by the token
1254 .BR key .
1255 .SP
1256 .BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
1257 The private key doesn't record the correct corresponding public key.
1258 .SP
1259 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
1260 A peer's public key doesn't request the same algorithms as our private
1261 key.
1262 .SP
1263 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len
1264 The key attributes specify the length of MAC tag as
1265 .I len
1266 but this is an invalid value \(en either too large or not a multiple of
1267 eight.
1268 .SP
1269 .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str
1270 The key attributes contain
1271 .I str
1272 where a MAC tag length was expected.  The key was generated wrongly.
1273 .SP
1274 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
1275 The private keyring has been changed, but the new private key can't be
1276 used because it uses a different group for Diffie\(enHellman key
1277 exchange.
1278 .SP
1279 .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
1280 A system error occurred while opening or reading the keyring file.
1281 .SP
1282 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
1283 The key specifies the use of an unknown bulk-crypto transform
1284 .IR bulk .
1285 Maybe the key was generated wrongly, or maybe the version of Catacomb
1286 installed is too old.
1287 .SP
1288 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
1289 The key specifies the use of an unknown symmetric encryption algorithm
1290 .IR cipher .
1291 Maybe the key was generated wrongly, or maybe the version of
1292 Catacomb installed is too old.
1293 .SP
1294 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type
1295 The key specifies the use of a Diffie\(enHellman group of an unknown
1296 .IR type .
1297 Maybe the key was generated wrongly, or maybe the version of
1298 .BR tripe (8)
1299 is too old.
1300 .SP
1301 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash
1302 The key specifies the use of an unknown hash function
1303 .IR hash .
1304 Maybe the key was generated wrongly, or maybe the version of Catacomb
1305 installed is too old.
1306 .SP
1307 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac
1308 The key specifies the use of an unknown message authentication code
1309 .IR mac .
1310 Maybe the key was generated wrongly, or maybe the version of Catacomb
1311 installed is too old.
1312 .SP
1313 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf
1314 The key specifies the use of an unknown symmetric encryption function
1315 .I mgf
1316 for mask generation.  Maybe the key was generated wrongly, or maybe the
1317 version of Catacomb installed is too old.
1318 .SP
1319 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser
1320 The key specifies the use of an unknown serialization format
1321 .I ser
1322 for hashing group elements.  Maybe the key was generated wrongly, or
1323 maybe the version of Catacomb installed is too old.
1324 .SP
1325 .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
1326 No message authentication code was given explicitly, and there's no
1327 implementation of HMAC for the selected hash function
1328 .IR hash .
1329 .SP
1330 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
1331 The
1332 .I alg
1333 token is either
1334 .B cipher
1335 or
1336 .BR mac .
1337 The named algorithm requires more key material than the hash function
1338 can provide.  You must change either the hash function, or the cipher or
1339 MAC.
1340 .SP
1341 .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule"
1342 The cipher selected for mask-generation is unsuitable because it can't
1343 accept arbitrary-sized keys.
1344 .SP
1345 .BI "KEYMGMT " which "-keyring " file " key-not-found " tag
1346 A key named
1347 .I tag
1348 couldn't be found in the keyring.
1349 .SP
1350 .BI "KEYMGMT " which "-keyring " file " line " line " " message
1351 The contents of the keyring file are invalid.  There may well be a bug
1352 in the
1353 .BR key (1)
1354 program.
1355 .SS "KX warnings"
1356 These indicate problems during key-exchange.  Many indicate either a bug
1357 in the server (either yours or the remote one), or some kind of attack
1358 in progress.  All name a
1359 .I peer
1360 as the second token: this is the peer the packet is apparently from,
1361 though it may have been sent by an attacker instead.
1362 .PP
1363 In the descriptions below,
1364 .I msgtoken
1365 is one of the tokens
1366 .BR pre-challenge ,
1367 .BR cookie ,
1368 .BR challenge ,
1369 .BR reply ,
1370 .BR switch-rq ,
1371 or
1372 .BR switch-ok .
1373 .SP
1374 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
1375 The algorithms specified in the peer's public key
1376 .I pubtag
1377 don't match the ones described in the private key
1378 .IR privtag .
1379 .SP
1380 .BI "KX " peer " bad-expected-reply-log"
1381 The challenges
1382 .B tripe
1383 uses in its protocol contain a check value which proves that the
1384 challenge is honest.  This message indicates that the check value
1385 supplied is wrong: someone is attempting to use bogus challenges to
1386 persuade your
1387 .B tripe
1388 server to leak private key information.  No chance!
1389 .SP
1390 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
1391 A symmetrically-encrypted portion of a key-exchange message failed to
1392 decrypt.
1393 .SP
1394 .BI "KX " peer " invalid " msgtoken
1395 A key-exchange message was malformed.  This almost certainly indicates a
1396 bug somewhere.
1397 .SP
1398 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
1399 A message didn't contain the right magic data.  This may be a replay of
1400 some old exchange, or random packets being sent in an attempt to waste
1401 CPU.
1402 .SP
1403 .BI "KX " peer " " which "-key-expired"
1404 The local private key or the peer's public key (distinguished by
1405 .IR which )
1406 has expired.  Either you or the peer's maintainer should have arranged
1407 for a replacement before now.
1408 .SP
1409 .BI "KX " peer " sending-cookie"
1410 We've received too many bogus pre-challenge messages.  Someone is trying
1411 to flood us with key-exchange messages and make us waste CPU on doing
1412 hard asymmetric crypto sums.
1413 .SP
1414 .BI "KX " peer " unexpected " msgtoken
1415 The message received wasn't appropriate for this stage of the key
1416 exchange process.  This may mean that one of our previous packets got
1417 lost.  For
1418 .BR pre-challenge ,
1419 it may simply mean that the peer has recently restarted.
1420 .SP
1421 .BI "KX " peer " unknown-challenge"
1422 The peer is asking for an answer to a challenge which we don't know
1423 about.  This may mean that we've been inundated with challenges from
1424 some malicious source
1425 .I who can read our messages
1426 and discarded the valid one.
1427 .SP
1428 .BI "KX " peer " unknown-message 0x" nn
1429 An unknown key-exchange message arrived.
1430 .SS "PEER warnings"
1431 These are largely concerned with management of peers and the low-level
1432 details of the network protocol.  The second token is usually the name of
1433 a peer, or
1434 .RB ` \- '
1435 if none is relevant.
1436 .SP
1437 .BI "PEER " peer " bad-packet no-type"
1438 An empty packet arrived.  This is very strange.
1439 .SP
1440 .BI "PEER " peer " bad-packet unknown-category 0x" nn
1441 The message category
1442 .I nn
1443 (in hex) isn't understood.  Probably a strange random packet from
1444 somewhere; could be an unlikely bug.
1445 .SP
1446 .BI "PEER " peer " bad-packet unknown-type 0x" nn
1447 The message type
1448 .I nn
1449 (in hex) isn't understood.  Probably a strange random packet from
1450 somewhere; could be an unlikely bug.
1451 .SP
1452 .BI "PEER " peer " corrupt-encrypted-ping"
1453 The peer sent a ping response which matches an outstanding ping, but its
1454 payload is wrong.  There's definitely a bug somewhere.
1455 .SP
1456 .BI "PEER " peer " corrupt-transport-ping"
1457 The peer (apparently) sent a ping response which matches an outstanding
1458 ping, but its payload is wrong.  Either there's a bug, or the bad guys
1459 are playing tricks on you.
1460 .SP
1461 .BI "PEER " peer " decrypt-failed"
1462 An encrypted IP packet failed to decrypt.  It may have been mangled in
1463 transit, or may be a very old packet from an expired previous session
1464 key.  There is usually a considerable overlap in the validity periods of
1465 successive session keys, so this shouldn't occur unless the key exchange
1466 takes ages or fails.
1467 .SP
1468 .BI "PEER " peer " malformed-encrypted-ping"
1469 The peer sent a ping response which is hopelessly invalid.  There's
1470 definitely a bug somewhere.
1471 .SP
1472 .BI "PEER " peer " malformed-transport-ping"
1473 The peer (apparently) sent a ping response which is hopelessly invalid.
1474 Either there's a bug, or the bad guys are playing tricks on you.
1475 .SP
1476 .BI "PEER " peer " packet-build-failed"
1477 There wasn't enough space in our buffer to put the packet we wanted to
1478 send.  Shouldn't happen.
1479 .SP
1480 .BI "PEER \- socket-read-error " ecode " " message
1481 An error occurred trying to read an incoming packet.
1482 .SP
1483 .BI "PEER " peer " socket-write-error " ecode " " message
1484 An error occurred attempting to send a network packet.  We lost that
1485 one.
1486 .SP
1487 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
1488 The peer sent an encrypted ping response whose id doesn't match any
1489 outstanding ping.  Maybe it was delayed for longer than the server was
1490 willing to wait, or maybe the peer has gone mad.
1491 .SP
1492 .BI "PEER \- unexpected-source " address\fR...
1493 A packet arrived from
1494 .I address
1495 (a network address \(en see above), but no peer is known at that
1496 address.  This may indicate a misconfiguration, or simply be a result of
1497 one end of a connection being set up before the other.
1498 .SP
1499 .BI "PEER " peer " unexpected-transport-ping 0x" id
1500 The peer (apparently) sent a transport ping response whose id doesn't
1501 match any outstanding ping.  Maybe it was delayed for longer than the
1502 server was willing to wait, or maybe the peer has gone mad; or maybe
1503 there are bad people trying to confuse you.
1504 .SS "SERVER warnings"
1505 These indicate problems concerning the server process as a whole.
1506 .SP
1507 .BI "SERVER ignore signal " name
1508 A signal arrived, but the server ignored it.  Currently this happens for
1509 .B SIGHUP
1510 because that's a popular way of telling daemons to re-read their
1511 configuration files.  Since
1512 .B tripe
1513 re-reads its keyrings automatically and has no other configuration
1514 files, it's not relevant, but it seemed better to ignore the signal than
1515 let the server die.
1516 .SP
1517 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1518 A signal arrived and
1519 .B tripe
1520 is going to quit.
1521 .SP
1522 .BI "SERVER quit admin-request"
1523 A client of the administration interface issued a
1524 .B QUIT
1525 command.
1526 .SP
1527 .BI "SERVER quit foreground-eof"
1528 The server is running in foreground mode (the
1529 .B \-F
1530 option), and encountered end-of-file on standard input.
1531 .SP
1532 .BI "SERVER select-error " ecode " " message
1533 An error occurred in the server's main event loop.  This is bad: if it
1534 happens too many times, the server will abort.
1535 .SS "SYMM warnings"
1536 These are concerned with the symmetric encryption and decryption
1537 process.
1538 .SP
1539 .BI "SYMM replay old-sequence"
1540 A packet was received with an old sequence number.  It may just have
1541 been delayed or duplicated, or it may have been an attempt at a replay
1542 attack.
1543 .SP
1544 .BI "SYMM replay duplicated-sequence"
1545 A packet was received with a sequence number we've definitely seen
1546 before.  It may be an accidental duplication because the 'net is like
1547 that, or a deliberate attempt at a replay.
1548 .SS "TUN warnings"
1549 These concern the workings of the system-specific tunnel driver.  The
1550 second token is the name of the tunnel interface in question, or
1551 .RB ` \- '
1552 if none.
1553 .SP
1554 .BI "TUN \- bsd no-tunnel-devices"
1555 The driver couldn't find an available tunnel device.  Maybe if you
1556 create some more
1557 .BI /dev/tun nn
1558 files, it will work.
1559 .SP
1560 .BI "TUN \- " tun-name " open-error " device " " ecode " " message
1561 An attempt to open the tunnel device file
1562 .I device
1563 failed.
1564 .SP
1565 .BI "TUN \- linux config-error " ecode " " message
1566 Configuring the Linux TUN/TAP interface failed.
1567 .SP
1568 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1569 Reading from the tunnel device failed.
1570 .SP
1571 .BI "TUN " ifname " " tun-name " write-error " ecode " " message
1572 Writing from the tunnel device failed.
1573 .SP
1574 .BI "TUN " ifname " slip bad-escape"
1575 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1576 The erroneous packet will be ignored.
1577 .SP
1578 .BI "TUN " ifname " slip eof"
1579 The SLIP driver encountered end-of-file on its input descriptor.
1580 Pending data is discarded, and no attempt is made to read any more data
1581 from that interface ever.
1582 .SP
1583 .BI "TUN " ifname " slip escape-end"
1584 The SLIP driver encountered an escaped `end' marker.  This probably
1585 means that someone's been sending it junk.  The erroneous packet is
1586 discarded, and we hope that we've rediscovered synchronization.
1587 .SP
1588 .BI "TUN \- slip fork-error " ecode " " message
1589 The SLIP driver encountered an error forking a child process while
1590 allocating a new dynamic interface.
1591 .SP
1592 .BI "TUN \- slip no-slip-interfaces"
1593 The driver ran out of static SLIP interfaces.  Either preallocate more,
1594 or use dynamic SLIP interface allocation.
1595 .SP
1596 .BI "TUN " ifname " slip overflow"
1597 The SLIP driver gave up reading a packet because it got too large.
1598 .SP
1599 .BI "TUN \- slip pipe-error " ecode " " message
1600 The SLIP driver encountered an error creating pipes while allocating a
1601 new dynamic interface.
1602 .SP
1603 .BI "TUN \- slip read-ifname-failed " ecode " " message
1604 The SLIP driver encountered an error reading the name of a dynamically
1605 allocated interface.  Maybe the allocation script is broken.
1606 .SP
1607 .BI "TUN \- unet config-error " ecode " " message
1608 Configuring the Linux Unet interface failed.  Unet is obsolete and
1609 shouldn't be used any more.
1610 .SP
1611 .BI "TUN \- unet getinfo-error " ecode " " message
1612 Reading information about the Unet interface failed.  Unet is obsolete
1613 and shouldn't be used any more.
1614 .SS "USER warnings"
1615 These are issued by administration clients using the
1616 .B WARN
1617 command.
1618 .SP
1619 .BI "USER " tokens\fR...
1620 An administration client issued a warning.
1621 .\"-sep
1622 .
1623 .\"--------------------------------------------------------------------------
1624 .SH "SUMMARY"
1625 .
1626 .SS "Command responses"
1627 .nf
1628 .BI "BGDETACH " tag
1629 .BI "BGFAIL " tag " " tokens \fR...
1630 .BI "BGINFO " tag " " tokens \fR...
1631 .BI "BGOK " tag
1632 .BI "FAIL " tokens \fR...
1633 .BI "INFO " tokens \fR...
1634 .B OK
1635 .fi
1636 .\"= summary
1637 .
1638 .\"--------------------------------------------------------------------------
1639 .SH "SEE ALSO"
1640 .
1641 .BR tripectl (1),
1642 .BR tripe (8).
1643 .PP
1644 .IR "The Trivial IP Encryption Protocol" .
1645 .
1646 .\"--------------------------------------------------------------------------
1647 .SH "AUTHOR"
1648 .
1649 Mark Wooding, <mdw@distorted.org.uk>
1650 .
1651 .\"----- That's all, folks --------------------------------------------------