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 \-\- " 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 \-\- " 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 These all indicate that the
698 server has become unable to continue. If enabled, the server will dump
699 core in its configuration directory.
701 .BI "ABORT repeated-select-errors"
702 The main event loop is repeatedly failing. If the server doesn't quit,
703 it will probably waste all available CPU doing nothing.
705 These indicate a problem with the administration socket interface.
707 .BI "ADMIN accept-error \-\- " message
708 There was an error while attempting to accept a connection from a new
711 .BI "ADMIN client-read-error \-\- " message
712 There was an error sending data to a client. The connection to the
713 client has been closed.
715 These indicate errors in challenges, either in the
717 command or in greeting packets.
719 .B "CHAL impossible-challenge"
720 The server hasn't issued any challenges yet. Quite how anyone else
721 thought he could make one up is hard to imagine.
723 .B "CHAL incorrect-tag"
724 Challenge received contained the wrong authentication data. It might be
725 very stale, or a forgery.
727 .B "CHAL invalid-challenge"
728 Challenge received was the wrong length. We might have changed MAC
729 algorithms since the challenge was issued, or it might just be rubbish.
731 .B "CHAL replay duplicated-sequence"
732 Challenge received was a definite replay of an old challenge. Someone's
735 .B "CHAL replay old-sequence"
736 Challenge received was old, but maybe not actually a replay. Try again.
737 .SS "KEYMGMT warnings"
738 These indicate a problem with the keyring files, or the keys stored in
741 .BI "KEYMGMT bad-private-key \-\- " message
742 The private key could not be read, or failed a consistency check. If
743 there was a problem with the file, usually there will have been
745 warnings before this.
747 .BI "KEYMGMT bad-public-keyring \-\- " message
748 The public keyring couldn't be read. Usually, there will have been
750 warnings before this.
752 .BI "KEYMGMT key-file-error " file ":" line " \-\- " message
753 Reports a specific error with the named keyring file. This probably
757 .BI "KEYMGMT public-key " tag " " tokens\fR...
758 These messages all indicate a problem with the public key named
761 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
762 The algorithms specified on the public key don't match the ones for our
763 private key. All the peers in a network have to use the same
766 .BI "KEYMGMT public-key " tag " bad \-\- " message
767 The public key couldn't be read, or is invalid.
769 .BI "KEYMGMT public-key " tag " bad-public-group-element"
770 The public key is invalid. This may indicate a malicious attempt to
771 introduce a bogus key.
773 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
774 The algorithms listed on the public key couldn't be understood. The
775 algorithm selection attributes are probably malformed and need fixing.
777 .BI "KEYMGMT public-key " tag " incorrect-group"
778 The public key doesn't use the same group as our private key. All the
779 peers in a network have to use the same group.
781 .BI "KEYMGMT public-key " tag " not-found"
782 The public key for peer
784 wasn't in the public keyring.
786 .BI "KEYMGMT public-key " tag " unknown-type"
787 The type of the public key isn't understood. Maybe you need to upgrade
790 (Even if you do, you'll have to regenerate your keys.)
792 These indicate problems during key-exchange. Many indicate either a bug
793 in the server (either yours or the remote one), or some kind of attack
794 in progress. All name a
796 as the second token: this is the peer the packet is apparently from,
797 though it may have been sent by an attacker instead.
799 In the descriptions below,
810 .BI "KX " peer " bad-expected-reply-log"
813 uses in its protocol contain a check value which proves that the
814 challenge is honest. This message indicates that the check value
815 supplied is wrong: someone is attempting to use bogus challenges to
818 server to leak private key information. No chance!
820 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
821 A symmetrically-encrypted portion of a key-exchange message failed to
824 .BI "KX " peer " invalid " msgtoken
825 A key-exchange message was malformed. This almost certainly indicates a
828 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
829 A message didn't contain the right magic data. This may be a replay of
830 some old exchange, or random packets being sent in an attempt to waste
833 .BI "KX " peer " public-key-expired"
834 The peer's public key has expired. It's maintainer should have given
835 you a replacement before now.
837 .BI "KX " peer " sending-cookie"
838 We've received too many bogus pre-challenge messages. Someone is trying
839 to flood us with key-exchange messages and make us waste CPU on doing
840 hard asymmetric crypto sums.
842 .BI "KX " peer " unexpected " msgtoken
843 The message received wasn't appropriate for this stage of the key
844 exchange process. This may mean that one of our previous packets got
847 it may simply mean that the peer has recently restarted.
849 .BI "KX " peer " unknown-challenge"
850 The peer is asking for an answer to a challenge which we don't know
851 about. This may mean that we've been inundated with challenges from
852 some malicious source
853 .I who can read our messages
854 and discarded the valid one.
856 .BI "KX " peer " unknown-message 0x" nn
857 An unknown key-exchange message arrived.
859 These are largely concerned with management of peers and the low-level
860 details of the network protocol. The second word is usually the name of
865 .BI "PEER " peer " bad-packet no-type"
866 An empty packet arrived. This is very strange.
868 .BI "PEER " peer " bad-packet unknown-category 0x" nn
871 (in hex) isn't understood. Probably a strange random packet from
872 somewhere; could be an unlikely bug.
874 .BI "PEER " peer " bad-packet unknown-type 0x" nn
877 (in hex) isn't understood. Probably a strange random packet from
878 somewhere; could be an unlikely bug.
880 .BI "PEER " peer " corrupt-encrypted-ping"
881 The peer sent a ping response which matches an outstanding ping, but its
882 payload is wrong. There's definitely a bug somewhere.
884 .BI "PEER " peer " corrupt-transport-ping"
885 The peer (apparently) sent a ping response which matches an outstanding
886 ping, but its payload is wrong. Either there's a bug, or the bad guys
887 are playing tricks on you.
889 .BI "PEER " peer " decrypt-failed"
890 An encrypted IP packet failed to decrypt. It may have been mangled in
891 transit, or may be a very old packet from an expired previous session
892 key. There is usually a considerable overlap in the validity periods of
893 successive session keys, so this shouldn't occur unless the key exchange
896 .BI "PEER " peer " malformed-encrypted-ping"
897 The peer sent a ping response which is hopelessly invalid. There's
898 definitely a bug somewhere.
900 .BI "PEER " peer " malformed-transport-ping"
901 The peer (apparently) sent a ping response which is hopelessly invalid.
902 Either there's a bug, or the bad guys are playing tricks on you.
904 .BI "PEER " peer " packet-build-failed"
905 There wasn't enough space in our buffer to put the packet we wanted to
906 send. Shouldn't happen.
908 .BI "PEER \- socket-read-error \-\- " message
909 An error occurred trying to read an incoming packet.
911 .BI "PEER " peer " socket-write-error \-\- " message
912 An error occurred attempting to send a network packet. We lost that
915 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
916 The peer sent an encrypted ping response whose id doesn't match any
917 outstanding ping. Maybe it was delayed for longer than the server was
918 willing to wait, or maybe the peer has gone mad.
920 .BI "PEER \- unexpected-source " address\fR...
921 A packet arrived from
923 (a network address \(en see above), but no peer is known at that
924 address. This may indicate a misconfiguration, or simply be a result of
925 one end of a connection being set up before the other.
927 .BI "PEER " peer " unexpected-transport-ping 0x" id
928 The peer (apparently) sent a transport ping response whose id doesn't
929 match any outstanding ping. Maybe it was delayed for longer than the
930 server was willing to wait, or maybe the peer has gone mad; or maybe
931 there are bad people trying to confuse you.
932 .SS "SERVER warnings"
933 These indicate problems concerning the server process as a whole.
935 .BI "SERVER ignore signal " name
936 A signal arrived, but the server ignored it. Currently this happens for
938 because that's a popular way of telling daemons to re-read their
939 configuration files. Since
941 re-reads its keyrings automatically and has no other configuration
942 files, it's not relevant, but it seemed better to ignore the signal than
945 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
950 .BI "SERVER quit admin-request"
951 A client of the administration interface issued a
955 .BI "SERVER select-error \-\- " message
956 An error occurred in the server's main event loop. This is bad: if it
957 happens too many times, the server will abort.
959 These are concerned with the symmetric encryption and decryption
962 .BI "SYMM replay old-sequence"
963 A packet was received with an old sequence number. It may just have
964 been delayed or duplicated, or it may have been an attempt at a replay
967 .BI "SYMM replay duplicated-sequence"
968 A packet was received with a sequence number we've definitely seen
969 before. It may be an accidental duplication because the 'net is like
970 that, or a deliberate attempt at a replay.
972 These concern the workings of the system-specific tunnel driver. The
973 second word is the name of the tunnel interface in question, or
977 .BI "TUN \- bsd no-tunnel-devices"
978 The driver couldn't find an available tunnel device. Maybe if you
983 .BI "TUN - open-error " device " \-\- " message
984 An attempt to open the tunnel device file
988 .BI "TUN \- linux config-error \-\- " message
989 Configuring the Linux TUN/TAP interface failed.
991 .BI "TUN " ifname " read-error \-\- " message
992 Reading from the tunnel device failed.
994 .BI "TUN " ifname " slip bad-escape"
995 The SLIP driver encountered a escaped byte it wasn't expecting to see.
996 The erroneous packet will be ignored.
998 .BI "TUN " ifname " slip eof"
999 The SLIP driver encountered end-of-file on its input descriptor.
1000 Pending data is discarded, and no attempt is made to read any more data
1001 from that interface ever.
1003 .BI "TUN " ifname " slip escape-end"
1004 The SLIP driver encountered an escaped `end' marker. This probably
1005 means that someone's been sending it junk. The erroneous packet is
1006 discarded, and we hope that we've rediscovered synchronization.
1008 .BI "TUN \- slip fork-error \-\- " message
1009 The SLIP driver encountered an error forking a child process while
1010 allocating a new dynamic interface.
1012 .BI "TUN \- slip no-slip-interfaces"
1013 The driver ran out of static SLIP interfaces. Either preallocate more,
1014 or use dynamic SLIP interface allocation.
1016 .BI "TUN " ifname " slip overflow"
1017 The SLIP driver gave up reading a packet because it got too large.
1019 .BI "TUN \- slip pipe-error \-\- " message
1020 The SLIP driver encountered an error creating pipes while allocating a
1021 new dynamic interface.
1023 .BI "TUN \- slip read-ifname-failed \-\- " message
1024 The SLIP driver encountered an error reading the name of a dynamically
1025 allocated interface. Maybe the allocation script is broken.
1027 .BI "TUN \- unet config-error \-\- " message
1028 Configuring the Linux Unet interface failed. Unet is obsolete and
1029 shouldn't be used any more.
1031 .BI "TUN \- unet getinfo-error \-\- " message
1032 Reading information about the Unet interface failed. Unet is obsolete
1033 and shouldn't be used any more.
1035 .BI "TUN \- unet ifname-too-long \-\- " message
1036 The Unet interface's name overflowed, so we couldn't read it properly.
1037 Unet is obsolete and shouldn't be used any more.
1039 These are issued by administration clients using the
1043 .BI "USER " tokens\fR...
1044 An administration client issued a warning.
1049 .IR "The Trivial IP Encryption Protocol" .
1051 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob