12 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
14 tripe-admin \- administrator commands for TrIPE
16 This manual page describes the administration interface provided by the
22 program can be used either interactively or in scripts to communicate
23 with the server using this interface. Alternatively, simple custom
24 clients can be written in scripting languages such as Perl, Python or
25 Tcl, or more advanced clients such as GUI monitors can be written in C
26 with little difficulty.
28 By default, the server listens for admin connections on the Unix-domain
30 .BR /var/lib/tripe/tripesock .
31 Administration commands use a textual protocol. Each client command or
32 server response consists of a line of ASCII text terminated by a single
33 linefeed character. No command may be longer than 255 characters.
34 .SS "General structure"
35 Each command or response line consists of a sequence of
36 whitespace-separated words. The number and nature of whitespace
37 characters separating two words in a client command is not significant;
38 the server always uses a single space character. The first word in a
41 identifying the type of command or response contained. Keywords in
42 client commands are not case-sensitive; the server always uses uppercase
45 For simple client command, the server responds with zero or more
47 lines, followed by either an
53 provides information requested in the command. An
55 response contains no further data. A
57 code is followed by a machine-readable explanation of why the command
60 Simple command processing is strictly synchronous: the server reads a
61 command, processes it, and responds, before reading the next command.
62 All commands can be run as simple commands. Long-running commands
67 block the client until they finish, but the rest of the server continues
69 .SS "Asynchronous messages"
70 There are three types of asynchronous messages which
71 aren't associated with any particular command.
75 message contains a machine-readable message warning of an error
76 encountered while processing a command, unexpected or unusual behaviour
77 by a peer, or a possible attack by an adversary. Under normal
78 conditions, the server shouldn't emit any warnings.
82 message contains a human-readable tracing message containing diagnostic
83 information. Trace messages are controlled using the
85 command-line option to the server, or the
87 administration command (see below). Support for tracing can be disabled
88 when the package is being configured, and may not be available in your
93 message is a machine-readable notification about some routine but
94 interesting event such as creation or destruction of peers.
96 The presence of asynchronous messages can be controlled using the
99 .SS "Background commands"
104 take a long time to complete. To prevent these long-running commands
105 from tying up a server connection, they can be run in the background.
106 Not all commands can be run like this: the ones that can provide a
108 option, which must be supplied with a
111 A command may fail before it starts running in the background. In this
112 case, the server emits a
114 response, as usual. To indicate that a command has started running in
115 the background, the server emits a response of the form
116 .BI "BGDETACH " tag \fR,
119 is the value passed to the
121 option. From this point on, the server is ready to process more
122 commands and reply to them.
124 Responses to background commands are indicated by a line beginning with
130 followed by the command tag. These correspond to the
135 responses for simple commands:
137 indicates information from a background command which has not completed
142 indicates that a background command succeeded or failed, respectively.
144 A background command will never issue an
148 response: it will always detach and then issue any
153 .SS "Network addresses"
154 A network address is a sequence of words. The first is a token
155 identifying the network address family. The length of an address and
156 the meanings of the subsequent words depend on the address family.
157 Address family tokens are not case-sensitive on input; on output, they
158 are always in upper-case.
160 At present, only one address family is understood.
162 .BI "INET " address " " port
163 An Internet socket, naming an IPv4 address and UDP port. On output, the
164 address is always in numeric dotted-quad form, and the port is given as
165 a plain number. On input, DNS hostnames and symbolic port names are
166 permitted. Name resolution does not block the main server, but will
167 block the requesting client. This hopefully makes life simpler for
168 stupid clients. Complex clients which don't wish to be held up can open
169 extra connections or do the resolution themselves.)
171 If, on input, no recognised address family token is found, the following
172 words are assumed to represent an
175 .SS "Key-value output"
180 produce output in the form of
182 pairs, one per word. Neither the
188 Commands which enable or disable kinds of output (e.g.,
192 work in similar ways. They take a single optional argument, which
193 consists of a string of letters selecting message types, optionally
198 to disable, the subsequently listed types.
200 If the argument is omitted, the available message types are displayed,
203 line, in a fixed-column format. Column zero contains the key letter for
204 selecting that message type; column one contains either a space or a
206 sign, if the message type is disabled or enabled respectively; and a
207 textual description of the message type begins at column 3 and continues
208 to the end of the line.
210 Lowercase key letters control individual message types. Uppercase key
211 letters control collections of message types.
212 .SH "COMMAND REFERENCE"
214 The commands provided are:
216 .BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
217 Adds a new peer. The peer is given the name
219 the peer's public key is assumed to be in the file
221 (or whatever alternative file was specified in the
223 option on the command line). The
225 is the network address (see above for the format) at which the peer can
226 be contacted. The following options are recognised.
230 .BI "\-background " tag
231 Run the command in the background, using the given
234 .BI "\-keepalive " time
235 Send a no-op packet if we've not sent a packet to the peer in the last
237 interval. This is useful for persuading port-translating firewalls to
238 believe that the `connection' is still active. The
240 is expressed as a nonnegative integer followed optionally by
246 for days, hours, minutes, or seconds respectively; if no suffix is
247 given, seconds are assumed.
249 .BI "\-tunnel " tunnel
250 Use the named tunnel driver, rather than the default.
257 line reporting the IP address and port number stored for
261 Cancels the background job with the named
264 .BI "CHECKCHAL " challenge
265 Verifies a challenge as being one earlier issued by
267 and not previously either passed to
269 or in a greeting message.
272 Causes the server to disassociate itself from its terminal and become a
273 background task. This only works once. A warning is issued.
275 .BI "EPING \fR[" options "\fR] " peer
276 Sends an encrypted ping to the peer, and expects an encrypted response.
277 This checks that the peer is running (and not being impersonated), and
278 that it can encrypt and decrypt packets correctly. Options and
279 responses are the same as for the
284 Requests the server to begin a new key exchange with
289 Requests a challenge. The challenge is returned in an
291 line, as a base64-encoded string. See
294 .BI "GREET " peer " " challenge
295 Sends a greeting packet containing the
297 (base-64 encoded) to the named
299 The expectation is that this will cause the peer to recognize us and
300 begin a key-exchange.
303 Causes the server to emit an
305 line for each command it supports. Each line lists the command name,
306 followed by the names of the arguments. This may be helpful as a memory
307 aid for interactive use, or for program clients probing for features.
312 line containing the name of the network interface used to collect IP
313 packets which are to be encrypted and sent to
315 Used by configuration scripts so that they can set up routing tables
316 appropriately after adding new peers.
321 line giving the tag for each outstanding background job.
324 Causes the server to forget all about
326 All keys are destroyed, and no more packets are sent. No notification
327 is sent to the peer: if it's important that the peer be notified, you
328 must think of a way to do that yourself.
331 For each currently-known peer, an
333 line is written containing the peer's name, as given to
336 .BI "NOTIFY " tokens\fR...
339 notification to all interested administration clients.
342 Returns information about a peer, in key-value form. The following keys
347 The tunnel driver used for this peer.
350 The keepalive interval, in seconds, or zero if no keepalives are to be
354 .BI "PING \fR[" options "\fR] " peer
355 Send a transport-level ping to the peer. The ping and its response are
356 not encrypted or authenticated. This command, possibly in conjunction
357 with tracing, is useful for ensuring that UDP packets are actually
358 flowing in both directions. See also the
364 line is printed describing the outcome:
367 .BI "ping-ok " millis
368 A response was received
370 after the ping was sent.
373 No response was received within the time allowed.
376 The peer was killed (probably by another admin connection) before a
377 response was received.
380 Options recognized for this command are:
384 .BI "\-background " tag
385 Run the command in the background, using the given
388 .BI "\-timeout " time
391 seconds before giving up on a response. The default is 5 seconds. (The
392 time format is the same as for the
401 line containing just the number of the UDP port used by the
403 server. If you've allowed your server to allocate a port dynamically,
404 this is how to find out which one it chose.
407 Instructs the server to recheck its keyring files. The server checks
408 these periodically anyway but it may be necessary to force a recheck,
409 for example after adding a new peer key.
412 Instructs the server to exit immediately. A warning is sent.
415 Returns information about the server, in the form of key-value pairs.
416 The following keys are used.
420 A keyword naming the implementation of the
422 server. The current implementation is called
426 The server's version number, as reported by
434 if the server has or hasn't (respectively) become a daemon.
437 .BI "SETIFNAME " peer " " new-name
438 Informs the server that the
440 tunnel-interface name has been changed to
442 This is useful if firewalling decisions are made based on interface
443 names: a setup script for a particular peer can change the name, and
444 then update the server's records so that they're accurate.
449 lines, each containing one or more statistics in the form
450 .IB name = value \fR.
451 The statistics-gathering is experimental and subject to change.
453 .BR "TRACE " [\fIoptions\fP]
454 Selects trace outputs: see
456 above. Message types provided are:
459 Currently, the following tracing options are supported:
462 Tunnel events: reception of packets to be encrypted, and injection of
463 successfully-decrypted packets.
466 Peer management events: creation and destruction of peer attachments,
467 and arrival of messages.
470 Administration interface: acceptance of new connections, and handling of
471 the backgroud name-resolution required by the
476 Handling of symmetric keysets: creation and expiry of keysets, and
477 encryption and decryption of messages.
480 Key exchange: reception, parsing and emission of key exchange messages.
483 Key management: loading keys and checking for file modifications.
486 Display information about challenge issuing and verification.
489 Display contents of packets sent and received by the tunnel and/or peer
493 Display inputs, outputs and intermediate results of cryptographic
494 operations. This includes plaintext and key material. Use with
506 outputs provide extra detail for other outputs. Specifying
512 isn't useful; neither is specifying
523 For each available tunnel driver, an
525 line is printed giving its name.
528 Causes the server to emit an
530 line stating its software version, as two words: the server name, and
531 its version string. The server name
533 is reserved to the Straylight/Edgeware implementation.
535 .BR "WATCH " [\fIoptions\fP]
536 Enables or disables asynchronous messages
537 .IR "for the current connection only" .
540 above. The default watch state for the connection the server opens
541 automatically on stdin/stdout is to show warnings and trace messages;
542 other connections show no asynchronous messages. (This is done in order
543 to guarantee that a program reading the server's stdout does not miss
547 Message types provided are:
565 .BI "WARN " tokens\fR...
568 warning to all interested administration clients.
570 .\"* 20 Error messages (FAIL codes)
575 messages are sent to clients as a result of errors during command
583 server is already running as a daemon.
585 .BI "bad-addr-syntax " message
586 (For commands accepting socket addresses.) The address couldn't be
589 .BI "bad-syntax " cmd " " message
590 (For any command.) The command couldn't be understood: e.g., the number
591 of arguments was wrong.
593 .BI "bad-time-spec " word
596 is not a valid time interval specification. Acceptable time
597 specifications are nonnegative integers followed optionally by
603 for days, hours, minutes, or seconds, respectively.
605 .BI "bad-trace-option " char
608 An unknown trace option was requested.
610 .BI "bad-watch-option " char
613 An unknown watch option was requested.
615 .BI "daemon-error " ecode " " message
618 An error occurred during the attempt to become a daemon, as reported by
621 .BI "invalid-port " number
624 The given port number is out of range.
626 .BI "peer-create-fail " peer
631 failed for some reason. A warning should have been emitted explaining
634 .BI "peer-exists " peer
637 There is already a peer named
640 .B "ping-send-failed"
641 The attempt to send a ping packet failed, probably due to lack of
644 .BI "resolve-error " hostname
649 could not be resolved.
651 .BI "resolver-timeout " hostname
656 took too long to resolve.
658 .BI "tag-exists " tag
659 (For long-running commands.) The named
661 is already the tag of an outstanding job.
663 .BI "unknown-command " token
668 .BI "unknown-peer " name
676 There is no peer called
679 .BI "unknown-port " port
687 .BI "unknown-tag " tag
692 is not the tag for any outstanding background job. It may have just
695 .\"* 30 Notification broadcasts (NOTE codes)
696 The following notifications are sent to clients who request them.
698 .BI "ADD " peer " " ifname " " address \fR...
699 A new peer has been added. The peer's name is
701 its tunnel is network interface
703 and its network address is
707 The server has forked off into the sunset and become a daemon.
709 .BI "GREET " challenge " " address \fR...
710 A valid greeting was received, with the given challenge (exactly as it
723 finished successfully.
728 has begun or restarted. If key exchange keeps failing, this message
729 will be repeated periodically.
731 .BI "NEWIFNAME " peer " " old-name " " new-name
734 tunnel interface name has been changed from
742 .BI "USER " tokens\fR...
743 An administration client issued a notification using the
747 .\"* 40 Warning broadcasts (WARN codes)
749 There are many possible warnings. They are categorized according to
752 Many of these warnings report system errors. These are reported as a
753 pair of tokens, described below as
759 is a string of the form
763 value of the error; the
765 is the `human-readable' form of the message, as reported by
768 These all indicate that the
770 server has become unable to continue. If enabled, the server will dump
771 core in its configuration directory.
773 .BI "ABORT repeated-select-errors"
774 The main event loop is repeatedly failing. If the server doesn't quit,
775 it will probably waste all available CPU doing nothing.
777 These indicate a problem with the administration socket interface.
779 .BI "ADMIN accept-error " ecode " " message
780 There was an error while attempting to accept a connection from a new
783 .BI "ADMIN client-write-error " ecode " " message
784 There was an error sending data to a client. The connection to the
785 client has been closed.
787 These indicate errors in challenges, either in the
789 command or in greeting packets.
791 .B "CHAL impossible-challenge"
792 The server hasn't issued any challenges yet. Quite how anyone else
793 thought he could make one up is hard to imagine.
795 .B "CHAL incorrect-tag"
796 Challenge received contained the wrong authentication data. It might be
797 very stale, or a forgery.
799 .B "CHAL invalid-challenge"
800 Challenge received was the wrong length. We might have changed MAC
801 algorithms since the challenge was issued, or it might just be rubbish.
803 .B "CHAL replay duplicated-sequence"
804 Challenge received was a definite replay of an old challenge. Someone's
807 .B "CHAL replay old-sequence"
808 Challenge received was old, but maybe not actually a replay. Try again.
809 .SS "KEYMGMT warnings"
810 These indicate a problem with the keyring files, or the keys stored in
813 .BI "KEYMGMT bad-private-key " message
814 The private key could not be read, or failed a consistency check. If
815 there was a problem with the file, usually there will have been
817 warnings before this.
819 .BI "KEYMGMT bad-public-keyring " message
820 The public keyring couldn't be read. Usually, there will have been
822 warnings before this.
824 .BI "KEYMGMT key-file-error " file ":" line " " message
825 Reports a specific error with the named keyring file. This probably
829 .BI "KEYMGMT public-key " tag " " tokens\fR...
830 These messages all indicate a problem with the public key named
833 .BI "KEYMGMT public-key " tag " algorithm-mismatch"
834 The algorithms specified on the public key don't match the ones for our
835 private key. All the peers in a network have to use the same
838 .BI "KEYMGMT public-key " tag " bad " message
839 The public key couldn't be read, or is invalid.
841 .BI "KEYMGMT public-key " tag " bad-public-group-element"
842 The public key is invalid. This may indicate a malicious attempt to
843 introduce a bogus key.
845 .BI "KEYMGMT public-key " tag " bad-algorithm-selection"
846 The algorithms listed on the public key couldn't be understood. The
847 algorithm selection attributes are probably malformed and need fixing.
849 .BI "KEYMGMT public-key " tag " incorrect-group"
850 The public key doesn't use the same group as our private key. All the
851 peers in a network have to use the same group.
853 .BI "KEYMGMT public-key " tag " not-found"
854 The public key for peer
856 wasn't in the public keyring.
858 .BI "KEYMGMT public-key " tag " unknown-type"
859 The type of the public key isn't understood. Maybe you need to upgrade
862 (Even if you do, you'll have to regenerate your keys.)
864 These indicate problems during key-exchange. Many indicate either a bug
865 in the server (either yours or the remote one), or some kind of attack
866 in progress. All name a
868 as the second token: this is the peer the packet is apparently from,
869 though it may have been sent by an attacker instead.
871 In the descriptions below,
882 .BI "KX " peer " bad-expected-reply-log"
885 uses in its protocol contain a check value which proves that the
886 challenge is honest. This message indicates that the check value
887 supplied is wrong: someone is attempting to use bogus challenges to
890 server to leak private key information. No chance!
892 .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
893 A symmetrically-encrypted portion of a key-exchange message failed to
896 .BI "KX " peer " invalid " msgtoken
897 A key-exchange message was malformed. This almost certainly indicates a
900 .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
901 A message didn't contain the right magic data. This may be a replay of
902 some old exchange, or random packets being sent in an attempt to waste
905 .BI "KX " peer " public-key-expired"
906 The peer's public key has expired. It's maintainer should have given
907 you a replacement before now.
909 .BI "KX " peer " sending-cookie"
910 We've received too many bogus pre-challenge messages. Someone is trying
911 to flood us with key-exchange messages and make us waste CPU on doing
912 hard asymmetric crypto sums.
914 .BI "KX " peer " unexpected " msgtoken
915 The message received wasn't appropriate for this stage of the key
916 exchange process. This may mean that one of our previous packets got
919 it may simply mean that the peer has recently restarted.
921 .BI "KX " peer " unknown-challenge"
922 The peer is asking for an answer to a challenge which we don't know
923 about. This may mean that we've been inundated with challenges from
924 some malicious source
925 .I who can read our messages
926 and discarded the valid one.
928 .BI "KX " peer " unknown-message 0x" nn
929 An unknown key-exchange message arrived.
931 These are largely concerned with management of peers and the low-level
932 details of the network protocol. The second word is usually the name of
937 .BI "PEER " peer " bad-packet no-type"
938 An empty packet arrived. This is very strange.
940 .BI "PEER " peer " bad-packet unknown-category 0x" nn
943 (in hex) isn't understood. Probably a strange random packet from
944 somewhere; could be an unlikely bug.
946 .BI "PEER " peer " bad-packet unknown-type 0x" nn
949 (in hex) isn't understood. Probably a strange random packet from
950 somewhere; could be an unlikely bug.
952 .BI "PEER " peer " corrupt-encrypted-ping"
953 The peer sent a ping response which matches an outstanding ping, but its
954 payload is wrong. There's definitely a bug somewhere.
956 .BI "PEER " peer " corrupt-transport-ping"
957 The peer (apparently) sent a ping response which matches an outstanding
958 ping, but its payload is wrong. Either there's a bug, or the bad guys
959 are playing tricks on you.
961 .BI "PEER " peer " decrypt-failed"
962 An encrypted IP packet failed to decrypt. It may have been mangled in
963 transit, or may be a very old packet from an expired previous session
964 key. There is usually a considerable overlap in the validity periods of
965 successive session keys, so this shouldn't occur unless the key exchange
968 .BI "PEER " peer " malformed-encrypted-ping"
969 The peer sent a ping response which is hopelessly invalid. There's
970 definitely a bug somewhere.
972 .BI "PEER " peer " malformed-transport-ping"
973 The peer (apparently) sent a ping response which is hopelessly invalid.
974 Either there's a bug, or the bad guys are playing tricks on you.
976 .BI "PEER " peer " packet-build-failed"
977 There wasn't enough space in our buffer to put the packet we wanted to
978 send. Shouldn't happen.
980 .BI "PEER \- socket-read-error " ecode " " message
981 An error occurred trying to read an incoming packet.
983 .BI "PEER " peer " socket-write-error " ecode " " message
984 An error occurred attempting to send a network packet. We lost that
987 .BI "PEER " peer " unexpected-encrypted-ping 0x" id
988 The peer sent an encrypted ping response whose id doesn't match any
989 outstanding ping. Maybe it was delayed for longer than the server was
990 willing to wait, or maybe the peer has gone mad.
992 .BI "PEER \- unexpected-source " address\fR...
993 A packet arrived from
995 (a network address \(en see above), but no peer is known at that
996 address. This may indicate a misconfiguration, or simply be a result of
997 one end of a connection being set up before the other.
999 .BI "PEER " peer " unexpected-transport-ping 0x" id
1000 The peer (apparently) sent a transport ping response whose id doesn't
1001 match any outstanding ping. Maybe it was delayed for longer than the
1002 server was willing to wait, or maybe the peer has gone mad; or maybe
1003 there are bad people trying to confuse you.
1004 .SS "SERVER warnings"
1005 These indicate problems concerning the server process as a whole.
1007 .BI "SERVER ignore signal " name
1008 A signal arrived, but the server ignored it. Currently this happens for
1010 because that's a popular way of telling daemons to re-read their
1011 configuration files. Since
1013 re-reads its keyrings automatically and has no other configuration
1014 files, it's not relevant, but it seemed better to ignore the signal than
1017 .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
1018 A signal arrived and
1022 .BI "SERVER quit admin-request"
1023 A client of the administration interface issued a
1027 .BI "SERVER select-error " ecode " " message
1028 An error occurred in the server's main event loop. This is bad: if it
1029 happens too many times, the server will abort.
1031 These are concerned with the symmetric encryption and decryption
1034 .BI "SYMM replay old-sequence"
1035 A packet was received with an old sequence number. It may just have
1036 been delayed or duplicated, or it may have been an attempt at a replay
1039 .BI "SYMM replay duplicated-sequence"
1040 A packet was received with a sequence number we've definitely seen
1041 before. It may be an accidental duplication because the 'net is like
1042 that, or a deliberate attempt at a replay.
1044 These concern the workings of the system-specific tunnel driver. The
1045 second word is the name of the tunnel interface in question, or
1049 .BI "TUN \- bsd no-tunnel-devices"
1050 The driver couldn't find an available tunnel device. Maybe if you
1053 files, it will work.
1055 .BI "TUN - " tun-name " open-error " device " " ecode " " message
1056 An attempt to open the tunnel device file
1060 .BI "TUN \- linux config-error " ecode " " message
1061 Configuring the Linux TUN/TAP interface failed.
1063 .BI "TUN " ifname " " tun-name " read-error " ecode " " message
1064 Reading from the tunnel device failed.
1066 .BI "TUN " ifname " slip bad-escape"
1067 The SLIP driver encountered a escaped byte it wasn't expecting to see.
1068 The erroneous packet will be ignored.
1070 .BI "TUN " ifname " slip eof"
1071 The SLIP driver encountered end-of-file on its input descriptor.
1072 Pending data is discarded, and no attempt is made to read any more data
1073 from that interface ever.
1075 .BI "TUN " ifname " slip escape-end"
1076 The SLIP driver encountered an escaped `end' marker. This probably
1077 means that someone's been sending it junk. The erroneous packet is
1078 discarded, and we hope that we've rediscovered synchronization.
1080 .BI "TUN \- slip fork-error " ecode " " message
1081 The SLIP driver encountered an error forking a child process while
1082 allocating a new dynamic interface.
1084 .BI "TUN \- slip no-slip-interfaces"
1085 The driver ran out of static SLIP interfaces. Either preallocate more,
1086 or use dynamic SLIP interface allocation.
1088 .BI "TUN " ifname " slip overflow"
1089 The SLIP driver gave up reading a packet because it got too large.
1091 .BI "TUN \- slip pipe-error " ecode " " message
1092 The SLIP driver encountered an error creating pipes while allocating a
1093 new dynamic interface.
1095 .BI "TUN \- slip read-ifname-failed " ecode " " message
1096 The SLIP driver encountered an error reading the name of a dynamically
1097 allocated interface. Maybe the allocation script is broken.
1099 .BI "TUN \- unet config-error " ecode " " message
1100 Configuring the Linux Unet interface failed. Unet is obsolete and
1101 shouldn't be used any more.
1103 .BI "TUN \- unet getinfo-error " ecode " " message
1104 Reading information about the Unet interface failed. Unet is obsolete
1105 and shouldn't be used any more.
1107 .BI "TUN \- unet ifname-too-long"
1108 The Unet interface's name overflowed, so we couldn't read it properly.
1109 Unet is obsolete and shouldn't be used any more.
1111 These are issued by administration clients using the
1115 .BI "USER " tokens\fR...
1116 An administration client issued a warning.
1119 .SS "Command responses"
1121 .BI "BGFAIL " tag " " tokens \fR...
1122 .BI "BGINFO " tag " " tokens \fR...
1124 .BI "FAIL " tokens \fR...
1125 .BI "INFO " tokens \fR...
1133 .IR "The Trivial IP Encryption Protocol" .
1135 Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blob