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