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.
24 .SS "General structure"
25 Each command or response line consists of a sequence of
26 whitespace-separated words. The number and nature of whitespace
27 characters separating two words in a client command is not significant;
28 the server always uses a single space character. The first word in a
31 identifying the type of command or response contained. Keywords in
32 client commands are not case-sensitive; the server always uses uppercase
34 .SS "Server responses"
35 For client command, the server responds with zero or more
37 lines, followed by either an
43 provides information requested in the command. An
45 response contains no further data. A
47 code is followed by a human-readable explanation of why the command
50 In addition, there are two types of asynchronous `responses', which
51 aren't associated with any particular command. The
53 response contains a human-readable message warning of an error
54 encountered while processing a command, unexpected or unusual behaviour
55 by a peer, or a possible attack by an adversary. Under normal
56 conditions, the server shouldn't emit any warnings. The
58 response contains a human-readable tracing message containing diagnostic
59 information. Trace messages are controlled using the
61 command-line option to the server, or the
63 administration command (see below). Support for tracing can be disabled
64 when the package is being configured, and may not be available in your
66 .SS "Command reference"
67 The commands provided are:
70 Causes the server to emit an
72 line for each command it supports. Each line lists the command name,
73 followed by the names of the arguments. This may be helpful as a memory
74 aid for interactive use, or for program clients probing for features.
76 .BR "TRACE " [\fIoptions\fP]
77 A trace argument consists of a string of letters (listed below)
78 selecting trace outputs, optionally interspersed with
82 to disable, the subsequently listed outputs; the initial behaviour is to
83 enable listed outputs. For example, the string
85 enables tracing of peer management, admin-connection handling and
86 key-exchange processing, and disables tracing of symmetric keyset
87 management and the system-specific tunnel driver. If no argument is
88 given, a table is returned showing the available tracing option letters
89 and their meanings. Programs should not attempt to parse this table:
90 its format is not guaranteed to remain the same.
92 Currently, the following tracing options are supported:
95 Tunnel events: reception of packets to be encrypted, and injection of
96 successfully-decrypted packets.
99 Peer management events: creation and destruction of peer attachments,
100 and arrival of messages.
103 Administration interface: acceptance of new connections, and handling of
104 the backgroud name-resolution required by the
109 Display contents of packets sent and received by the tunnel and/or peer
113 Display inputs, outputs and intermediate results of cryptographic
114 operations. This includes plaintext and key material. Use with
118 Handling of symmetric keysets: creation and expiry of keysets, and
119 encryption and decryption of messages.
122 Key exchange: reception, parsing and emission of key exchange messages.
125 Key management: loading keys and checking for file modifications.
133 outputs provide extra detail for other outputs. Specifying
139 isn't useful; neither is specifying
151 line containing just the number of the UDP port used by the
153 server. If you've allowed your server to allocate a port dynamically,
154 this is how to find out which one it chose.
157 Causes the server to disassociate itself from its terminal and become a
158 background task. This only works once. A warning is issued.
161 For each currently-known peer, an
163 line is written containing the peer's name, as given to
169 line containing the name of the network interface used to collect IP
170 packets which are to be encrypted and sent to
172 Used by configuration scripts so that they can set up routing tables
173 appropriately after adding new peers.
178 line reporting the IP address and port number stored for
184 lines, each containing one or more statistics in the form
185 .IB name = value \fR.
186 The statistics-gathering is experimental and subject to change.
189 Causes the server to forget all about
191 All keys are destroyed, and no more packets are sent. No notification
192 is sent to the peer: if it's important that the peer be notified, you
193 must think of a way to do that yourself.
195 .BI "ADD " "peer addr port"
196 Adds a new peer. The peer is given the name
198 the peer's public key is assumed to be in the file
200 (or whatever alternative file was specified in the
202 option on the command line). The peer's
204 implementation may be contacted at the given UDP port and IP address.
207 Instructs the server to exit immediately. A warning is sent.
212 .IR "The Trivial IP Encryption Protocol" ,
214 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob