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