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