chiark / gitweb /
826d0f44704d4ed241e7e72b3c5a730ba0b2ea2d
[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 5 "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 "\-tunnel " tunnel
352 Use the named tunnel driver, rather than the default.
353 .\"-opts
354 .RE
355 .SP
356 .BI "ADDR " peer
357 Emits an
358 .B INFO
359 line reporting the IP address and port number stored for
360 .IR peer .
361 .SP
362 .B "ALGS"
363 Emits information about the cryptographic algorithms in use, in
364 key-value form.  The keys are as follows.
365 .RS
366 .TP
367 .B kx-group
368 Type of key-exchange group in use, currently either
369 .B ec
370 or
371 .BR prime .
372 .TP
373 .B kx-group-order-bits
374 Length of the group order, in bits.  This gives an approximate measure
375 of the group strength.
376 .TP
377 .B kx-group-elt-bits
378 Length of a group element, in bits.  This may be useful when analyzing
379 protocol traces.
380 .TP
381 .B hash
382 The hash function in use, e.g.,
383 .BR sha256 .
384 .TP
385 .B mgf
386 The mask-generating function in use, e.g.,
387 .BR whirlpool-mgf .
388 .TP
389 .B hashsz
390 The size of the hash function's output, in octets.
391 .TP
392 .B cipher
393 The name of the bulk data cipher in use, e.g.,
394 .BR blowfish-cbc .
395 .TP
396 .B cipher-keysz
397 The length of key used by the bulk data cipher, in octets.
398 .TP
399 .B cipher-blksz
400 The block size of the bulk data cipher, or zero if it's not based on a
401 block cipher.
402 .TP
403 .B cipher-data-limit
404 The maximum amount of data to be encrypted using a single key.  (A new
405 key exchange is instigated well before the limit is reached, in order to
406 allow for a seamless changeover of keys.)
407 .TP
408 .B mac
409 The message authentication algorithm in use, e.g.,
410 .BR ripemd160-hmac ..
411 .TP
412 .B mac-keysz
413 The length of the key used by the message authentication algorithm, in
414 octets.
415 .TP
416 .B mac-tagsz
417 The length of the message authentication tag, in octets.
418 .PP
419 The various sizes are useful, for example, when computing the MTU for a
420 tunnel interface.  If
421 .I MTU
422 is the MTU of the path to the peer, then the tunnel MTU should be
423 .IP
424 .I MTU
425 \- 33 \-
426 .I cipher-blksz
427 \-
428 .I mac-tagsz
429 .PP
430 allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
431 octet, a four-octet sequence number, an IV, and a MAC tag.
432 .RE
433 .SP
434 .BI "BGCANCEL " tag
435 Cancels the background job with the named
436 .IR tag .
437 .SP
438 .BI "CHECKCHAL " challenge
439 Verifies a challenge as being one earlier issued by
440 .B GETCHAL
441 and not previously either passed to
442 .B CHECKCHAL
443 or in a greeting message.
444 .SP
445 .B "DAEMON"
446 Causes the server to disassociate itself from its terminal and become a
447 background task.  This only works once.  A warning is issued.
448 .SP
449 .BI "EPING \fR[" options "\fR] " peer
450 Sends an encrypted ping to the peer, and expects an encrypted response.
451 This checks that the peer is running (and not being impersonated), and
452 that it can encrypt and decrypt packets correctly.  Options and
453 responses are the same as for the
454 .B PING
455 command.
456 .SP
457 .BI "FORCEKX " peer
458 Requests the server to begin a new key exchange with
459 .I peer
460 immediately.
461 .SP
462 .B "GETCHAL"
463 Requests a challenge.  The challenge is returned in an
464 .B INFO
465 line, as a base64-encoded string.  See
466 .BR CHECKCHAL .
467 .SP
468 .BI "GREET " peer " " challenge
469 Sends a greeting packet containing the
470 .I challenge
471 (base-64 encoded) to the named
472 .IR peer .
473 The expectation is that this will cause the peer to recognize us and
474 begin a key-exchange.
475 .SP
476 .B "HELP"
477 Causes the server to emit an
478 .B INFO
479 line for each command it supports.  Each line lists the command name,
480 followed by the names of the arguments.  This may be helpful as a memory
481 aid for interactive use, or for program clients probing for features.
482 .SP
483 .BI "IFNAME " peer
484 Emits an
485 .B INFO
486 line containing the name of the network interface used to collect IP
487 packets which are to be encrypted and sent to
488 .IR peer .
489 Used by configuration scripts so that they can set up routing tables
490 appropriately after adding new peers.
491 .SP
492 .B "JOBS"
493 Emits an
494 .B INFO
495 line giving the tag for each outstanding background job.
496 .SP
497 .BI "KILL " peer
498 Causes the server to forget all about
499 .IR peer .
500 All keys are destroyed, and no more packets are sent.  No notification
501 is sent to the peer: if it's important that the peer be notified, you
502 must think of a way to do that yourself.
503 .SP
504 .B "LIST"
505 For each currently-known peer, an
506 .B INFO
507 line is written containing the peer's name, as given to
508 .BR ADD .
509 .SP
510 .BI "NOTIFY " tokens\fR...
511 Issues a
512 .B USER
513 notification to all interested administration clients.
514 .SP
515 .BI "PEERINFO " peer
516 Returns information about a peer, in key-value form.  The following keys
517 are returned.
518 .RS
519 .TP
520 .B tunnel
521 The tunnel driver used for this peer.
522 .TP
523 .B keepalive
524 The keepalive interval, in seconds, or zero if no keepalives are to be
525 sent.
526 .RE
527 .SP
528 .BI "PING \fR[" options "\fR] " peer
529 Send a transport-level ping to the peer.  The ping and its response are
530 not encrypted or authenticated.  This command, possibly in conjunction
531 with tracing, is useful for ensuring that UDP packets are actually
532 flowing in both directions.  See also the
533 .B EPING
534 command.
535 .IP
536 An
537 .B INFO
538 line is printed describing the outcome:
539 .RS
540 .TP
541 .BI "ping-ok " millis
542 A response was received
543 .I millis
544 after the ping was sent.
545 .TP
546 .BI "ping-timeout"
547 No response was received within the time allowed.
548 .TP
549 .BI "ping-peer-died"
550 The peer was killed (probably by another admin connection) before a
551 response was received.
552 .RE
553 .IP
554 Options recognized for this command are:
555 .RS
556 .\"+opts
557 .TP
558 .BI "\-background " tag
559 Run the command in the background, using the given
560 .IR tag .
561 .TP
562 .BI "\-timeout " time
563 Wait for
564 .I time
565 seconds before giving up on a response.  The default is 5 seconds.  The
566 .I time
567 is expressed as a nonnegative integer followed optionally by
568 .BR d ,
569 .BR h ,
570 .BR m ,
571 or
572 .BR s
573 for days, hours, minutes, or seconds respectively; if no suffix is
574 given, seconds are assumed.
575 .\"-opts
576 .RE
577 .SP
578 .B "PORT"
579 Emits an
580 .B INFO
581 line containing just the number of the UDP port used by the
582 .B tripe
583 server.  If you've allowed your server to allocate a port dynamically,
584 this is how to find out which one it chose.
585 .SP
586 .B "RELOAD"
587 Instructs the server to recheck its keyring files.  The server checks
588 these periodically anyway but it may be necessary to force a recheck,
589 for example after adding a new peer key.
590 .SP
591 .B "QUIT"
592 Instructs the server to exit immediately.  A warning is sent.
593 .SP
594 .B "SERVINFO"
595 Returns information about the server, in the form of key-value pairs.
596 The following keys are used.
597 .RS
598 .TP
599 .B implementation
600 A keyword naming the implementation of the
601 .BR tripe (8)
602 server.  The current implementation is called
603 .BR edgeware-tripe .
604 .TP
605 .B version
606 The server's version number, as reported by
607 .BR VERSION .
608 .TP
609 .B daemon
610 Either
611 .B t
612 or
613 .BR nil ,
614 if the server has or hasn't (respectively) become a daemon.
615 .RE
616 .SP
617 .BI "SETIFNAME " peer " " new-name
618 Informs the server that the
619 .IR peer 's
620 tunnel-interface name has been changed to
621 .IR new-name .
622 This is useful if firewalling decisions are made based on interface
623 names: a setup script for a particular peer can change the name, and
624 then update the server's records so that they're accurate.
625 .SP
626 .BI "SVCCLAIM " service " " version
627 Attempts to claim the named
628 .IR service ,
629 offering the given
630 .IR version .
631 The claim is successful if the service is currently unclaimed, or if
632 a version earlier than
633 .I version
634 is provided; otherwise the command fails with the error
635 .BR "service-exists" .
636 .SP
637 .BI "SVCENSURE " service " \fR[" version \fR]
638 Ensure that
639 .I service
640 is provided, and (if specified) to at least the given
641 .IR version .
642 An error is reported if these conditions are not met; otherwise the
643 command succeeds silently.
644 .SP
645 .BI "SVCFAIL " jobid " " tokens \fR...
646 Send a
647 .B FAIL
648 (or
649 .BR BGFAIL )
650 response to the service job with the given
651 .IR jobid ,
652 passing the
653 .I tokens
654 as the reason for failure.  The job is closed.
655 .SP
656 .BI "SVCINFO " jobid " " tokens \fR...
657 Send an
658 .B INFO
659 (or
660 .BR BGINFO )
661 response to the service job with the given
662 .IR jobid ,
663 passing the
664 .I tokens
665 as the info message.  The job remains open.
666 .SP
667 .B "SVCLIST"
668 Output a line of the form
669 .RS
670 .IP
671 .B INFO
672 .I service
673 .I version
674 .PP
675 for each service currently provided.
676 .RE
677 .SP
678 .BI "SVCOK " jobid
679 Send an
680 .B OK
681 (or
682 .BR BGINFO )
683 response to the service job with the given
684 .IR jobid .
685 The job is closed.
686 .SP
687 .BI "SVCQUERY " service
688 Emits a number of
689 .B info
690 lines in key-value format, describing the named
691 .IR service.
692 The following keys are used.
693 .RS
694 .TP
695 .B name
696 The service's name.
697 .TP
698 .B version
699 The service's version string.
700 .RE
701 .SP
702 .BI "SVCRELEASE " service
703 Announce that the client no longer wishes to provide the named
704 .IR service .
705 .SP
706 .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
707 Submit a job to the provider of the given
708 .IR service ,
709 passing it the named
710 .I command
711 and the given
712 .IR arguments .
713 The following options are accepted.
714 .RS
715 .\"+opts
716 .TP
717 .BI "\-background " tag
718 Run the command in the background, using the given
719 .IR tag .
720 .TP
721 .BI "\-version " version
722 Ensure that at least the given
723 .I version
724 of the service is available before submitting the job.
725 .RE
726 .\"-opts
727 .SP
728 .BI "STATS " peer
729 Emits a number of
730 .B INFO
731 lines, each containing one or more statistics in the form
732 .IB name = value \fR.
733 The statistics-gathering is experimental and subject to change.
734 .SP
735 .BR "TRACE " [\fIoptions\fP]
736 Selects trace outputs: see
737 .B "Trace lists"
738 above.  Message types provided are:
739 .RS
740 .PP
741 Currently, the following tracing options are supported:
742 .TP
743 .B t
744 Tunnel events: reception of packets to be encrypted, and injection of
745 successfully-decrypted packets.
746 .TP
747 .B r
748 Peer management events: creation and destruction of peer attachments,
749 and arrival of messages.
750 .TP
751 .B a
752 Administration interface: acceptance of new connections, and handling of
753 the backgroud name-resolution required by the
754 .B ADD
755 command.
756 .TP
757 .B s
758 Handling of symmetric keysets: creation and expiry of keysets, and
759 encryption and decryption of messages.
760 .TP
761 .B x
762 Key exchange: reception, parsing and emission of key exchange messages.
763 .TP
764 .B m
765 Key management: loading keys and checking for file modifications.
766 .TP
767 .B l
768 Display information about challenge issuing and verification.
769 .TP
770 .B p
771 Display contents of packets sent and received by the tunnel and/or peer
772 modules.
773 .TP
774 .B c
775 Display inputs, outputs and intermediate results of cryptographic
776 operations.  This includes plaintext and key material.  Use with
777 caution.
778 .TP
779 .B A
780 All of the above.
781 .PP
782 Note that the
783 .B p
784 (packet contents)
785 and
786 .B c
787 (crypto details)
788 outputs provide extra detail for other outputs.  Specifying
789 .B p
790 without
791 .BR r
792 or
793 .B t
794 isn't useful; neither is specifying
795 .B c
796 without one of
797 .BR s ,
798 .BR l ,
799 .B x
800 or
801 .BR m .
802 .RE
803 .SP
804 .B "TUNNELS"
805 For each available tunnel driver, an
806 .B INFO
807 line is printed giving its name.
808 .SP
809 .B "VERSION"
810 Causes the server to emit an
811 .B INFO
812 line stating its software version, as two tokens: the server name, and
813 its version string.  The server name
814 .B tripe
815 is reserved to the Straylight/Edgeware implementation.
816 .SP
817 .BR "WATCH " [\fIoptions\fP]
818 Enables or disables asynchronous broadcasts
819 .IR "for the current connection only" .
820 See
821 .B "Trace lists"
822 above.  The default watch state for the connection the server opens
823 automatically on stdin/stdout is to show warnings and trace messages;
824 other connections show no asynchronous broadcast messages.  (This is
825 done in order to guarantee that a program reading the server's stdout
826 does not miss any warnings.)
827 .RS
828 .PP
829 Message types provided are:
830 .TP
831 .B t
832 .B TRACE
833 messages.
834 .TP
835 .B n
836 .B NOTE
837 messages.
838 .TP
839 .B w
840 .B WARN
841 messages.
842 .TP
843 .B A
844 All of the above.
845 .RE
846 .SP
847 .BI "WARN " tokens\fR...
848 Issues a
849 .B USER
850 warning to all interested administration clients.
851 .
852 .\"--------------------------------------------------------------------------
853 .SH "ERROR MESSAGES"
854 .
855 .\"* 20 Error messages (FAIL codes)
856 The following
857 .B FAIL
858 (or
859 .BR BGFAIL )
860 messages are sent to clients as a result of errors during command
861 processing.
862 .SP
863 .BI "already-daemon"
864 (For
865 .BR DAEMON .)
866 The
867 .B tripe
868 server is already running as a daemon.
869 .SP
870 .BI "bad-addr-syntax " message
871 (For commands accepting socket addresses.)  The address couldn't be
872 understood.
873 .SP
874 .BI "bad-syntax " cmd " " message
875 (For any command.)  The command couldn't be understood: e.g., the number
876 of arguments was wrong.
877 .SP
878 .BI "bad-time-spec " token
879 The
880 .I token
881 is not a valid time interval specification.  Acceptable time
882 specifications are nonnegative integers followed optionally by
883 .BR d ,
884 .BR h ,
885 .BR m ,
886 or
887 .BR s ,
888 for days, hours, minutes, or seconds, respectively.
889 .SP
890 .BI "bad-trace-option " char
891 (For
892 .BR TRACE .)
893 An unknown trace option was requested.
894 .SP
895 .BI "bad-watch-option " char
896 (For
897 .BR WATCH .)
898 An unknown watch option was requested.
899 .SP
900 .BI "daemon-error " ecode " " message
901 (For
902 .BR DAEMON .)
903 An error occurred during the attempt to become a daemon, as reported by
904 .IR message .
905 .SP
906 .BI "invalid-port " number
907 (For
908 .BR ADD .)
909 The given port number is out of range.
910 .SP
911 .BI "not-service-provider " service
912 (For
913 .BR SVCRELEASE .)
914 The invoking client is not the current provider of the named
915 .IR service ,
916 and is therefore not allowed to release it.
917 .SP
918 .BI "peer-create-fail " peer
919 (For
920 .BR ADD .)
921 Adding
922 .I peer
923 failed for some reason.  A warning should have been emitted explaining
924 why.
925 .SP
926 .BI "peer-addr-exists " address\fR...
927 (For
928 .BR ADD .)
929 There is already a peer with the given
930 .IR address .
931 .SP
932 .BI "peer-exists " peer
933 (For
934 .BR ADD .)
935 There is already a peer named
936 .IR peer .
937 .SP
938 .B "ping-send-failed"
939 The attempt to send a ping packet failed, probably due to lack of
940 encryption keys.
941 .SP
942 .BI "resolve-error " hostname
943 (For
944 .BR ADD .)
945 The DNS name
946 .I hostname
947 could not be resolved.
948 .SP
949 .BI "resolver-timeout " hostname
950 (For
951 .BR ADD .)
952 The DNS name
953 .I hostname
954 took too long to resolve.
955 .SP
956 .BI "service-exists " service " " version
957 (For
958 .BR SVCCLAIM .)
959 Another client is already providing the stated
960 .I version
961 of the
962 .IR service .
963 .SP
964 .BI "service-too-old " service " " version
965 (For
966 .B SVCENSURE
967 and
968 .BR SVCSUBMIT .)
969 Only the given
970 .I version
971 of the requested
972 .I service
973 is available, which does not meet the stated requirements.
974 .SP
975 .BI "tag-exists " tag
976 (For long-running commands.)  The named
977 .I tag
978 is already the tag of an outstanding job.
979 .SP
980 .BI "unknown-command " token
981 The command
982 .I token
983 was not recognized.
984 .SP
985 .BI "unknown-jobid " jobid
986 (For
987 .BR SVCOK ,
988 .BR SVCFAIL ,
989 and
990 .BR SVCINFO .)
991 The token
992 .I jobid
993 is not recognized as identifying an outstanding job.  It may have just
994 been cancelled.
995 .SP
996 .BI "unknown-peer " name
997 (For
998 .BR ADDR ,
999 .BR IFNAME ,
1000 .BR KILL ,
1001 .BR SETIFNAME ,
1002 and
1003 .BR STATS .)
1004 There is no peer called
1005 .IR name .
1006 .SP
1007 .BI "unknown-port " port
1008 (For
1009 .BR ADD .)
1010 The port name
1011 .I port
1012 couldn't be found in
1013 .BR /etc/services .
1014 .TP
1015 .BI "unknown-service " service
1016 (For
1017 .BR SVCENSURE ,
1018 .BR SVCQUERY ,
1019 .BR SVCRELEASE ,
1020 and
1021 .BR SVCSUBMIT .)
1022 The token
1023 .I service
1024 is not recognized as the name of a client-provided service.
1025 .TP
1026 .BI "unknown-tag " tag
1027 (For
1028 .BR BGCANCEL .)
1029 The given
1030 .I tag
1031 is not the tag for any outstanding background job.  It may have just
1032 finished.
1033 .
1034 .\"--------------------------------------------------------------------------
1035 .SH "NOTIFICATIONS"
1036 .
1037 .\"* 30 Notification broadcasts (NOTE codes)
1038 The following notifications are sent to clients who request them.
1039 .SP
1040 .BI "ADD " peer " " ifname " " address \fR...
1041 A new peer has been added.  The peer's name is
1042 .IR peer ,
1043 its tunnel is network interface
1044 .IR ifname ,
1045 and its network address is
1046 .IR address .
1047 .SP
1048 .BI "DAEMON"
1049 The server has forked off into the sunset and become a daemon.
1050 .SP
1051 .BI "GREET " challenge " " address \fR...
1052 A valid greeting was received, with the given challenge (exactly as it
1053 was returned by
1054 .B GETCHAL
1055 earlier).
1056 .SP
1057 .BI "KILL " peer
1058 The peer
1059 .I peer
1060 has been killed.
1061 .SP
1062 .BI "KXDONE " peer
1063 Key exchange with
1064 .I peer
1065 finished successfully.
1066 .SP
1067 .BI "KXSTART " peer
1068 Key exchange with
1069 .I peer
1070 has begun or restarted.  If key exchange keeps failing, this message
1071 will be repeated periodically.
1072 .SP
1073 .BI "NEWIFNAME " peer " " old-name " " new-name
1074 The given
1075 .IR peer 's
1076 tunnel interface name has been changed from
1077 .I old-name
1078 to
1079 .IR new-name ,
1080 as a result of a
1081 .B SETIFNAME
1082 command.
1083 .SP
1084 .BI "SVCCLAIM " service " " version
1085 The named
1086 .I service
1087 is now available, at the stated
1088 .IR version .
1089 .SP
1090 .BI "SVCRELEASE " service
1091 The named
1092 .I service
1093 is no longer available.
1094 .SP
1095 .BI "USER " tokens\fR...
1096 An administration client issued a notification using the
1097 .B NOTIFY
1098 command.
1099 .
1100 .\"--------------------------------------------------------------------------
1101 .SH "WARNINGS"
1102 .
1103 .\"* 40 Warning broadcasts (WARN codes)
1104 .\"+sep
1105 There are many possible warnings.  They are categorized according to
1106 their first tokens.
1107 .PP
1108 Many of these warnings report system errors.  These are reported as a
1109 pair of tokens, described below as
1110 .I ecode
1111 and
1112 .IR message .
1113 The
1114 .I ecode
1115 is a string of the form
1116 .BI E number
1117 giving the
1118 .BR errno (3)
1119 value of the error; the
1120 .I message
1121 is the `human-readable' form of the message, as reported by
1122 .BR strerror (3).
1123 .SS "ABORT warnings"
1124 These all indicate that the
1125 .B tripe
1126 server has become unable to continue.  If enabled, the server will dump
1127 core in its configuration directory.
1128 .SP
1129 .BI "ABORT repeated-select-errors"
1130 The main event loop is repeatedly failing.  If the server doesn't quit,
1131 it will probably waste all available CPU doing nothing.
1132 .SS "ADMIN warnings"
1133 These indicate a problem with the administration socket interface.
1134 .SP
1135 .BI "ADMIN accept-error " ecode " " message
1136 There was an error while attempting to accept a connection from a new
1137 client.
1138 .SP
1139 .BI "ADMIN client-write-error " ecode " " message
1140 There was an error sending data to a client.  The connection to the
1141 client has been closed.
1142 .SS "CHAL warnings"
1143 These indicate errors in challenges, either in the
1144 .B CHECKCHAL
1145 command or in greeting packets.
1146 .SP
1147 .B "CHAL impossible-challenge"
1148 The server hasn't issued any challenges yet.  Quite how anyone else
1149 thought he could make one up is hard to imagine.
1150 .SP
1151 .B "CHAL incorrect-tag"
1152 Challenge received contained the wrong authentication data.  It might be
1153 very stale, or a forgery.
1154 .SP
1155 .B "CHAL invalid-challenge"
1156 Challenge received was the wrong length.  We might have changed MAC
1157 algorithms since the challenge was issued, or it might just be rubbish.
1158 .SP
1159 .B "CHAL replay duplicated-sequence"
1160 Challenge received was a definite replay of an old challenge.  Someone's
1161 up to something!
1162 .SP
1163 .B "CHAL replay old-sequence"
1164 Challenge received was old, but maybe not actually a replay.  Try again.
1165 .SS "KEYMGMT warnings"
1166 These indicate a problem with the keyring files, or the keys stored in
1167 them.
1168 .SP
1169 .BI "KEYMGMT bad-private-key " message
1170 The private key could not be read, or failed a consistency check.  If
1171 there was a problem with the file, usually there will have been
1172 .B key-file-error
1173 warnings before this.
1174 .SP
1175 .BI "KEYMGMT bad-public-keyring " message
1176 The public keyring couldn't be read.  Usually, there will have been
1177 .B key-file-error
1178 warnings before this.
1179 .SP
1180 .BI "KEYMGMT key-file-error " file ":" line " " message
1181 Reports a specific error with the named keyring file.  This probably
1182 indicates a bug in
1183 .BR key (1).
1184 .SP
1185 .BI "KEYMGMT public-key " tag " " tokens\fR...
1186 These messages all indicate a problem with the public key named
1187 .IR tag .
1188 .SP
1189 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
1190 The algorithms specified on the public key don't match the ones for our
1191 private key.  All the peers in a network have to use the same
1192 algorithms.
1193 .SP
1194 .BI "KEYMGMT public-key " tag " bad " message
1195 The public key couldn't be read, or is invalid.
1196 .SP
1197 .BI "KEYMGMT public-key " tag " bad-public-group-element"
1198 The public key is invalid.  This may indicate a malicious attempt to
1199 introduce a bogus key.
1200 .SP
1201 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
1202 The algorithms listed on the public key couldn't be understood.  The
1203 algorithm selection attributes are probably malformed and need fixing.
1204 .SP
1205 .BI "KEYMGMT public-key " tag " incorrect-group"
1206 The public key doesn't use the same group as our private key.  All the
1207 peers in a network have to use the same group.
1208 .SP
1209 .BI "KEYMGMT public-key " tag " not-found"
1210 The public key for peer
1211 .I tag
1212 wasn't in the public keyring.
1213 .SP
1214 .BI "KEYMGMT public-key " tag " unknown-type"
1215 The type of the public key isn't understood.  Maybe you need to upgrade
1216 your copy of
1217 .BR tripe .
1218 (Even if you do, you'll have to regenerate your keys.)
1219 .SS "KX warnings"
1220 These indicate problems during key-exchange.  Many indicate either a bug
1221 in the server (either yours or the remote one), or some kind of attack
1222 in progress.  All name a
1223 .I peer
1224 as the second token: this is the peer the packet is apparently from,
1225 though it may have been sent by an attacker instead.
1226 .PP
1227 In the descriptions below,
1228 .I msgtoken
1229 is one of the tokens
1230 .BR pre-challenge ,
1231 .BR cookie ,
1232 .BR challenge ,
1233 .BR reply ,
1234 .BR switch-rq ,
1235 or
1236 .BR switch-ok .
1237 .SP
1238 .BI "KX " peer " bad-expected-reply-log"
1239 The challenges
1240 .B tripe
1241 uses in its protocol contain a check value which proves that the
1242 challenge is honest.  This message indicates that the check value
1243 supplied is wrong: someone is attempting to use bogus challenges to
1244 persuade your
1245 .B tripe
1246 server to leak private key information.  No chance!
1247 .SP
1248 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
1249 A symmetrically-encrypted portion of a key-exchange message failed to
1250 decrypt.
1251 .SP
1252 .BI "KX " peer " invalid " msgtoken
1253 A key-exchange message was malformed.  This almost certainly indicates a
1254 bug somewhere.
1255 .SP
1256 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
1257 A message didn't contain the right magic data.  This may be a replay of
1258 some old exchange, or random packets being sent in an attempt to waste
1259 CPU.
1260 .SP
1261 .BI "KX " peer " public-key-expired"
1262 The peer's public key has expired.  It's maintainer should have given
1263 you a replacement before now.
1264 .SP
1265 .BI "KX " peer " sending-cookie"
1266 We've received too many bogus pre-challenge messages.  Someone is trying
1267 to flood us with key-exchange messages and make us waste CPU on doing
1268 hard asymmetric crypto sums.
1269 .SP
1270 .BI "KX " peer " unexpected " msgtoken
1271 The message received wasn't appropriate for this stage of the key
1272 exchange process.  This may mean that one of our previous packets got
1273 lost.  For
1274 .BR pre-challenge ,
1275 it may simply mean that the peer has recently restarted.
1276 .SP
1277 .BI "KX " peer " unknown-challenge"
1278 The peer is asking for an answer to a challenge which we don't know
1279 about.  This may mean that we've been inundated with challenges from
1280 some malicious source
1281 .I who can read our messages
1282 and discarded the valid one.
1283 .SP
1284 .BI "KX " peer " unknown-message 0x" nn
1285 An unknown key-exchange message arrived.
1286 .SS "PEER warnings"
1287 These are largely concerned with management of peers and the low-level
1288 details of the network protocol.  The second token is usually the name of
1289 a peer, or
1290 .RB ` \- '
1291 if none is relevant.
1292 .SP
1293 .BI "PEER " peer " bad-packet no-type"
1294 An empty packet arrived.  This is very strange.
1295 .SP
1296 .BI "PEER " peer " bad-packet unknown-category 0x" nn
1297 The message category
1298 .I nn
1299 (in hex) isn't understood.  Probably a strange random packet from
1300 somewhere; could be an unlikely bug.
1301 .SP
1302 .BI "PEER " peer " bad-packet unknown-type 0x" nn
1303 The message type
1304 .I nn
1305 (in hex) isn't understood.  Probably a strange random packet from
1306 somewhere; could be an unlikely bug.
1307 .SP
1308 .BI "PEER " peer " corrupt-encrypted-ping"
1309 The peer sent a ping response which matches an outstanding ping, but its
1310 payload is wrong.  There's definitely a bug somewhere.
1311 .SP
1312 .BI "PEER " peer " corrupt-transport-ping"
1313 The peer (apparently) sent a ping response which matches an outstanding
1314 ping, but its payload is wrong.  Either there's a bug, or the bad guys
1315 are playing tricks on you.
1316 .SP
1317 .BI "PEER " peer " decrypt-failed"
1318 An encrypted IP packet failed to decrypt.  It may have been mangled in
1319 transit, or may be a very old packet from an expired previous session
1320 key.  There is usually a considerable overlap in the validity periods of
1321 successive session keys, so this shouldn't occur unless the key exchange
1322 takes ages or fails.
1323 .SP
1324 .BI "PEER " peer " malformed-encrypted-ping"
1325 The peer sent a ping response which is hopelessly invalid.  There's
1326 definitely a bug somewhere.
1327 .SP
1328 .BI "PEER " peer " malformed-transport-ping"
1329 The peer (apparently) sent a ping response which is hopelessly invalid.
1330 Either there's a bug, or the bad guys are playing tricks on you.
1331 .SP
1332 .BI "PEER " peer " packet-build-failed"
1333 There wasn't enough space in our buffer to put the packet we wanted to
1334 send.  Shouldn't happen.
1335 .SP
1336 .BI "PEER \- socket-read-error " ecode " " message
1337 An error occurred trying to read an incoming packet.
1338 .SP
1339 .BI "PEER " peer " socket-write-error " ecode " " message
1340 An error occurred attempting to send a network packet.  We lost that
1341 one.
1342 .SP
1343 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
1344 The peer sent an encrypted ping response whose id doesn't match any
1345 outstanding ping.  Maybe it was delayed for longer than the server was
1346 willing to wait, or maybe the peer has gone mad.
1347 .SP
1348 .BI "PEER \- unexpected-source " address\fR...
1349 A packet arrived from
1350 .I address
1351 (a network address \(en see above), but no peer is known at that
1352 address.  This may indicate a misconfiguration, or simply be a result of
1353 one end of a connection being set up before the other.
1354 .SP
1355 .BI "PEER " peer " unexpected-transport-ping 0x" id
1356 The peer (apparently) sent a transport ping response whose id doesn't
1357 match any outstanding ping.  Maybe it was delayed for longer than the
1358 server was willing to wait, or maybe the peer has gone mad; or maybe
1359 there are bad people trying to confuse you.
1360 .SS "SERVER warnings"
1361 These indicate problems concerning the server process as a whole.
1362 .SP
1363 .BI "SERVER ignore signal " name
1364 A signal arrived, but the server ignored it.  Currently this happens for
1365 .B SIGHUP
1366 because that's a popular way of telling daemons to re-read their
1367 configuration files.  Since
1368 .B tripe
1369 re-reads its keyrings automatically and has no other configuration
1370 files, it's not relevant, but it seemed better to ignore the signal than
1371 let the server die.
1372 .SP
1373 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1374 A signal arrived and
1375 .B tripe
1376 is going to quit.
1377 .SP
1378 .BI "SERVER quit admin-request"
1379 A client of the administration interface issued a
1380 .B QUIT
1381 command.
1382 .SP
1383 .BI "SERVER quit foreground-eof"
1384 The server is running in foreground mode (the
1385 .B \-F
1386 option), and encountered end-of-file on standard input.
1387 .SP
1388 .BI "SERVER select-error " ecode " " message
1389 An error occurred in the server's main event loop.  This is bad: if it
1390 happens too many times, the server will abort.
1391 .SS "SYMM warnings"
1392 These are concerned with the symmetric encryption and decryption
1393 process.
1394 .SP
1395 .BI "SYMM replay old-sequence"
1396 A packet was received with an old sequence number.  It may just have
1397 been delayed or duplicated, or it may have been an attempt at a replay
1398 attack.
1399 .SP
1400 .BI "SYMM replay duplicated-sequence"
1401 A packet was received with a sequence number we've definitely seen
1402 before.  It may be an accidental duplication because the 'net is like
1403 that, or a deliberate attempt at a replay.
1404 .SS "TUN warnings"
1405 These concern the workings of the system-specific tunnel driver.  The
1406 second token is the name of the tunnel interface in question, or
1407 .RB ` \- '
1408 if none.
1409 .SP
1410 .BI "TUN \- bsd no-tunnel-devices"
1411 The driver couldn't find an available tunnel device.  Maybe if you
1412 create some more
1413 .BI /dev/tun nn
1414 files, it will work.
1415 .SP
1416 .BI "TUN \- " tun-name " open-error " device " " ecode " " message
1417 An attempt to open the tunnel device file
1418 .I device
1419 failed.
1420 .SP
1421 .BI "TUN \- linux config-error " ecode " " message
1422 Configuring the Linux TUN/TAP interface failed.
1423 .SP
1424 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1425 Reading from the tunnel device failed.
1426 .SP
1427 .BI "TUN " ifname " slip bad-escape"
1428 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1429 The erroneous packet will be ignored.
1430 .SP
1431 .BI "TUN " ifname " slip eof"
1432 The SLIP driver encountered end-of-file on its input descriptor.
1433 Pending data is discarded, and no attempt is made to read any more data
1434 from that interface ever.
1435 .SP
1436 .BI "TUN " ifname " slip escape-end"
1437 The SLIP driver encountered an escaped `end' marker.  This probably
1438 means that someone's been sending it junk.  The erroneous packet is
1439 discarded, and we hope that we've rediscovered synchronization.
1440 .SP
1441 .BI "TUN \- slip fork-error " ecode " " message
1442 The SLIP driver encountered an error forking a child process while
1443 allocating a new dynamic interface.
1444 .SP
1445 .BI "TUN \- slip no-slip-interfaces"
1446 The driver ran out of static SLIP interfaces.  Either preallocate more,
1447 or use dynamic SLIP interface allocation.
1448 .SP
1449 .BI "TUN " ifname " slip overflow"
1450 The SLIP driver gave up reading a packet because it got too large.
1451 .SP
1452 .BI "TUN \- slip pipe-error " ecode " " message
1453 The SLIP driver encountered an error creating pipes while allocating a
1454 new dynamic interface.
1455 .SP
1456 .BI "TUN \- slip read-ifname-failed " ecode " " message
1457 The SLIP driver encountered an error reading the name of a dynamically
1458 allocated interface.  Maybe the allocation script is broken.
1459 .SP
1460 .BI "TUN \- unet config-error " ecode " " message
1461 Configuring the Linux Unet interface failed.  Unet is obsolete and
1462 shouldn't be used any more.
1463 .SP
1464 .BI "TUN \- unet getinfo-error " ecode " " message
1465 Reading information about the Unet interface failed.  Unet is obsolete
1466 and shouldn't be used any more.
1467 .SS "USER warnings"
1468 These are issued by administration clients using the
1469 .B WARN
1470 command.
1471 .SP
1472 .BI "USER " tokens\fR...
1473 An administration client issued a warning.
1474 .\"-sep
1475 .
1476 .\"--------------------------------------------------------------------------
1477 .SH "SUMMARY"
1478 .
1479 .SS "Command responses"
1480 .nf
1481 .BI "BGDETACH " tag
1482 .BI "BGFAIL " tag " " tokens \fR...
1483 .BI "BGINFO " tag " " tokens \fR...
1484 .BI "BGOK " tag
1485 .BI "FAIL " tokens \fR...
1486 .BI "INFO " tokens \fR...
1487 .B OK
1488 .fi
1489 .\"= summary
1490 .
1491 .\"--------------------------------------------------------------------------
1492 .SH "SEE ALSO"
1493 .
1494 .BR tripectl (1),
1495 .BR tripe (8).
1496 .PP
1497 .IR "The Trivial IP Encryption Protocol" .
1498 .
1499 .\"--------------------------------------------------------------------------
1500 .SH "AUTHOR"
1501 .
1502 Mark Wooding, <mdw@distorted.org.uk>
1503 .
1504 .\"----- That's all, folks --------------------------------------------------