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