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
36 For simple 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 Simple command processing is strictly synchronous: the server reads a
52 command, processes it, and responds, before reading the next command.
53 All commands can be run as simple commands. Long-running commands
58 block the client until they finish, but the rest of the server continues
60 .SS "Asynchronous messages"
61 There are three types of asynchronous messages which
62 aren't associated with any particular command.
66 message contains a machine-readable message warning of an error
67 encountered while processing a command, unexpected or unusual behaviour
68 by a peer, or a possible attack by an adversary. Under normal
69 conditions, the server shouldn't emit any warnings.
73 message contains a human-readable tracing message containing diagnostic
74 information. Trace messages are controlled using the
76 command-line option to the server, or the
78 administration command (see below). Support for tracing can be disabled
79 when the package is being configured, and may not be available in your
84 message is a machine-readable notification about some routine but
85 interesting event such as creation or destruction of peers.
87 The presence of asynchronous messages can be controlled using the
90 .SS "Background commands"
95 take a long time to complete. To prevent these long-running commands
96 from tying up a server connection, they can be run in the background.
97 Not all commands can be run like this: the ones that can provide a
99 option, which must be supplied with a
102 A command may fail before it starts running in the background. In this
103 case, the server emits a
105 response, as usual. To indicate that a command has started running in
106 the background, the server emits a response of the form
107 .BI "BGDETACH " tag \fR,
110 is the value passed to the
112 option. From this point on, the server is ready to process more
113 commands and reply to them.
115 Responses to background commands are indicated by a line beginning with
121 followed by the command tag. These correspond to the
126 responses for simple commands:
128 indicates information from a background command which has not completed
133 indicates that a background command succeeded or failed, respectively.
135 A background command will never issue an
137 response: it will always detach and then issue a
140 .SS "Network addresses"
141 A network address is a sequence of words. The first is a token
142 identifying the network address family. The length of an address and
143 the meanings of the subsequent words depend on the address family.
144 Address family tokens are not case-sensitive on input; on output, they
145 are always in upper-case.
147 At present, only one address family is understood.
149 .BI "INET " address " " port
150 An Internet socket, naming an IPv4 address and UDP port. On output, the
151 address is always in numeric dotted-quad form, and the port is given as
152 a plain number. On input, DNS hostnames and symbolic port names are
153 permitted. Name resolution does not block the main server, but will
154 block the requesting client. This hopefully makes life simpler for
155 stupid clients. Complex clients which don't wish to be held up can open
156 extra connections or do the resolution themselves.)
158 If, on input, no recognised address family token is found, the following
159 words are assumed to represent an
162 .SH "COMMAND REFERENCE"
163 The commands provided are:
165 .BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
166 Adds a new peer. The peer is given the name
168 the peer's public key is assumed to be in the file
170 (or whatever alternative file was specified in the
172 option on the command line). The
174 is the network address (see above for the format) at which the peer can
175 be contacted. The following options are recognised.
178 .BI "\-background " tag
179 Run the command in the background, using the given
182 .BI "\-keepalive " time
183 Send a no-op packet if we've not sent a packet to the peer in the last
185 interval. This is useful for persuading port-translating firewalls to
186 believe that the `connection' is still active. The
188 is expressed as a nonnegative integer followed optionally by
194 for days, hours, minutes, or seconds respectively; if no suffix is
195 given, seconds are assumed.
197 .BI "\-tunnel " tunnel
198 Use the named tunnel driver, rather than the default.
204 line reporting the IP address and port number stored for
208 Causes the server to disassociate itself from its terminal and become a
209 background task. This only works once. A warning is issued.
211 .BI "EPING \fR[" options "\fR] " peer
212 Sends an encrypted ping to the peer, and expects an encrypted response.
213 This checks that the peer is running (and not being impersonated), and
214 that it can encrypt and decrypt packets correctly. Options and
215 responses are the same as for the
220 Requests the server to begin a new key exchange with
225 Causes the server to emit an
227 line for each command it supports. Each line lists the command name,
228 followed by the names of the arguments. This may be helpful as a memory
229 aid for interactive use, or for program clients probing for features.
234 line containing the name of the network interface used to collect IP
235 packets which are to be encrypted and sent to
237 Used by configuration scripts so that they can set up routing tables
238 appropriately after adding new peers.
241 Causes the server to forget all about
243 All keys are destroyed, and no more packets are sent. No notification
244 is sent to the peer: if it's important that the peer be notified, you
245 must think of a way to do that yourself.
248 For each currently-known peer, an
250 line is written containing the peer's name, as given to
253 .BI "NOTIFY " tokens\fR...
256 notification to all interested administration clients.
258 .BI "PING \fR[" options "\fR] " peer
259 Send a transport-level ping to the peer. The ping and its response are
260 not encrypted or authenticated. This command, possibly in conjunction
261 with tracing, is useful for ensuring that UDP packets are actually
262 flowing in both directions. See also the
268 line is printed describing the outcome:
271 .BI "ping-ok " millis
272 A response was received
274 after the ping was sent.
277 No response was received within the time allowed.
280 The peer was killed (probably by another admin connection) before a
281 response was received.
284 Options recognized for this command are:
287 .BI "\-background " tag
288 Run the command in the background, using the given
291 .BI "\-timeout " time
294 seconds before giving up on a response. The default is 5 seconds. (The
295 time format is the same as for the
303 line containing just the number of the UDP port used by the
305 server. If you've allowed your server to allocate a port dynamically,
306 this is how to find out which one it chose.
309 Instructs the server to recheck its keyring files. The server checks
310 these periodically anyway but it may be necessary to force a recheck,
311 for example after adding a new peer key.
314 Instructs the server to exit immediately. A warning is sent.
319 lines, each containing one or more statistics in the form
320 .IB name = value \fR.
321 The statistics-gathering is experimental and subject to change.
323 .BR "TRACE " [\fIoptions\fP]
324 A trace argument consists of a string of letters (listed below)
325 selecting trace outputs, optionally interspersed with
329 to disable, the subsequently listed outputs; the initial behaviour is to
330 enable listed outputs. For example, the string
332 enables tracing of peer management, admin-connection handling and
333 key-exchange processing, and disables tracing of symmetric keyset
334 management and the system-specific tunnel driver. If no argument is
335 given, a table is returned showing the available tracing option letters
336 and their meanings. Programs should not attempt to parse this table:
337 its format is not guaranteed to remain the same.
340 Currently, the following tracing options are supported:
343 Tunnel events: reception of packets to be encrypted, and injection of
344 successfully-decrypted packets.
347 Peer management events: creation and destruction of peer attachments,
348 and arrival of messages.
351 Administration interface: acceptance of new connections, and handling of
352 the backgroud name-resolution required by the
357 Display contents of packets sent and received by the tunnel and/or peer
361 Display inputs, outputs and intermediate results of cryptographic
362 operations. This includes plaintext and key material. Use with
366 Handling of symmetric keysets: creation and expiry of keysets, and
367 encryption and decryption of messages.
370 Key exchange: reception, parsing and emission of key exchange messages.
373 Key management: loading keys and checking for file modifications.
381 outputs provide extra detail for other outputs. Specifying
387 isn't useful; neither is specifying
399 .BR "WATCH " [\fIoptions\fP]
400 Enables or disables asynchronous messages
401 .IR "for the current connection only" .
402 This command has no effect on other connections. A watch argument
403 consists of a string of letters (listed below) selecting message types,
404 optionally interspersed with
408 to disable, the subsequently listed types, similar to
410 above. The default watch state for the connection the server opens
411 automatically on stdin/stdout is to show warnings and trace messages;
412 other connections show no asynchronous messages. (This is done in order
413 to guarantee that a program reading the server's stdout does not miss
417 Currently, the following watch options are supported:
436 Causes the server to emit an
438 line stating its software version, as two words: the server name, and
439 its version string. The server name
441 is reserved to the Straylight/Edgeware implementation.
443 .BI "WARN " tokens\fR...
446 warning to all interested administration clients.
452 messages are sent to clients as a result of errors during command
460 server is already running as a daemon.
462 .BI "bad-syntax \-\- " message
463 (For any command.) The command couldn't be understood: e.g., the number
464 of arguments was wrong.
466 .BI "bad-time-spec " word
469 is not a valid time interval specification. Acceptable time
470 specifications are nonnegative integers followed optionally by
476 for days, hours, minutes, or seconds, respectively.
478 .BI "bad-trace-option " char
481 An unknown trace option was requested.
483 .BI "bad-watch-option " char
486 An unknown watch option was requested.
488 .BI "daemon-error \-\- " message
491 An error occurred during the attempt to become a daemon, as reported by
494 .BI "invalid-port " number
497 The given port number is out of range.
499 .BI "peer-create-fail " peer
504 failed for some reason. A warning should have been emitted explaining
507 .BI "peer-exists " peer
510 There is already a peer named
513 .B "ping-send-failed"
514 The attempt to send a ping packet failed, probably due to lack of
517 .BI "resolve-error " hostname
522 could not be resolved.
524 .BI "resolver-timeout " hostname
529 took too long to resolve.
531 .BI "unknown-command " token
536 .BI "unknown-peer " name
543 There is no peer called
546 .BI "unknown-service " service
554 The following notifications are sent to clients who request them.
556 .BI "ADD " peer " " ifname " " address \fR...
557 A new peer has been added. The peer's name is
559 its tunnel is network interface
561 and its network address is
565 The server has forked off into the sunset and become a daemon.
575 finished successfully.
580 has begun or restarted. If key exchange keeps failing, this message
581 will be repeated periodically.
583 .BI "USER " tokens\fR...
584 An administration client issued a notification using the
588 There are many possible warnings. They are categorized according to
591 These all indicate that the
593 server has become unable to continue. If enabled, the server will dump
594 core in its configuration directory.
596 .BI "ABORT repeated-select-errors"
597 The main event loop is repeatedly failing. If the server doesn't quit,
598 it will probably waste all available CPU doing nothing.
600 These indicate a problem with the administration socket interface.
602 .BI "ADMIN accept-error \-\- " message
603 There was an error while attempting to accept a connection from a new
606 .BI "ADMIN client-read-error \-\- " message
607 There was an error sending data to a client. The connection to the
608 client has been closed.
609 .SS "KEYMGMT warnings"
610 These indicate a problem with the keyring files, or the keys stored in
613 .BI "KEYMGMT bad-private-key \-\- " message
614 The private key could not be read, or failed a consistency check. If
615 there was a problem with the file, usually there will have been
617 warnings before this.
619 .BI "KEYMGMT bad-public-keyring \-\- " message
620 The public keyring couldn't be read. Usually, there will have been
622 warnings before this.
624 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
625 Reports a specific error with the named keyring file. This probably
629 .BI "KEYMGMT public-key " tag " " tokens\fR...
630 These messages all indicate a problem with the public key named
633 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
634 The algorithms specified on the public key don't match the ones for our
635 private key. All the peers in a network have to use the same
638 .BI "KEYMGMT public-key " tag " bad \-\- " message
639 The public key couldn't be read, or is invalid.
641 .BI "KEYMGMT public-key " tag " bad-public-group-element"
642 The public key is invalid. This may indicate a malicious attempt to
643 introduce a bogus key.
645 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
646 The algorithms listed on the public key couldn't be understood. The
647 algorithm selection attributes are probably malformed and need fixing.
649 .BI "KEYMGMT public-key " tag " incorrect-group"
650 The public key doesn't use the same group as our private key. All the
651 peers in a network have to use the same group.
653 .BI "KEYMGMT public-key " tag " not-found"
654 The public key for peer
656 wasn't in the public keyring.
658 .BI "KEYMGMT public-key " tag " unknown-type"
659 The type of the public key isn't understood. Maybe you need to upgrade
662 (Even if you do, you'll have to regenerate your keys.)
664 These indicate problems during key-exchange. Many indicate either a bug
665 in the server (either yours or the remote one), or some kind of attack
666 in progress. All name a
668 as the second token: this is the peer the packet is apparently from,
669 though it may have been sent by an attacker instead.
671 In the descriptions below,
682 .BI "KX " peer " bad-expected-reply-log"
685 uses in its protocol contain a check value which proves that the
686 challenge is honest. This message indicates that the check value
687 supplied is wrong: someone is attempting to use bogus challenges to
690 server to leak private key information. No chance!
692 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
693 A symmetrically-encrypted portion of a key-exchange message failed to
696 .BI "KX " peer " invalid " msgtoken
697 A key-exchange message was malformed. This almost certainly indicates a
700 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
701 A message didn't contain the right magic data. This may be a replay of
702 some old exchange, or random packets being sent in an attempt to waste
705 .BI "KX " peer " public-key-expired"
706 The peer's public key has expired. It's maintainer should have given
707 you a replacement before now.
709 .BI "KX " peer " sending-cookie"
710 We've received too many bogus pre-challenge messages. Someone is trying
711 to flood us with key-exchange messages and make us waste CPU on doing
712 hard asymmetric crypto sums.
714 .BI "KX " peer " unexpected " msgtoken
715 The message received wasn't appropriate for this stage of the key
716 exchange process. This may mean that one of our previous packets got
719 it may simply mean that the peer has recently restarted.
721 .BI "KX " peer " unknown-challenge"
722 The peer is asking for an answer to a challenge which we don't know
723 about. This may mean that we've been inundated with challenges from
724 some malicious source
725 .I who can read our messages
726 and discarded the valid one.
728 .BI "KX " peer " unknown-message 0x" nn
729 An unknown key-exchange message arrived.
731 These are largely concerned with management of peers and the low-level
732 details of the network protocol. The second word is usually the name of
737 .BI "PEER " peer " bad-packet no-type"
738 An empty packet arrived. This is very strange.
740 .BI "PEER " peer " bad-packet unknown-category 0x" nn
743 (in hex) isn't understood. Probably a strange random packet from
744 somewhere; could be an unlikely bug.
746 .BI "PEER " peer " bad-packet unknown-type 0x" nn
749 (in hex) isn't understood. Probably a strange random packet from
750 somewhere; could be an unlikely bug.
752 .BI "PEER " peer " corrupt-encrypted-ping"
753 The peer sent a ping response which matches an outstanding ping, but its
754 payload is wrong. There's definitely a bug somewhere.
756 .BI "PEER " peer " corrupt-transport-ping"
757 The peer (apparently) sent a ping response which matches an outstanding
758 ping, but its payload is wrong. Either there's a bug, or the bad guys
759 are playing tricks on you.
761 .BI "PEER " peer " decrypt-failed"
762 An encrypted IP packet failed to decrypt. It may have been mangled in
763 transit, or may be a very old packet from an expired previous session
764 key. There is usually a considerable overlap in the validity periods of
765 successive session keys, so this shouldn't occur unless the key exchange
768 .BI "PEER " peer " malformed-encrypted-ping"
769 The peer sent a ping response which is hopelessly invalid. There's
770 definitely a bug somewhere.
772 .BI "PEER " peer " malformed-transport-ping"
773 The peer (apparently) sent a ping response which is hopelessly invalid.
774 Either there's a bug, or the bad guys are playing tricks on you.
776 .BI "PEER " peer " packet-build-failed"
777 There wasn't enough space in our buffer to put the packet we wanted to
778 send. Shouldn't happen.
780 .BI "PEER \- socket-read-error \-\- " message
781 An error occurred trying to read an incoming packet.
783 .BI "PEER " peer " socket-write-error \-\- " message
784 An error occurred attempting to send a network packet. We lost that
787 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
788 The peer sent an encrypted ping response whose id doesn't match any
789 outstanding ping. Maybe it was delayed for longer than the server was
790 willing to wait, or maybe the peer has gone mad.
792 .BI "PEER \- unexpected-source " address\fR...
793 A packet arrived from
795 (a network address \(en see above), but no peer is known at that
796 address. This may indicate a misconfiguration, or simply be a result of
797 one end of a connection being set up before the other.
799 .BI "PEER " peer " unexpected-transport-ping 0x" id
800 The peer (apparently) sent a transport ping response whose id doesn't
801 match any outstanding ping. Maybe it was delayed for longer than the
802 server was willing to wait, or maybe the peer has gone mad; or maybe
803 there are bad people trying to confuse you.
804 .SS "SERVER warnings"
805 These indicate problems concerning the server process as a whole.
807 .BI "SERVER ignore signal " name
808 A signal arrived, but the server ignored it. Currently this happens for
810 because that's a popular way of telling daemons to re-read their
811 configuration files. Since
813 re-reads its keyrings automatically and has no other configuration
814 files, it's not relevant, but it seemed better to ignore the signal than
817 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
822 .BI "SERVER quit admin-request"
823 A client of the administration interface issued a
827 .BI "SERVER select-error \-\- " message
828 An error occurred in the server's main event loop. This is bad: if it
829 happens too many times, the server will abort.
831 These are concerned with the symmetric encryption and decryption
834 .BI "SYMM replay old-sequence"
835 A packet was received with an old sequence number. It may just have
836 been delayed or duplicated, or it may have been an attempt at a replay
839 .BI "SYMM replay duplicated-sequence"
840 A packet was received with a sequence number we've definitely seen
841 before. It may be an accidental duplication because the 'net is like
842 that, or a deliberate attempt at a replay.
844 These concern the workings of the system-specific tunnel driver. The
845 second word is the name of the tunnel interface in question, or
849 .BI "TUN \- bsd no-tunnel-devices"
850 The driver couldn't find an available tunnel device. Maybe if you
855 .BI "TUN - open-error " device " \-\- " message
856 An attempt to open the tunnel device file
860 .BI "TUN \- linux config-error \-\- " message
861 Configuring the Linux TUN/TAP interface failed.
863 .BI "TUN " ifname " read-error \-\- " message
864 Reading from the tunnel device failed.
866 .BI "TUN " ifname " slip bad-escape"
867 The SLIP driver encountered a escaped byte it wasn't expecting to see.
868 The erroneous packet will be ignored.
870 .BI "TUN " ifname " slip eof"
871 The SLIP driver encountered end-of-file on its input descriptor.
872 Pending data is discarded, and no attempt is made to read any more data
873 from that interface ever.
875 .BI "TUN " ifname " slip escape-end"
876 The SLIP driver encountered an escaped `end' marker. This probably
877 means that someone's been sending it junk. The erroneous packet is
878 discarded, and we hope that we've rediscovered synchronization.
880 .BI "TUN \- slip fork-error \-\- " message
881 The SLIP driver encountered an error forking a child process while
882 allocating a new dynamic interface.
884 .BI "TUN \- slip no-slip-interfaces"
885 The driver ran out of static SLIP interfaces. Either preallocate more,
886 or use dynamic SLIP interface allocation.
888 .BI "TUN " ifname " slip overflow"
889 The SLIP driver gave up reading a packet because it got too large.
891 .BI "TUN \- slip pipe-error \-\- " message
892 The SLIP driver encountered an error creating pipes while allocating a
893 new dynamic interface.
895 .BI "TUN \- slip read-ifname-failed \-\- " message
896 The SLIP driver encountered an error reading the name of a dynamically
897 allocated interface. Maybe the allocation script is broken.
899 .BI "TUN \- unet config-error \-\- " message
900 Configuring the Linux Unet interface failed. Unet is obsolete and
901 shouldn't be used any more.
903 .BI "TUN \- unet getinfo-error \-\- " message
904 Reading information about the Unet interface failed. Unet is obsolete
905 and shouldn't be used any more.
907 .BI "TUN \- unet ifname-too-long \-\- " message
908 The Unet interface's name overflowed, so we couldn't read it properly.
909 Unet is obsolete and shouldn't be used any more.
911 These are issued by administration clients using the
915 .BI "USER " tokens\fR...
916 An administration client issued a warning.
921 .IR "The Trivial IP Encryption Protocol" .
923 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob