8 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
10 tripe-admin \- administrator commands for TrIPE
12 This manual page describes the administration interface provided by the
18 program can be used either interactively or in scripts to communicate
19 with the server using this interface. Alternatively, simple custom
20 clients can be written in scripting languages such as Perl, Python or
21 Tcl, or more advanced clients such as GUI monitors can be written in C
22 with little difficulty.
24 By default, the server listens for admin connections on the Unix-domain
26 .BR /var/lib/tripe/tripesock .
27 Administration commands use a simple textual protocol. Each client
28 command or server response consists of a line of ASCII text terminated
29 by a single linefeed character. No command may be longer than 255
31 .SS "General structure"
32 Each command or response line consists of a sequence of
33 whitespace-separated words. The number and nature of whitespace
34 characters separating two words in a client command is not significant;
35 the server always uses a single space character. The first word in a
38 identifying the type of command or response contained. Keywords in
39 client commands are not case-sensitive; the server always uses uppercase
42 For simple client command, the server responds with zero or more
44 lines, followed by either an
50 provides information requested in the command. An
52 response contains no further data. A
54 code is followed by a machine-readable explanation of why the command
57 Simple command processing is strictly synchronous: the server reads a
58 command, processes it, and responds, before reading the next command.
59 All commands can be run as simple commands. Long-running commands
64 block the client until they finish, but the rest of the server continues
66 .SS "Asynchronous messages"
67 There are three types of asynchronous messages which
68 aren't associated with any particular command.
72 message contains a machine-readable message warning of an error
73 encountered while processing a command, unexpected or unusual behaviour
74 by a peer, or a possible attack by an adversary. Under normal
75 conditions, the server shouldn't emit any warnings.
79 message contains a human-readable tracing message containing diagnostic
80 information. Trace messages are controlled using the
82 command-line option to the server, or the
84 administration command (see below). Support for tracing can be disabled
85 when the package is being configured, and may not be available in your
90 message is a machine-readable notification about some routine but
91 interesting event such as creation or destruction of peers.
93 The presence of asynchronous messages can be controlled using the
96 .SS "Background commands"
101 take a long time to complete. To prevent these long-running commands
102 from tying up a server connection, they can be run in the background.
103 Not all commands can be run like this: the ones that can provide a
105 option, which must be supplied with a
108 A command may fail before it starts running in the background. In this
109 case, the server emits a
111 response, as usual. To indicate that a command has started running in
112 the background, the server emits a response of the form
113 .BI "BGDETACH " tag \fR,
116 is the value passed to the
118 option. From this point on, the server is ready to process more
119 commands and reply to them.
121 Responses to background commands are indicated by a line beginning with
127 followed by the command tag. These correspond to the
132 responses for simple commands:
134 indicates information from a background command which has not completed
139 indicates that a background command succeeded or failed, respectively.
141 A background command will never issue an
145 response: it will always detach and then issue any
150 .SS "Network addresses"
151 A network address is a sequence of words. The first is a token
152 identifying the network address family. The length of an address and
153 the meanings of the subsequent words depend on the address family.
154 Address family tokens are not case-sensitive on input; on output, they
155 are always in upper-case.
157 At present, only one address family is understood.
159 .BI "INET " address " " port
160 An Internet socket, naming an IPv4 address and UDP port. On output, the
161 address is always in numeric dotted-quad form, and the port is given as
162 a plain number. On input, DNS hostnames and symbolic port names are
163 permitted. Name resolution does not block the main server, but will
164 block the requesting client. This hopefully makes life simpler for
165 stupid clients. Complex clients which don't wish to be held up can open
166 extra connections or do the resolution themselves.)
168 If, on input, no recognised address family token is found, the following
169 words are assumed to represent an
172 .SS "Key-value output"
177 produce output in the form of
179 pairs, one per word. Neither the
185 Commands which enable or disable kinds of output (e.g.,
189 work in similar ways. They take a single optional argument, which
190 consists of a string of letters selecting message types, optionally
195 to disable, the subsequently listed types.
197 If the argument is omitted, the available message types are displayed,
200 line, in a fixed-column format. Column zero contains the key letter for
201 selecting that message type; column one contains either a space or a
203 sign, if the message type is disabled or enabled respectively; and a
204 textual description of the message type begins at column 3 and continues
205 to the end of the line.
207 Lowercase key letters control individual message types. Uppercase key
208 letters control collections of message types.
209 .SH "COMMAND REFERENCE"
210 The commands provided are:
212 .BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
213 Adds a new peer. The peer is given the name
215 the peer's public key is assumed to be in the file
217 (or whatever alternative file was specified in the
219 option on the command line). The
221 is the network address (see above for the format) at which the peer can
222 be contacted. The following options are recognised.
225 .BI "\-background " tag
226 Run the command in the background, using the given
229 .BI "\-keepalive " time
230 Send a no-op packet if we've not sent a packet to the peer in the last
232 interval. This is useful for persuading port-translating firewalls to
233 believe that the `connection' is still active. The
235 is expressed as a nonnegative integer followed optionally by
241 for days, hours, minutes, or seconds respectively; if no suffix is
242 given, seconds are assumed.
244 .BI "\-tunnel " tunnel
245 Use the named tunnel driver, rather than the default.
251 line reporting the IP address and port number stored for
255 Causes the server to disassociate itself from its terminal and become a
256 background task. This only works once. A warning is issued.
258 .BI "EPING \fR[" options "\fR] " peer
259 Sends an encrypted ping to the peer, and expects an encrypted response.
260 This checks that the peer is running (and not being impersonated), and
261 that it can encrypt and decrypt packets correctly. Options and
262 responses are the same as for the
267 Requests the server to begin a new key exchange with
272 Causes the server to emit an
274 line for each command it supports. Each line lists the command name,
275 followed by the names of the arguments. This may be helpful as a memory
276 aid for interactive use, or for program clients probing for features.
281 line containing the name of the network interface used to collect IP
282 packets which are to be encrypted and sent to
284 Used by configuration scripts so that they can set up routing tables
285 appropriately after adding new peers.
288 Causes the server to forget all about
290 All keys are destroyed, and no more packets are sent. No notification
291 is sent to the peer: if it's important that the peer be notified, you
292 must think of a way to do that yourself.
295 For each currently-known peer, an
297 line is written containing the peer's name, as given to
300 .BI "NOTIFY " tokens\fR...
303 notification to all interested administration clients.
306 Returns information about a peer, in key-value form. The following keys
311 The tunnel driver used for this peer.
314 The keepalive interval, in seconds, or zero if no keepalives are to be
318 .BI "PING \fR[" options "\fR] " peer
319 Send a transport-level ping to the peer. The ping and its response are
320 not encrypted or authenticated. This command, possibly in conjunction
321 with tracing, is useful for ensuring that UDP packets are actually
322 flowing in both directions. See also the
328 line is printed describing the outcome:
331 .BI "ping-ok " millis
332 A response was received
334 after the ping was sent.
337 No response was received within the time allowed.
340 The peer was killed (probably by another admin connection) before a
341 response was received.
344 Options recognized for this command are:
347 .BI "\-background " tag
348 Run the command in the background, using the given
351 .BI "\-timeout " time
354 seconds before giving up on a response. The default is 5 seconds. (The
355 time format is the same as for the
363 line containing just the number of the UDP port used by the
365 server. If you've allowed your server to allocate a port dynamically,
366 this is how to find out which one it chose.
369 Instructs the server to recheck its keyring files. The server checks
370 these periodically anyway but it may be necessary to force a recheck,
371 for example after adding a new peer key.
374 Instructs the server to exit immediately. A warning is sent.
377 Returns information about the server, in the form of key-value pairs.
378 The following keys are used.
382 A keyword naming the implementation of the
384 server. The current implementation is called
388 The server's version number, as reported by
396 if the server has or hasn't (respectively) become a daemon.
402 lines, each containing one or more statistics in the form
403 .IB name = value \fR.
404 The statistics-gathering is experimental and subject to change.
406 .BR "TRACE " [\fIoptions\fP]
407 Selects trace outputs: see
409 above. Message types provided are:
412 Currently, the following tracing options are supported:
415 Tunnel events: reception of packets to be encrypted, and injection of
416 successfully-decrypted packets.
419 Peer management events: creation and destruction of peer attachments,
420 and arrival of messages.
423 Administration interface: acceptance of new connections, and handling of
424 the backgroud name-resolution required by the
429 Display contents of packets sent and received by the tunnel and/or peer
433 Display inputs, outputs and intermediate results of cryptographic
434 operations. This includes plaintext and key material. Use with
438 Handling of symmetric keysets: creation and expiry of keysets, and
439 encryption and decryption of messages.
442 Key exchange: reception, parsing and emission of key exchange messages.
445 Key management: loading keys and checking for file modifications.
453 outputs provide extra detail for other outputs. Specifying
459 isn't useful; neither is specifying
472 For each available tunnel driver, an
474 line is printed giving its name.
477 Causes the server to emit an
479 line stating its software version, as two words: the server name, and
480 its version string. The server name
482 is reserved to the Straylight/Edgeware implementation.
484 .BR "WATCH " [\fIoptions\fP]
485 Enables or disables asynchronous messages
486 .IR "for the current connection only" .
489 above. The default watch state for the connection the server opens
490 automatically on stdin/stdout is to show warnings and trace messages;
491 other connections show no asynchronous messages. (This is done in order
492 to guarantee that a program reading the server's stdout does not miss
496 Message types provided are:
514 .BI "WARN " tokens\fR...
517 warning to all interested administration clients.
523 messages are sent to clients as a result of errors during command
531 server is already running as a daemon.
533 .BI "bad-syntax \-\- " message
534 (For any command.) The command couldn't be understood: e.g., the number
535 of arguments was wrong.
537 .BI "bad-time-spec " word
540 is not a valid time interval specification. Acceptable time
541 specifications are nonnegative integers followed optionally by
547 for days, hours, minutes, or seconds, respectively.
549 .BI "bad-trace-option " char
552 An unknown trace option was requested.
554 .BI "bad-watch-option " char
557 An unknown watch option was requested.
559 .BI "daemon-error \-\- " message
562 An error occurred during the attempt to become a daemon, as reported by
565 .BI "invalid-port " number
568 The given port number is out of range.
570 .BI "peer-create-fail " peer
575 failed for some reason. A warning should have been emitted explaining
578 .BI "peer-exists " peer
581 There is already a peer named
584 .B "ping-send-failed"
585 The attempt to send a ping packet failed, probably due to lack of
588 .BI "resolve-error " hostname
593 could not be resolved.
595 .BI "resolver-timeout " hostname
600 took too long to resolve.
602 .BI "unknown-command " token
607 .BI "unknown-peer " name
614 There is no peer called
617 .BI "unknown-service " service
625 The following notifications are sent to clients who request them.
627 .BI "ADD " peer " " ifname " " address \fR...
628 A new peer has been added. The peer's name is
630 its tunnel is network interface
632 and its network address is
636 The server has forked off into the sunset and become a daemon.
646 finished successfully.
651 has begun or restarted. If key exchange keeps failing, this message
652 will be repeated periodically.
654 .BI "USER " tokens\fR...
655 An administration client issued a notification using the
659 There are many possible warnings. They are categorized according to
662 These all indicate that the
664 server has become unable to continue. If enabled, the server will dump
665 core in its configuration directory.
667 .BI "ABORT repeated-select-errors"
668 The main event loop is repeatedly failing. If the server doesn't quit,
669 it will probably waste all available CPU doing nothing.
671 These indicate a problem with the administration socket interface.
673 .BI "ADMIN accept-error \-\- " message
674 There was an error while attempting to accept a connection from a new
677 .BI "ADMIN client-read-error \-\- " message
678 There was an error sending data to a client. The connection to the
679 client has been closed.
680 .SS "KEYMGMT warnings"
681 These indicate a problem with the keyring files, or the keys stored in
684 .BI "KEYMGMT bad-private-key \-\- " message
685 The private key could not be read, or failed a consistency check. If
686 there was a problem with the file, usually there will have been
688 warnings before this.
690 .BI "KEYMGMT bad-public-keyring \-\- " message
691 The public keyring couldn't be read. Usually, there will have been
693 warnings before this.
695 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
696 Reports a specific error with the named keyring file. This probably
700 .BI "KEYMGMT public-key " tag " " tokens\fR...
701 These messages all indicate a problem with the public key named
704 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
705 The algorithms specified on the public key don't match the ones for our
706 private key. All the peers in a network have to use the same
709 .BI "KEYMGMT public-key " tag " bad \-\- " message
710 The public key couldn't be read, or is invalid.
712 .BI "KEYMGMT public-key " tag " bad-public-group-element"
713 The public key is invalid. This may indicate a malicious attempt to
714 introduce a bogus key.
716 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
717 The algorithms listed on the public key couldn't be understood. The
718 algorithm selection attributes are probably malformed and need fixing.
720 .BI "KEYMGMT public-key " tag " incorrect-group"
721 The public key doesn't use the same group as our private key. All the
722 peers in a network have to use the same group.
724 .BI "KEYMGMT public-key " tag " not-found"
725 The public key for peer
727 wasn't in the public keyring.
729 .BI "KEYMGMT public-key " tag " unknown-type"
730 The type of the public key isn't understood. Maybe you need to upgrade
733 (Even if you do, you'll have to regenerate your keys.)
735 These indicate problems during key-exchange. Many indicate either a bug
736 in the server (either yours or the remote one), or some kind of attack
737 in progress. All name a
739 as the second token: this is the peer the packet is apparently from,
740 though it may have been sent by an attacker instead.
742 In the descriptions below,
753 .BI "KX " peer " bad-expected-reply-log"
756 uses in its protocol contain a check value which proves that the
757 challenge is honest. This message indicates that the check value
758 supplied is wrong: someone is attempting to use bogus challenges to
761 server to leak private key information. No chance!
763 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
764 A symmetrically-encrypted portion of a key-exchange message failed to
767 .BI "KX " peer " invalid " msgtoken
768 A key-exchange message was malformed. This almost certainly indicates a
771 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
772 A message didn't contain the right magic data. This may be a replay of
773 some old exchange, or random packets being sent in an attempt to waste
776 .BI "KX " peer " public-key-expired"
777 The peer's public key has expired. It's maintainer should have given
778 you a replacement before now.
780 .BI "KX " peer " sending-cookie"
781 We've received too many bogus pre-challenge messages. Someone is trying
782 to flood us with key-exchange messages and make us waste CPU on doing
783 hard asymmetric crypto sums.
785 .BI "KX " peer " unexpected " msgtoken
786 The message received wasn't appropriate for this stage of the key
787 exchange process. This may mean that one of our previous packets got
790 it may simply mean that the peer has recently restarted.
792 .BI "KX " peer " unknown-challenge"
793 The peer is asking for an answer to a challenge which we don't know
794 about. This may mean that we've been inundated with challenges from
795 some malicious source
796 .I who can read our messages
797 and discarded the valid one.
799 .BI "KX " peer " unknown-message 0x" nn
800 An unknown key-exchange message arrived.
802 These are largely concerned with management of peers and the low-level
803 details of the network protocol. The second word is usually the name of
808 .BI "PEER " peer " bad-packet no-type"
809 An empty packet arrived. This is very strange.
811 .BI "PEER " peer " bad-packet unknown-category 0x" nn
814 (in hex) isn't understood. Probably a strange random packet from
815 somewhere; could be an unlikely bug.
817 .BI "PEER " peer " bad-packet unknown-type 0x" nn
820 (in hex) isn't understood. Probably a strange random packet from
821 somewhere; could be an unlikely bug.
823 .BI "PEER " peer " corrupt-encrypted-ping"
824 The peer sent a ping response which matches an outstanding ping, but its
825 payload is wrong. There's definitely a bug somewhere.
827 .BI "PEER " peer " corrupt-transport-ping"
828 The peer (apparently) sent a ping response which matches an outstanding
829 ping, but its payload is wrong. Either there's a bug, or the bad guys
830 are playing tricks on you.
832 .BI "PEER " peer " decrypt-failed"
833 An encrypted IP packet failed to decrypt. It may have been mangled in
834 transit, or may be a very old packet from an expired previous session
835 key. There is usually a considerable overlap in the validity periods of
836 successive session keys, so this shouldn't occur unless the key exchange
839 .BI "PEER " peer " malformed-encrypted-ping"
840 The peer sent a ping response which is hopelessly invalid. There's
841 definitely a bug somewhere.
843 .BI "PEER " peer " malformed-transport-ping"
844 The peer (apparently) sent a ping response which is hopelessly invalid.
845 Either there's a bug, or the bad guys are playing tricks on you.
847 .BI "PEER " peer " packet-build-failed"
848 There wasn't enough space in our buffer to put the packet we wanted to
849 send. Shouldn't happen.
851 .BI "PEER \- socket-read-error \-\- " message
852 An error occurred trying to read an incoming packet.
854 .BI "PEER " peer " socket-write-error \-\- " message
855 An error occurred attempting to send a network packet. We lost that
858 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
859 The peer sent an encrypted ping response whose id doesn't match any
860 outstanding ping. Maybe it was delayed for longer than the server was
861 willing to wait, or maybe the peer has gone mad.
863 .BI "PEER \- unexpected-source " address\fR...
864 A packet arrived from
866 (a network address \(en see above), but no peer is known at that
867 address. This may indicate a misconfiguration, or simply be a result of
868 one end of a connection being set up before the other.
870 .BI "PEER " peer " unexpected-transport-ping 0x" id
871 The peer (apparently) sent a transport ping response whose id doesn't
872 match any outstanding ping. Maybe it was delayed for longer than the
873 server was willing to wait, or maybe the peer has gone mad; or maybe
874 there are bad people trying to confuse you.
875 .SS "SERVER warnings"
876 These indicate problems concerning the server process as a whole.
878 .BI "SERVER ignore signal " name
879 A signal arrived, but the server ignored it. Currently this happens for
881 because that's a popular way of telling daemons to re-read their
882 configuration files. Since
884 re-reads its keyrings automatically and has no other configuration
885 files, it's not relevant, but it seemed better to ignore the signal than
888 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
893 .BI "SERVER quit admin-request"
894 A client of the administration interface issued a
898 .BI "SERVER select-error \-\- " message
899 An error occurred in the server's main event loop. This is bad: if it
900 happens too many times, the server will abort.
902 These are concerned with the symmetric encryption and decryption
905 .BI "SYMM replay old-sequence"
906 A packet was received with an old sequence number. It may just have
907 been delayed or duplicated, or it may have been an attempt at a replay
910 .BI "SYMM replay duplicated-sequence"
911 A packet was received with a sequence number we've definitely seen
912 before. It may be an accidental duplication because the 'net is like
913 that, or a deliberate attempt at a replay.
915 These concern the workings of the system-specific tunnel driver. The
916 second word is the name of the tunnel interface in question, or
920 .BI "TUN \- bsd no-tunnel-devices"
921 The driver couldn't find an available tunnel device. Maybe if you
926 .BI "TUN - open-error " device " \-\- " message
927 An attempt to open the tunnel device file
931 .BI "TUN \- linux config-error \-\- " message
932 Configuring the Linux TUN/TAP interface failed.
934 .BI "TUN " ifname " read-error \-\- " message
935 Reading from the tunnel device failed.
937 .BI "TUN " ifname " slip bad-escape"
938 The SLIP driver encountered a escaped byte it wasn't expecting to see.
939 The erroneous packet will be ignored.
941 .BI "TUN " ifname " slip eof"
942 The SLIP driver encountered end-of-file on its input descriptor.
943 Pending data is discarded, and no attempt is made to read any more data
944 from that interface ever.
946 .BI "TUN " ifname " slip escape-end"
947 The SLIP driver encountered an escaped `end' marker. This probably
948 means that someone's been sending it junk. The erroneous packet is
949 discarded, and we hope that we've rediscovered synchronization.
951 .BI "TUN \- slip fork-error \-\- " message
952 The SLIP driver encountered an error forking a child process while
953 allocating a new dynamic interface.
955 .BI "TUN \- slip no-slip-interfaces"
956 The driver ran out of static SLIP interfaces. Either preallocate more,
957 or use dynamic SLIP interface allocation.
959 .BI "TUN " ifname " slip overflow"
960 The SLIP driver gave up reading a packet because it got too large.
962 .BI "TUN \- slip pipe-error \-\- " message
963 The SLIP driver encountered an error creating pipes while allocating a
964 new dynamic interface.
966 .BI "TUN \- slip read-ifname-failed \-\- " message
967 The SLIP driver encountered an error reading the name of a dynamically
968 allocated interface. Maybe the allocation script is broken.
970 .BI "TUN \- unet config-error \-\- " message
971 Configuring the Linux Unet interface failed. Unet is obsolete and
972 shouldn't be used any more.
974 .BI "TUN \- unet getinfo-error \-\- " message
975 Reading information about the Unet interface failed. Unet is obsolete
976 and shouldn't be used any more.
978 .BI "TUN \- unet ifname-too-long \-\- " message
979 The Unet interface's name overflowed, so we couldn't read it properly.
980 Unet is obsolete and shouldn't be used any more.
982 These are issued by administration clients using the
986 .BI "USER " tokens\fR...
987 An administration client issued a warning.
992 .IR "The Trivial IP Encryption Protocol" .
994 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob