2 .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
4 tripe-admin \- administrator commands for TrIPE
6 This manual page describes the administration interface provided by the
12 program can be used either interactively or in scripts to communicate
13 with the server using this interface. Alternatively, simple custom
14 clients can be written in scripting languages such as Perl, Python or
15 Tcl, or more advanced clients such as GUI monitors can be written in C
16 with little difficulty.
18 By default, the server listens for admin connections on the Unix-domain
20 .BR /var/lib/tripe/tripesock .
21 Administration commands use a simple textual protocol. Each client
22 command or server response consists of a line of ASCII text terminated
23 by a single linefeed character. No command may be longer than 255
25 .SS "General structure"
26 Each command or response line consists of a sequence of
27 whitespace-separated words. The number and nature of whitespace
28 characters separating two words in a client command is not significant;
29 the server always uses a single space character. The first word in a
32 identifying the type of command or response contained. Keywords in
33 client commands are not case-sensitive; the server always uses uppercase
35 .SS "Server responses"
36 For client command, the server responds with zero or more
38 lines, followed by either an
44 provides information requested in the command. An
46 response contains no further data. A
48 code is followed by a human-readable explanation of why the command
51 In addition, there are two types of asynchronous `responses', which
52 aren't associated with any particular command. The
54 response contains a human-readable message warning of an error
55 encountered while processing a command, unexpected or unusual behaviour
56 by a peer, or a possible attack by an adversary. Under normal
57 conditions, the server shouldn't emit any warnings. The
59 response contains a human-readable tracing message containing diagnostic
60 information. Trace messages are controlled using the
62 command-line option to the server, or the
64 administration command (see below). Support for tracing can be disabled
65 when the package is being configured, and may not be available in your
67 .SS "Command reference"
68 The commands provided are:
71 Causes the server to emit an
73 line for each command it supports. Each line lists the command name,
74 followed by the names of the arguments. This may be helpful as a memory
75 aid for interactive use, or for program clients probing for features.
77 .BR "TRACE " [\fIoptions\fP]
78 A trace argument consists of a string of letters (listed below)
79 selecting trace outputs, optionally interspersed with
83 to disable, the subsequently listed outputs; the initial behaviour is to
84 enable listed outputs. For example, the string
86 enables tracing of peer management, admin-connection handling and
87 key-exchange processing, and disables tracing of symmetric keyset
88 management and the system-specific tunnel driver. If no argument is
89 given, a table is returned showing the available tracing option letters
90 and their meanings. Programs should not attempt to parse this table:
91 its format is not guaranteed to remain the same.
93 Currently, the following tracing options are supported:
96 Tunnel events: reception of packets to be encrypted, and injection of
97 successfully-decrypted packets.
100 Peer management events: creation and destruction of peer attachments,
101 and arrival of messages.
104 Administration interface: acceptance of new connections, and handling of
105 the backgroud name-resolution required by the
110 Display contents of packets sent and received by the tunnel and/or peer
114 Display inputs, outputs and intermediate results of cryptographic
115 operations. This includes plaintext and key material. Use with
119 Handling of symmetric keysets: creation and expiry of keysets, and
120 encryption and decryption of messages.
123 Key exchange: reception, parsing and emission of key exchange messages.
126 Key management: loading keys and checking for file modifications.
134 outputs provide extra detail for other outputs. Specifying
140 isn't useful; neither is specifying
152 line containing just the number of the UDP port used by the
154 server. If you've allowed your server to allocate a port dynamically,
155 this is how to find out which one it chose.
158 Causes the server to disassociate itself from its terminal and become a
159 background task. This only works once. A warning is issued.
162 For each currently-known peer, an
164 line is written containing the peer's name, as given to
170 line containing the name of the network interface used to collect IP
171 packets which are to be encrypted and sent to
173 Used by configuration scripts so that they can set up routing tables
174 appropriately after adding new peers.
179 line reporting the IP address and port number stored for
185 lines, each containing one or more statistics in the form
186 .IB name = value \fR.
187 The statistics-gathering is experimental and subject to change.
190 Causes the server to forget all about
192 All keys are destroyed, and no more packets are sent. No notification
193 is sent to the peer: if it's important that the peer be notified, you
194 must think of a way to do that yourself.
196 .BI "ADD " "peer addr port"
197 Adds a new peer. The peer is given the name
199 the peer's public key is assumed to be in the file
201 (or whatever alternative file was specified in the
203 option on the command line). The peer's
205 implementation may be contacted at the given UDP port and IP address.
208 Instructs the server to exit immediately. A warning is sent.
213 .IR "The Trivial IP Encryption Protocol" ,
215 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob