chiark / gitweb /
Distribute the manpages.
[tripe] / doc / tripe-admin.5
1 .\" -*-nroff-*-
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
7 .BR tripe (8)
8 daemon.
9 .PP
10 The
11 .BR tripectl (8)
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.
17 .PP
18 By default, the server listens for admin connections on the Unix-domain
19 socket
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
24 characters.
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
30 line is a
31 .I keyword
32 identifying the type of command or response contained.  Keywords in
33 client commands are not case-sensitive; the server always uses uppercase
34 for its keywords.
35 .SS "Server responses"
36 For client command, the server responds with zero or more
37 .B INFO
38 lines, followed by either an
39 .B OK
40 line or a
41 .B FAIL
42 line.  Each
43 .B INFO
44 provides information requested in the command.  An
45 .B OK
46 response contains no further data.  A
47 .B FAIL
48 code is followed by a human-readable explanation of why the command
49 failed.
50 .PP
51 In addition, there are two types of asynchronous `responses', which
52 aren't associated with any particular command.  The
53 .B WARN
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
61 .B \-T
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
66 version.
67 .SS "Command reference"
68 The commands provided are:
69 .TP
70 .B "HELP"
71 Causes the server to emit an
72 .B INFO
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.
76 .TP
77 .BR "TRACE " [\fIoptions\fP]
78 A trace argument consists of a string of letters (listed below)
79 selecting trace outputs, optionally interspersed with
80 .RB ` + '
81 to enable, or
82 .RB ` \- '
83 to disable, the subsequently listed outputs; the initial behaviour is to
84 enable listed outputs.  For example, the string
85 .B ra\-st+x
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.
92 .RS
93 Currently, the following tracing options are supported:
94 .TP
95 .B t
96 Tunnel events: reception of packets to be encrypted, and injection of
97 successfully-decrypted packets.
98 .TP
99 .B r
100 Peer management events: creation and destruction of peer attachments,
101 and arrival of messages.
102 .TP
103 .B a
104 Administration interface: acceptance of new connections, and handling of
105 the backgroud name-resolution required by the
106 .B ADD
107 command.
108 .TP
109 .B p
110 Display contents of packets sent and received by the tunnel and/or peer
111 modules.
112 .TP
113 .B c
114 Display inputs, outputs and intermediate results of cryptographic
115 operations.  This includes plaintext and key material.  Use with
116 caution.
117 .TP
118 .B s
119 Handling of symmetric keysets: creation and expiry of keysets, and
120 encryption and decryption of messages.
121 .TP
122 .B x
123 Key exchange: reception, parsing and emission of key exchange messages.
124 .TP
125 .B m
126 Key management: loading keys and checking for file modifications.
127 .PP
128 Note that the
129 .B p
130 (packet contents)
131 and
132 .B c
133 (crypto details)
134 outputs provide extra detail for other outputs.  Specifying
135 .B p
136 without
137 .B r
138 or
139 .B t
140 isn't useful; neither is specifying
141 .B c
142 without one of
143 .BR s ,
144 .B x
145 or
146 .BR m .
147 .RE
148 .TP
149 .B "PORT"
150 Emits an
151 .B INFO
152 line containing just the number of the UDP port used by the
153 .B tripe
154 server.  If you've allowed your server to allocate a port dynamically,
155 this is how to find out which one it chose.
156 .TP
157 .B "DAEMON"
158 Causes the server to disassociate itself from its terminal and become a
159 background task.  This only works once.  A warning is issued.
160 .TP
161 .B "LIST"
162 For each currently-known peer, an
163 .B INFO
164 line is written containing the peer's name, as given to
165 .BR ADD .
166 .TP 
167 .BI "IFNAME " peer
168 Emits an
169 .B INFO
170 line containing the name of the network interface used to collect IP
171 packets which are to be encrypted and sent to
172 .IR peer .
173 Used by configuration scripts so that they can set up routing tables
174 appropriately after adding new peers.
175 .TP
176 .BI "ADDR " peer
177 Emits an
178 .B INFO
179 line reporting the IP address and port number stored for
180 .IR peer .
181 .TP
182 .BI "STATS " peer
183 Emits a number of
184 .B INFO
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.
188 .TP
189 .BI "KILL " peer
190 Causes the server to forget all about
191 .IR peer .
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.
195 .TP
196 .BI "ADD " "peer addr port"
197 Adds a new peer.  The peer is given the name
198 .IR peer ;
199 the peer's public key is assumed to be in the file
200 .B
201 (or whatever alternative file was specified in the
202 .B \-K
203 option on the command line).  The peer's
204 .B tripe
205 implementation may be contacted at the given UDP port and IP address.
206 .TP
207 .B "QUIT"
208 Instructs the server to exit immediately.  A warning is sent.
209 .SH "SEE ALSO"
210 .BR tripectl (1),
211 .BR tripe (8).
212 .PP
213 .IR "The Trivial IP Encryption Protocol" ,
214 .SH "AUTHOR"
215 Mark Wooding, <>