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.
94 Currently, the following tracing options are supported:
97 Tunnel events: reception of packets to be encrypted, and injection of
98 successfully-decrypted packets.
101 Peer management events: creation and destruction of peer attachments,
102 and arrival of messages.
105 Administration interface: acceptance of new connections, and handling of
106 the backgroud name-resolution required by the
111 Display contents of packets sent and received by the tunnel and/or peer
115 Display inputs, outputs and intermediate results of cryptographic
116 operations. This includes plaintext and key material. Use with
120 Handling of symmetric keysets: creation and expiry of keysets, and
121 encryption and decryption of messages.
124 Key exchange: reception, parsing and emission of key exchange messages.
127 Key management: loading keys and checking for file modifications.
135 outputs provide extra detail for other outputs. Specifying
141 isn't useful; neither is specifying
153 line containing just the number of the UDP port used by the
155 server. If you've allowed your server to allocate a port dynamically,
156 this is how to find out which one it chose.
159 Causes the server to disassociate itself from its terminal and become a
160 background task. This only works once. A warning is issued.
163 For each currently-known peer, an
165 line is written containing the peer's name, as given to
171 line containing the name of the network interface used to collect IP
172 packets which are to be encrypted and sent to
174 Used by configuration scripts so that they can set up routing tables
175 appropriately after adding new peers.
180 line reporting the IP address and port number stored for
186 lines, each containing one or more statistics in the form
187 .IB name = value \fR.
188 The statistics-gathering is experimental and subject to change.
191 Causes the server to forget all about
193 All keys are destroyed, and no more packets are sent. No notification
194 is sent to the peer: if it's important that the peer be notified, you
195 must think of a way to do that yourself.
197 .BI "ADD " "peer addr port"
198 Adds a new peer. The peer is given the name
200 the peer's public key is assumed to be in the file
202 (or whatever alternative file was specified in the
204 option on the command line). The peer's
206 implementation may be contacted at the given UDP port and IP address.
209 Instructs the server to exit immediately. A warning is sent.
214 .IR "The Trivial IP Encryption Protocol" ,
216 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob