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 textual protocol. Each client command or
28 server response consists of a line of ASCII text terminated by a single
29 linefeed character. No command may be longer than 255 characters.
30 .SS "General structure"
31 Each command or response line consists of a sequence of
32 whitespace-separated words. The number and nature of whitespace
33 characters separating two words in a client command is not significant;
34 the server always uses a single space character. The first word in a
37 identifying the type of command or response contained. Keywords in
38 client commands are not case-sensitive; the server always uses uppercase
41 For simple client command, the server responds with zero or more
43 lines, followed by either an
49 provides information requested in the command. An
51 response contains no further data. A
53 code is followed by a machine-readable explanation of why the command
56 Simple command processing is strictly synchronous: the server reads a
57 command, processes it, and responds, before reading the next command.
58 All commands can be run as simple commands. Long-running commands
63 block the client until they finish, but the rest of the server continues
65 .SS "Asynchronous messages"
66 There are three types of asynchronous messages which
67 aren't associated with any particular command.
71 message contains a machine-readable message warning of an error
72 encountered while processing a command, unexpected or unusual behaviour
73 by a peer, or a possible attack by an adversary. Under normal
74 conditions, the server shouldn't emit any warnings.
78 message contains a human-readable tracing message containing diagnostic
79 information. Trace messages are controlled using the
81 command-line option to the server, or the
83 administration command (see below). Support for tracing can be disabled
84 when the package is being configured, and may not be available in your
89 message is a machine-readable notification about some routine but
90 interesting event such as creation or destruction of peers.
92 The presence of asynchronous messages can be controlled using the
95 .SS "Background commands"
100 take a long time to complete. To prevent these long-running commands
101 from tying up a server connection, they can be run in the background.
102 Not all commands can be run like this: the ones that can provide a
104 option, which must be supplied with a
107 A command may fail before it starts running in the background. In this
108 case, the server emits a
110 response, as usual. To indicate that a command has started running in
111 the background, the server emits a response of the form
112 .BI "BGDETACH " tag \fR,
115 is the value passed to the
117 option. From this point on, the server is ready to process more
118 commands and reply to them.
120 Responses to background commands are indicated by a line beginning with
126 followed by the command tag. These correspond to the
131 responses for simple commands:
133 indicates information from a background command which has not completed
138 indicates that a background command succeeded or failed, respectively.
140 A background command will never issue an
144 response: it will always detach and then issue any
149 .SS "Network addresses"
150 A network address is a sequence of words. The first is a token
151 identifying the network address family. The length of an address and
152 the meanings of the subsequent words depend on the address family.
153 Address family tokens are not case-sensitive on input; on output, they
154 are always in upper-case.
156 At present, only one address family is understood.
158 .BI "INET " address " " port
159 An Internet socket, naming an IPv4 address and UDP port. On output, the
160 address is always in numeric dotted-quad form, and the port is given as
161 a plain number. On input, DNS hostnames and symbolic port names are
162 permitted. Name resolution does not block the main server, but will
163 block the requesting client. This hopefully makes life simpler for
164 stupid clients. Complex clients which don't wish to be held up can open
165 extra connections or do the resolution themselves.)
167 If, on input, no recognised address family token is found, the following
168 words are assumed to represent an
171 .SS "Key-value output"
176 produce output in the form of
178 pairs, one per word. Neither the
184 Commands which enable or disable kinds of output (e.g.,
188 work in similar ways. They take a single optional argument, which
189 consists of a string of letters selecting message types, optionally
194 to disable, the subsequently listed types.
196 If the argument is omitted, the available message types are displayed,
199 line, in a fixed-column format. Column zero contains the key letter for
200 selecting that message type; column one contains either a space or a
202 sign, if the message type is disabled or enabled respectively; and a
203 textual description of the message type begins at column 3 and continues
204 to the end of the line.
206 Lowercase key letters control individual message types. Uppercase key
207 letters control collections of message types.
208 .SH "COMMAND REFERENCE"
209 The commands provided are:
211 .BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
212 Adds a new peer. The peer is given the name
214 the peer's public key is assumed to be in the file
216 (or whatever alternative file was specified in the
218 option on the command line). The
220 is the network address (see above for the format) at which the peer can
221 be contacted. The following options are recognised.
224 .BI "\-background " tag
225 Run the command in the background, using the given
228 .BI "\-keepalive " time
229 Send a no-op packet if we've not sent a packet to the peer in the last
231 interval. This is useful for persuading port-translating firewalls to
232 believe that the `connection' is still active. The
234 is expressed as a nonnegative integer followed optionally by
240 for days, hours, minutes, or seconds respectively; if no suffix is
241 given, seconds are assumed.
243 .BI "\-tunnel " tunnel
244 Use the named tunnel driver, rather than the default.
250 line reporting the IP address and port number stored for
253 .BI "CHECKCHAL " challenge
254 Verifies a challenge as being one earlier issued by
256 and not previously either passed to
258 or in a greeting message.
261 Causes the server to disassociate itself from its terminal and become a
262 background task. This only works once. A warning is issued.
264 .BI "EPING \fR[" options "\fR] " peer
265 Sends an encrypted ping to the peer, and expects an encrypted response.
266 This checks that the peer is running (and not being impersonated), and
267 that it can encrypt and decrypt packets correctly. Options and
268 responses are the same as for the
273 Requests the server to begin a new key exchange with
278 Requests a challenge. The challenge is returned in an
280 line, as a base64-encoded string. See
283 .BI "GREET " peer " " challenge
284 Sends a greeting packet containing the
286 (base-64 encoded) to the named
288 The expectation is that this will cause the peer to recognize us and
289 begin a key-exchange.
292 Causes the server to emit an
294 line for each command it supports. Each line lists the command name,
295 followed by the names of the arguments. This may be helpful as a memory
296 aid for interactive use, or for program clients probing for features.
301 line containing the name of the network interface used to collect IP
302 packets which are to be encrypted and sent to
304 Used by configuration scripts so that they can set up routing tables
305 appropriately after adding new peers.
308 Causes the server to forget all about
310 All keys are destroyed, and no more packets are sent. No notification
311 is sent to the peer: if it's important that the peer be notified, you
312 must think of a way to do that yourself.
315 For each currently-known peer, an
317 line is written containing the peer's name, as given to
320 .BI "NOTIFY " tokens\fR...
323 notification to all interested administration clients.
326 Returns information about a peer, in key-value form. The following keys
331 The tunnel driver used for this peer.
334 The keepalive interval, in seconds, or zero if no keepalives are to be
338 .BI "PING \fR[" options "\fR] " peer
339 Send a transport-level ping to the peer. The ping and its response are
340 not encrypted or authenticated. This command, possibly in conjunction
341 with tracing, is useful for ensuring that UDP packets are actually
342 flowing in both directions. See also the
348 line is printed describing the outcome:
351 .BI "ping-ok " millis
352 A response was received
354 after the ping was sent.
357 No response was received within the time allowed.
360 The peer was killed (probably by another admin connection) before a
361 response was received.
364 Options recognized for this command are:
367 .BI "\-background " tag
368 Run the command in the background, using the given
371 .BI "\-timeout " time
374 seconds before giving up on a response. The default is 5 seconds. (The
375 time format is the same as for the
383 line containing just the number of the UDP port used by the
385 server. If you've allowed your server to allocate a port dynamically,
386 this is how to find out which one it chose.
389 Instructs the server to recheck its keyring files. The server checks
390 these periodically anyway but it may be necessary to force a recheck,
391 for example after adding a new peer key.
394 Instructs the server to exit immediately. A warning is sent.
397 Returns information about the server, in the form of key-value pairs.
398 The following keys are used.
402 A keyword naming the implementation of the
404 server. The current implementation is called
408 The server's version number, as reported by
416 if the server has or hasn't (respectively) become a daemon.
422 lines, each containing one or more statistics in the form
423 .IB name = value \fR.
424 The statistics-gathering is experimental and subject to change.
426 .BR "TRACE " [\fIoptions\fP]
427 Selects trace outputs: see
429 above. Message types provided are:
432 Currently, the following tracing options are supported:
435 Tunnel events: reception of packets to be encrypted, and injection of
436 successfully-decrypted packets.
439 Peer management events: creation and destruction of peer attachments,
440 and arrival of messages.
443 Administration interface: acceptance of new connections, and handling of
444 the backgroud name-resolution required by the
449 Handling of symmetric keysets: creation and expiry of keysets, and
450 encryption and decryption of messages.
453 Key exchange: reception, parsing and emission of key exchange messages.
456 Key management: loading keys and checking for file modifications.
459 Display information about challenge issuing and verification.
462 Display contents of packets sent and received by the tunnel and/or peer
466 Display inputs, outputs and intermediate results of cryptographic
467 operations. This includes plaintext and key material. Use with
479 outputs provide extra detail for other outputs. Specifying
485 isn't useful; neither is specifying
496 For each available tunnel driver, an
498 line is printed giving its name.
501 Causes the server to emit an
503 line stating its software version, as two words: the server name, and
504 its version string. The server name
506 is reserved to the Straylight/Edgeware implementation.
508 .BR "WATCH " [\fIoptions\fP]
509 Enables or disables asynchronous messages
510 .IR "for the current connection only" .
513 above. The default watch state for the connection the server opens
514 automatically on stdin/stdout is to show warnings and trace messages;
515 other connections show no asynchronous messages. (This is done in order
516 to guarantee that a program reading the server's stdout does not miss
520 Message types provided are:
538 .BI "WARN " tokens\fR...
541 warning to all interested administration clients.
547 messages are sent to clients as a result of errors during command
555 server is already running as a daemon.
557 .BI "bad-addr-syntax " message
558 (For commands accepting socket addresses.) The address couldn't be
561 .BI "bad-syntax " cmd " " message
562 (For any command.) The command couldn't be understood: e.g., the number
563 of arguments was wrong.
565 .BI "bad-time-spec " word
568 is not a valid time interval specification. Acceptable time
569 specifications are nonnegative integers followed optionally by
575 for days, hours, minutes, or seconds, respectively.
577 .BI "bad-trace-option " char
580 An unknown trace option was requested.
582 .BI "bad-watch-option " char
585 An unknown watch option was requested.
587 .BI "daemon-error " ecode " " message
590 An error occurred during the attempt to become a daemon, as reported by
593 .BI "invalid-port " number
596 The given port number is out of range.
598 .BI "peer-create-fail " peer
603 failed for some reason. A warning should have been emitted explaining
606 .BI "peer-exists " peer
609 There is already a peer named
612 .B "ping-send-failed"
613 The attempt to send a ping packet failed, probably due to lack of
616 .BI "resolve-error " hostname
621 could not be resolved.
623 .BI "resolver-timeout " hostname
628 took too long to resolve.
630 .BI "unknown-command " token
635 .BI "unknown-peer " name
642 There is no peer called
645 .BI "unknown-service " service
653 The following notifications are sent to clients who request them.
655 .BI "ADD " peer " " ifname " " address \fR...
656 A new peer has been added. The peer's name is
658 its tunnel is network interface
660 and its network address is
664 The server has forked off into the sunset and become a daemon.
666 .BI "GREET " challenge " " address \fR...
667 A valid greeting was received, with the given challenge (exactly as it
680 finished successfully.
685 has begun or restarted. If key exchange keeps failing, this message
686 will be repeated periodically.
688 .BI "USER " tokens\fR...
689 An administration client issued a notification using the
693 There are many possible warnings. They are categorized according to
696 Many of these warnings report system errors. These are reported as a
697 pair of tokens, described below as
703 is a string of the form
707 value of the error; the
709 is the `human-readable' form of the message, as reported by
712 These all indicate that the
714 server has become unable to continue. If enabled, the server will dump
715 core in its configuration directory.
717 .BI "ABORT repeated-select-errors"
718 The main event loop is repeatedly failing. If the server doesn't quit,
719 it will probably waste all available CPU doing nothing.
721 These indicate a problem with the administration socket interface.
723 .BI "ADMIN accept-error " ecode " " message
724 There was an error while attempting to accept a connection from a new
727 .BI "ADMIN client-write-error " ecode " " message
728 There was an error sending data to a client. The connection to the
729 client has been closed.
731 These indicate errors in challenges, either in the
733 command or in greeting packets.
735 .B "CHAL impossible-challenge"
736 The server hasn't issued any challenges yet. Quite how anyone else
737 thought he could make one up is hard to imagine.
739 .B "CHAL incorrect-tag"
740 Challenge received contained the wrong authentication data. It might be
741 very stale, or a forgery.
743 .B "CHAL invalid-challenge"
744 Challenge received was the wrong length. We might have changed MAC
745 algorithms since the challenge was issued, or it might just be rubbish.
747 .B "CHAL replay duplicated-sequence"
748 Challenge received was a definite replay of an old challenge. Someone's
751 .B "CHAL replay old-sequence"
752 Challenge received was old, but maybe not actually a replay. Try again.
753 .SS "KEYMGMT warnings"
754 These indicate a problem with the keyring files, or the keys stored in
757 .BI "KEYMGMT bad-private-key " message
758 The private key could not be read, or failed a consistency check. If
759 there was a problem with the file, usually there will have been
761 warnings before this.
763 .BI "KEYMGMT bad-public-keyring " message
764 The public keyring couldn't be read. Usually, there will have been
766 warnings before this.
768 .BI "KEYMGMT key-file-error " file ":" line " " message
769 Reports a specific error with the named keyring file. This probably
773 .BI "KEYMGMT public-key " tag " " tokens\fR...
774 These messages all indicate a problem with the public key named
777 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
778 The algorithms specified on the public key don't match the ones for our
779 private key. All the peers in a network have to use the same
782 .BI "KEYMGMT public-key " tag " bad " message
783 The public key couldn't be read, or is invalid.
785 .BI "KEYMGMT public-key " tag " bad-public-group-element"
786 The public key is invalid. This may indicate a malicious attempt to
787 introduce a bogus key.
789 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
790 The algorithms listed on the public key couldn't be understood. The
791 algorithm selection attributes are probably malformed and need fixing.
793 .BI "KEYMGMT public-key " tag " incorrect-group"
794 The public key doesn't use the same group as our private key. All the
795 peers in a network have to use the same group.
797 .BI "KEYMGMT public-key " tag " not-found"
798 The public key for peer
800 wasn't in the public keyring.
802 .BI "KEYMGMT public-key " tag " unknown-type"
803 The type of the public key isn't understood. Maybe you need to upgrade
806 (Even if you do, you'll have to regenerate your keys.)
808 These indicate problems during key-exchange. Many indicate either a bug
809 in the server (either yours or the remote one), or some kind of attack
810 in progress. All name a
812 as the second token: this is the peer the packet is apparently from,
813 though it may have been sent by an attacker instead.
815 In the descriptions below,
826 .BI "KX " peer " bad-expected-reply-log"
829 uses in its protocol contain a check value which proves that the
830 challenge is honest. This message indicates that the check value
831 supplied is wrong: someone is attempting to use bogus challenges to
834 server to leak private key information. No chance!
836 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
837 A symmetrically-encrypted portion of a key-exchange message failed to
840 .BI "KX " peer " invalid " msgtoken
841 A key-exchange message was malformed. This almost certainly indicates a
844 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
845 A message didn't contain the right magic data. This may be a replay of
846 some old exchange, or random packets being sent in an attempt to waste
849 .BI "KX " peer " public-key-expired"
850 The peer's public key has expired. It's maintainer should have given
851 you a replacement before now.
853 .BI "KX " peer " sending-cookie"
854 We've received too many bogus pre-challenge messages. Someone is trying
855 to flood us with key-exchange messages and make us waste CPU on doing
856 hard asymmetric crypto sums.
858 .BI "KX " peer " unexpected " msgtoken
859 The message received wasn't appropriate for this stage of the key
860 exchange process. This may mean that one of our previous packets got
863 it may simply mean that the peer has recently restarted.
865 .BI "KX " peer " unknown-challenge"
866 The peer is asking for an answer to a challenge which we don't know
867 about. This may mean that we've been inundated with challenges from
868 some malicious source
869 .I who can read our messages
870 and discarded the valid one.
872 .BI "KX " peer " unknown-message 0x" nn
873 An unknown key-exchange message arrived.
875 These are largely concerned with management of peers and the low-level
876 details of the network protocol. The second word is usually the name of
881 .BI "PEER " peer " bad-packet no-type"
882 An empty packet arrived. This is very strange.
884 .BI "PEER " peer " bad-packet unknown-category 0x" nn
887 (in hex) isn't understood. Probably a strange random packet from
888 somewhere; could be an unlikely bug.
890 .BI "PEER " peer " bad-packet unknown-type 0x" nn
893 (in hex) isn't understood. Probably a strange random packet from
894 somewhere; could be an unlikely bug.
896 .BI "PEER " peer " corrupt-encrypted-ping"
897 The peer sent a ping response which matches an outstanding ping, but its
898 payload is wrong. There's definitely a bug somewhere.
900 .BI "PEER " peer " corrupt-transport-ping"
901 The peer (apparently) sent a ping response which matches an outstanding
902 ping, but its payload is wrong. Either there's a bug, or the bad guys
903 are playing tricks on you.
905 .BI "PEER " peer " decrypt-failed"
906 An encrypted IP packet failed to decrypt. It may have been mangled in
907 transit, or may be a very old packet from an expired previous session
908 key. There is usually a considerable overlap in the validity periods of
909 successive session keys, so this shouldn't occur unless the key exchange
912 .BI "PEER " peer " malformed-encrypted-ping"
913 The peer sent a ping response which is hopelessly invalid. There's
914 definitely a bug somewhere.
916 .BI "PEER " peer " malformed-transport-ping"
917 The peer (apparently) sent a ping response which is hopelessly invalid.
918 Either there's a bug, or the bad guys are playing tricks on you.
920 .BI "PEER " peer " packet-build-failed"
921 There wasn't enough space in our buffer to put the packet we wanted to
922 send. Shouldn't happen.
924 .BI "PEER \- socket-read-error " ecode " " message
925 An error occurred trying to read an incoming packet.
927 .BI "PEER " peer " socket-write-error " ecode " " message
928 An error occurred attempting to send a network packet. We lost that
931 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
932 The peer sent an encrypted ping response whose id doesn't match any
933 outstanding ping. Maybe it was delayed for longer than the server was
934 willing to wait, or maybe the peer has gone mad.
936 .BI "PEER \- unexpected-source " address\fR...
937 A packet arrived from
939 (a network address \(en see above), but no peer is known at that
940 address. This may indicate a misconfiguration, or simply be a result of
941 one end of a connection being set up before the other.
943 .BI "PEER " peer " unexpected-transport-ping 0x" id
944 The peer (apparently) sent a transport ping response whose id doesn't
945 match any outstanding ping. Maybe it was delayed for longer than the
946 server was willing to wait, or maybe the peer has gone mad; or maybe
947 there are bad people trying to confuse you.
948 .SS "SERVER warnings"
949 These indicate problems concerning the server process as a whole.
951 .BI "SERVER ignore signal " name
952 A signal arrived, but the server ignored it. Currently this happens for
954 because that's a popular way of telling daemons to re-read their
955 configuration files. Since
957 re-reads its keyrings automatically and has no other configuration
958 files, it's not relevant, but it seemed better to ignore the signal than
961 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
966 .BI "SERVER quit admin-request"
967 A client of the administration interface issued a
971 .BI "SERVER select-error " ecode " " message
972 An error occurred in the server's main event loop. This is bad: if it
973 happens too many times, the server will abort.
975 These are concerned with the symmetric encryption and decryption
978 .BI "SYMM replay old-sequence"
979 A packet was received with an old sequence number. It may just have
980 been delayed or duplicated, or it may have been an attempt at a replay
983 .BI "SYMM replay duplicated-sequence"
984 A packet was received with a sequence number we've definitely seen
985 before. It may be an accidental duplication because the 'net is like
986 that, or a deliberate attempt at a replay.
988 These concern the workings of the system-specific tunnel driver. The
989 second word is the name of the tunnel interface in question, or
993 .BI "TUN \- bsd no-tunnel-devices"
994 The driver couldn't find an available tunnel device. Maybe if you
999 .BI "TUN - " tun-name " open-error " device " " ecode " " message
1000 An attempt to open the tunnel device file
1004 .BI "TUN \- linux config-error " ecode " " message
1005 Configuring the Linux TUN/TAP interface failed.
1007 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1008 Reading from the tunnel device failed.
1010 .BI "TUN " ifname " slip bad-escape"
1011 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1012 The erroneous packet will be ignored.
1014 .BI "TUN " ifname " slip eof"
1015 The SLIP driver encountered end-of-file on its input descriptor.
1016 Pending data is discarded, and no attempt is made to read any more data
1017 from that interface ever.
1019 .BI "TUN " ifname " slip escape-end"
1020 The SLIP driver encountered an escaped `end' marker. This probably
1021 means that someone's been sending it junk. The erroneous packet is
1022 discarded, and we hope that we've rediscovered synchronization.
1024 .BI "TUN \- slip fork-error " ecode " " message
1025 The SLIP driver encountered an error forking a child process while
1026 allocating a new dynamic interface.
1028 .BI "TUN \- slip no-slip-interfaces"
1029 The driver ran out of static SLIP interfaces. Either preallocate more,
1030 or use dynamic SLIP interface allocation.
1032 .BI "TUN " ifname " slip overflow"
1033 The SLIP driver gave up reading a packet because it got too large.
1035 .BI "TUN \- slip pipe-error " ecode " " message
1036 The SLIP driver encountered an error creating pipes while allocating a
1037 new dynamic interface.
1039 .BI "TUN \- slip read-ifname-failed " ecode " " message
1040 The SLIP driver encountered an error reading the name of a dynamically
1041 allocated interface. Maybe the allocation script is broken.
1043 .BI "TUN \- unet config-error " ecode " " message
1044 Configuring the Linux Unet interface failed. Unet is obsolete and
1045 shouldn't be used any more.
1047 .BI "TUN \- unet getinfo-error " ecode " " message
1048 Reading information about the Unet interface failed. Unet is obsolete
1049 and shouldn't be used any more.
1051 .BI "TUN \- unet ifname-too-long"
1052 The Unet interface's name overflowed, so we couldn't read it properly.
1053 Unet is obsolete and shouldn't be used any more.
1055 These are issued by administration clients using the
1059 .BI "USER " tokens\fR...
1060 An administration client issued a warning.
1065 .IR "The Trivial IP Encryption Protocol" .
1067 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob