2 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
4 tripe-admin \- administrator commands for TrIPE
6 This manual page describes the administration interface provided by the
12 program can be used either interactively or in scripts to communicate
13 with the server using this interface. Alternatively, simple custom
14 clients can be written in scripting languages such as Perl, Python or
15 Tcl, or more advanced clients such as GUI monitors can be written in C
16 with little difficulty.
18 By default, the server listens for admin connections on the Unix-domain
20 .BR /var/lib/tripe/tripesock .
21 Administration commands use a simple textual protocol. Each client
22 command or server response consists of a line of ASCII text terminated
23 by a single linefeed character. No command may be longer than 255
25 .SS "General structure"
26 Each command or response line consists of a sequence of
27 whitespace-separated words. The number and nature of whitespace
28 characters separating two words in a client command is not significant;
29 the server always uses a single space character. The first word in a
32 identifying the type of command or response contained. Keywords in
33 client commands are not case-sensitive; the server always uses uppercase
35 .SS "Server responses"
36 For client command, the server responds with zero or more
38 lines, followed by either an
44 provides information requested in the command. An
46 response contains no further data. A
48 code is followed by a machine-readable explanation of why the command
51 In addition, there are three types of asynchronous messages which
52 aren't associated with any particular command. The
54 message contains a machine-readable message warning of an error
55 encountered while processing a command, unexpected or unusual behaviour
56 by a peer, or a possible attack by an adversary. Under normal
57 conditions, the server shouldn't emit any warnings. The
59 message contains a human-readable tracing message containing diagnostic
60 information. Trace messages are controlled using the
62 command-line option to the server, or the
64 administration command (see below). Support for tracing can be disabled
65 when the package is being configured, and may not be available in your
68 message is a machine-readable notification about some routine but
69 interesting event such as creation or destruction of peers.
71 The presence of asynchronous messages can be controlled using the
74 .SS "Network addresses"
75 A network address is a sequence of words. The first is a token
76 identifying the network address family. The length of an address and
77 the meanings of the subsequent words depend on the address family.
78 Address family tokens are not case-sensitive on input; on output, they
79 are always in upper-case.
81 At present, only one address family is understood.
83 .BI "INET " address " " port
84 An Internet socket, naming an IPv4 address and UDP port. On output, the
85 address is always in numeric dotted-quad form, and the port is given as
86 a plain number. On input, DNS hostnames and symbolic port names are
87 permitted. Name resolution does not block the main server, but will
88 block the requesting client. This hopefully makes life simpler for
89 stupid clients. Complex clients which don't wish to be held up can open
90 extra connections or do the resolution themselves.)
92 If, on input, no recognised address family token is found, the following
93 words are assumed to represent an
96 .SH "COMMAND REFERENCE"
97 The commands provided are:
99 .BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
100 Adds a new peer. The peer is given the name
102 the peer's public key is assumed to be in the file
104 (or whatever alternative file was specified in the
106 option on the command line). The
108 is the network address (see above for the format) at which the peer can
109 be contacted. The following options are recognised.
112 .BI "\-keepalive " time
113 Send a no-op packet if we've not sent a packet to the peer in the last
115 interval. This is useful for persuading port-translating firewalls to
116 believe that the `connection' is still active. The
118 is expressed as a nonnegative integer followed optionally by
124 for days, hours, minutes, or seconds respectively; if no suffix is
125 given, seconds are assumed.
127 .BI "\-tunnel " tunnel
128 Use the named tunnel driver, rather than the default.
134 line reporting the IP address and port number stored for
138 Causes the server to disassociate itself from its terminal and become a
139 background task. This only works once. A warning is issued.
141 .BI "EPING \fR[" options "\fR] " peer
142 Sends an encrypted ping to the peer, and expects an encrypted response.
143 This checks that the peer is running (and not being impersonated), and
144 that it can encrypt and decrypt packets correctly. Options and
145 responses are the same as for the
150 Causes the server to emit an
152 line for each command it supports. Each line lists the command name,
153 followed by the names of the arguments. This may be helpful as a memory
154 aid for interactive use, or for program clients probing for features.
159 line containing the name of the network interface used to collect IP
160 packets which are to be encrypted and sent to
162 Used by configuration scripts so that they can set up routing tables
163 appropriately after adding new peers.
166 Causes the server to forget all about
168 All keys are destroyed, and no more packets are sent. No notification
169 is sent to the peer: if it's important that the peer be notified, you
170 must think of a way to do that yourself.
173 For each currently-known peer, an
175 line is written containing the peer's name, as given to
178 .BI "NOTIFY " tokens\fR...
181 notification to all interested administration clients.
183 .BI "PING \fR[" options "\fR] " peer
184 Send a transport-level ping to the peer. The ping and its response are
185 not encrypted or authenticated. This command, possibly in conjunction
186 with tracing, is useful for ensuring that UDP packets are actually
187 flowing in both directions. See also the
193 line is printed describing the outcome:
196 .BI "ping-ok " millis
197 A response was received
199 after the ping was sent.
202 No response was received within the time allowed.
205 The peer was killed (probably by another admin connection) before a
206 response was received.
209 Options recognized for this command are:
212 .BI "\-timeout " time
215 seconds before giving up on a response. The default is 5 seconds. (The
216 time format is the same as for the
224 line containing just the number of the UDP port used by the
226 server. If you've allowed your server to allocate a port dynamically,
227 this is how to find out which one it chose.
230 Instructs the server to exit immediately. A warning is sent.
235 lines, each containing one or more statistics in the form
236 .IB name = value \fR.
237 The statistics-gathering is experimental and subject to change.
239 .BR "TRACE " [\fIoptions\fP]
240 A trace argument consists of a string of letters (listed below)
241 selecting trace outputs, optionally interspersed with
245 to disable, the subsequently listed outputs; the initial behaviour is to
246 enable listed outputs. For example, the string
248 enables tracing of peer management, admin-connection handling and
249 key-exchange processing, and disables tracing of symmetric keyset
250 management and the system-specific tunnel driver. If no argument is
251 given, a table is returned showing the available tracing option letters
252 and their meanings. Programs should not attempt to parse this table:
253 its format is not guaranteed to remain the same.
256 Currently, the following tracing options are supported:
259 Tunnel events: reception of packets to be encrypted, and injection of
260 successfully-decrypted packets.
263 Peer management events: creation and destruction of peer attachments,
264 and arrival of messages.
267 Administration interface: acceptance of new connections, and handling of
268 the backgroud name-resolution required by the
273 Display contents of packets sent and received by the tunnel and/or peer
277 Display inputs, outputs and intermediate results of cryptographic
278 operations. This includes plaintext and key material. Use with
282 Handling of symmetric keysets: creation and expiry of keysets, and
283 encryption and decryption of messages.
286 Key exchange: reception, parsing and emission of key exchange messages.
289 Key management: loading keys and checking for file modifications.
297 outputs provide extra detail for other outputs. Specifying
303 isn't useful; neither is specifying
315 .BR "WATCH " [\fIoptions\fP]
316 Enables or disables asynchronous messages
317 .IR "for the current connection only" .
318 This command has no effect on other connections. A watch argument
319 consists of a string of letters (listed below) selecting message types,
320 optionally interspersed with
324 to disable, the subsequently listed types, similar to
326 above. The default watch state for the connection the server opens
327 automatically on stdin/stdout is to show warnings and trace messages;
328 other connections show no asynchronous messages. (This is done in order
329 to guarantee that a program reading the server's stdout does not miss
333 Currently, the following watch options are supported:
352 Causes the server to emit an
354 line stating its software version, as two words: the server name, and
355 its version string. The server name
357 is reserved to the Straylight/Edgeware implementation.
359 .BI "WARN " tokens\fR...
362 warning to all interested administration clients.
366 messages are sent to clients as a result of errors during command
374 server is already running as a daemon.
376 .BI "bad-syntax \-\- " message
377 (For any command.) The command couldn't be understood: e.g., the number
378 of arguments was wrong.
380 .BI "bad-time-spec " word
383 is not a valid time interval specification. Acceptable time
384 specifications are nonnegative integers followed optionally by
390 for days, hours, minutes, or seconds, respectively.
392 .BI "bad-trace-option " char
395 An unknown trace option was requested.
397 .BI "bad-watch-option " char
400 An unknown watch option was requested.
402 .BI "daemon-error \-\- " message
405 An error occurred during the attempt to become a daemon, as reported by
408 .BI "invalid-port " number
411 The given port number is out of range.
413 .BI "peer-create-fail " peer
418 failed for some reason. A warning should have been emitted explaining
421 .BI "peer-exists " peer
424 There is already a peer named
427 .B "ping-send-failed"
428 The attempt to send a ping packet failed, probably due to lack of
431 .BI "resolve-error " hostname
436 could not be resolved.
438 .BI "resolver-timeout " hostname
443 took too long to resolve.
445 .BI "unknown-command " token
450 .BI "unknown-peer " name
457 There is no peer called
460 .BI "unknown-service " service
468 The following notifications are sent to clients who request them.
470 .BI "ADD " peer " " ifname " " address \fR...
471 A new peer has been added. The peer's name is
473 its tunnel is network interface
475 and its network address is
479 The server has forked off into the sunset and become a daemon.
489 finished successfully.
494 has begun or restarted. If key exchange keeps failing, this message
495 will be repeated periodically.
497 .BI "USER " tokens\fR...
498 An administration client issued a notification using the
502 There are many possible warnings. They are categorized according to
505 These all indicate that the
507 server has become unable to continue. If enabled, the server will dump
508 core in its configuration directory.
510 .BI "ABORT repeated-select-errors"
511 The main event loop is repeatedly failing. If the server doesn't quit,
512 it will probably waste all available CPU doing nothing.
514 These indicate a problem with the administration socket interface.
516 .BI "ADMIN accept-error \-\- " message
517 There was an error while attempting to accept a connection from a new
520 .BI "ADMIN client-read-error \-\- " message
521 There was an error sending data to a client. The connection to the
522 client has been closed.
523 .SS "KEYMGMT warnings"
524 These indicate a problem with the keyring files, or the keys stored in
527 .BI "KEYMGMT bad-private-key \-\- " message
528 The private key could not be read, or failed a consistency check. If
529 there was a problem with the file, usually there will have been
531 warnings before this.
533 .BI "KEYMGMT bad-public-keyring \-\- " message
534 The public keyring couldn't be read. Usually, there will have been
536 warnings before this.
538 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
539 Reports a specific error with the named keyring file. This probably
543 .BI "KEYMGMT public-key " tag " " tokens\fR...
544 These messages all indicate a problem with the public key named
547 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
548 The algorithms specified on the public key don't match the ones for our
549 private key. All the peers in a network have to use the same
552 .BI "KEYMGMT public-key " tag " bad \-\- " message
553 The public key couldn't be read, or is invalid.
555 .BI "KEYMGMT public-key " tag " bad-public-group-element"
556 The public key is invalid. This may indicate a malicious attempt to
557 introduce a bogus key.
559 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
560 The algorithms listed on the public key couldn't be understood. The
561 algorithm selection attributes are probably malformed and need fixing.
563 .BI "KEYMGMT public-key " tag " incorrect-group"
564 The public key doesn't use the same group as our private key. All the
565 peers in a network have to use the same group.
567 .BI "KEYMGMT public-key " tag " not-found"
568 The public key for peer
570 wasn't in the public keyring.
572 .BI "KEYMGMT public-key " tag " unknown-type"
573 The type of the public key isn't understood. Maybe you need to upgrade
576 (Even if you do, you'll have to regenerate your keys.)
578 These indicate problems during key-exchange. Many indicate either a bug
579 in the server (either yours or the remote one), or some kind of attack
580 in progress. All name a
582 as the second token: this is the peer the packet is apparently from,
583 though it may have been sent by an attacker instead.
585 In the descriptions below,
596 .BI "KX " peer " bad-expected-reply-log"
599 uses in its protocol contain a check value which proves that the
600 challenge is honest. This message indicates that the check value
601 supplied is wrong: someone is attempting to use bogus challenges to
604 server to leak private key information. No chance!
606 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
607 A symmetrically-encrypted portion of a key-exchange message failed to
610 .BI "KX " peer " invalid " msgtoken
611 A key-exchange message was malformed. This almost certainly indicates a
614 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
615 A message didn't contain the right magic data. This may be a replay of
616 some old exchange, or random packets being sent in an attempt to waste
619 .BI "KX " peer " public-key-expired"
620 The peer's public key has expired. It's maintainer should have given
621 you a replacement before now.
623 .BI "KX " peer " sending-cookie"
624 We've received too many bogus pre-challenge messages. Someone is trying
625 to flood us with key-exchange messages and make us waste CPU on doing
626 hard asymmetric crypto sums.
628 .BI "KX " peer " unexpected " msgtoken
629 The message received wasn't appropriate for this stage of the key
630 exchange process. This may mean that one of our previous packets got
633 it may simply mean that the peer has recently restarted.
635 .BI "KX " peer " unknown-challenge"
636 The peer is asking for an answer to a challenge which we don't know
637 about. This may mean that we've been inundated with challenges from
638 some malicious source
639 .I who can read our messages
640 and discarded the valid one.
642 .BI "KX " peer " unknown-message 0x" nn
643 An unknown key-exchange message arrived.
645 These are largely concerned with management of peers and the low-level
646 details of the network protocol. The second word is usually the name of
651 .BI "PEER " peer " bad-packet no-type"
652 An empty packet arrived. This is very strange.
654 .BI "PEER " peer " bad-packet unknown-category 0x" nn
657 (in hex) isn't understood. Probably a strange random packet from
658 somewhere; could be an unlikely bug.
660 .BI "PEER " peer " bad-packet unknown-type 0x" nn
663 (in hex) isn't understood. Probably a strange random packet from
664 somewhere; could be an unlikely bug.
666 .BI "PEER " peer " corrupt-encrypted-ping"
667 The peer sent a ping response which matches an outstanding ping, but its
668 payload is wrong. There's definitely a bug somewhere.
670 .BI "PEER " peer " corrupt-transport-ping"
671 The peer (apparently) sent a ping response which matches an outstanding
672 ping, but its payload is wrong. Either there's a bug, or the bad guys
673 are playing tricks on you.
675 .BI "PEER " peer " decrypt-failed"
676 An encrypted IP packet failed to decrypt. It may have been mangled in
677 transit, or may be a very old packet from an expired previous session
678 key. There is usually a considerable overlap in the validity periods of
679 successive session keys, so this shouldn't occur unless the key exchange
682 .BI "PEER " peer " malformed-encrypted-ping"
683 The peer sent a ping response which is hopelessly invalid. There's
684 definitely a bug somewhere.
686 .BI "PEER " peer " malformed-transport-ping"
687 The peer (apparently) sent a ping response which is hopelessly invalid.
688 Either there's a bug, or the bad guys are playing tricks on you.
690 .BI "PEER " peer " packet-build-failed"
691 There wasn't enough space in our buffer to put the packet we wanted to
692 send. Shouldn't happen.
694 .BI "PEER \- socket-read-error \-\- " message
695 An error occurred trying to read an incoming packet.
697 .BI "PEER " peer " socket-write-error \-\- " message
698 An error occurred attempting to send a network packet. We lost that
701 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
702 The peer sent an encrypted ping response whose id doesn't match any
703 outstanding ping. Maybe it was delayed for longer than the server was
704 willing to wait, or maybe the peer has gone mad.
706 .BI "PEER \- unexpected-source " address\fR...
707 A packet arrived from
709 (a network address \(en see above), but no peer is known at that
710 address. This may indicate a misconfiguration, or simply be a result of
711 one end of a connection being set up before the other.
713 .BI "PEER " peer " unexpected-transport-ping 0x" id
714 The peer (apparently) sent a transport ping response whose id doesn't
715 match any outstanding ping. Maybe it was delayed for longer than the
716 server was willing to wait, or maybe the peer has gone mad; or maybe
717 there are bad people trying to confuse you.
718 .SS "SERVER warnings"
719 These indicate problems concerning the server process as a whole.
721 .BI "SERVER ignore signal " name
722 A signal arrived, but the server ignored it. Currently this happens for
724 because that's a popular way of telling daemons to re-read their
725 configuration files. Since
727 re-reads its keyrings automatically and has no other configuration
728 files, it's not relevant, but it seemed better to ignore the signal than
731 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
736 .BI "SERVER quit admin-request"
737 A client of the administration interface issued a
741 .BI "SERVER select-error \-\- " message
742 An error occurred in the server's main event loop. This is bad: if it
743 happens too many times, the server will abort.
745 These are concerned with the symmetric encryption and decryption
748 .BI "SYMM replay old-sequence"
749 A packet was received with an old sequence number. It may just have
750 been delayed or duplicated, or it may have been an attempt at a replay
753 .BI "SYMM replay duplicated-sequence"
754 A packet was received with a sequence number we've definitely seen
755 before. It may be an accidental duplication because the 'net is like
756 that, or a deliberate attempt at a replay.
758 These concern the workings of the system-specific tunnel driver. The
759 second word is the name of the tunnel interface in question, or
763 .BI "TUN \- bsd no-tunnel-devices"
764 The driver couldn't find an available tunnel device. Maybe if you
769 .BI "TUN - open-error " device " \-\- " message
770 An attempt to open the tunnel device file
774 .BI "TUN \- linux config-error \-\- " message
775 Configuring the Linux TUN/TAP interface failed.
777 .BI "TUN " ifname " read-error \-\- " message
778 Reading from the tunnel device failed.
780 .BI "TUN " ifname " slip bad-escape"
781 The SLIP driver encountered a escaped byte it wasn't expecting to see.
782 The erroneous packet will be ignored.
784 .BI "TUN " ifname " slip eof"
785 The SLIP driver encountered end-of-file on its input descriptor.
786 Pending data is discarded, and no attempt is made to read any more data
787 from that interface ever.
789 .BI "TUN " ifname " slip escape-end"
790 The SLIP driver encountered an escaped `end' marker. This probably
791 means that someone's been sending it junk. The erroneous packet is
792 discarded, and we hope that we've rediscovered synchronization.
794 .BI "TUN \- slip fork-error \-\- " message
795 The SLIP driver encountered an error forking a child process while
796 allocating a new dynamic interface.
798 .BI "TUN \- slip no-slip-interfaces"
799 The driver ran out of static SLIP interfaces. Either preallocate more,
800 or use dynamic SLIP interface allocation.
802 .BI "TUN " ifname " slip overflow"
803 The SLIP driver gave up reading a packet because it got too large.
805 .BI "TUN \- slip pipe-error \-\- " message
806 The SLIP driver encountered an error creating pipes while allocating a
807 new dynamic interface.
809 .BI "TUN \- slip read-ifname-failed \-\- " message
810 The SLIP driver encountered an error reading the name of a dynamically
811 allocated interface. Maybe the allocation script is broken.
813 .BI "TUN \- unet config-error \-\- " message
814 Configuring the Linux Unet interface failed. Unet is obsolete and
815 shouldn't be used any more.
817 .BI "TUN \- unet getinfo-error \-\- " message
818 Reading information about the Unet interface failed. Unet is obsolete
819 and shouldn't be used any more.
821 .BI "TUN \- unet ifname-too-long \-\- " message
822 The Unet interface's name overflowed, so we couldn't read it properly.
823 Unet is obsolete and shouldn't be used any more.
825 These are issued by administration clients using the
829 .BI "USER " tokens\fR...
830 An administration client issued a warning.
835 .IR "The Trivial IP Encryption Protocol" .
837 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob