chiark / gitweb /
Use standard GNU uppercase for metavariables in usage strings. Some manpage
[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 .PP
94 Currently, the following tracing options are supported:
95 .TP
96 .B t
97 Tunnel events: reception of packets to be encrypted, and injection of
98 successfully-decrypted packets.
99 .TP
100 .B r
101 Peer management events: creation and destruction of peer attachments,
102 and arrival of messages.
103 .TP
104 .B a
105 Administration interface: acceptance of new connections, and handling of
106 the backgroud name-resolution required by the
107 .B ADD
108 command.
109 .TP
110 .B p
111 Display contents of packets sent and received by the tunnel and/or peer
112 modules.
113 .TP
114 .B c
115 Display inputs, outputs and intermediate results of cryptographic
116 operations.  This includes plaintext and key material.  Use with
117 caution.
118 .TP
119 .B s
120 Handling of symmetric keysets: creation and expiry of keysets, and
121 encryption and decryption of messages.
122 .TP
123 .B x
124 Key exchange: reception, parsing and emission of key exchange messages.
125 .TP
126 .B m
127 Key management: loading keys and checking for file modifications.
128 .PP
129 Note that the
130 .B p
131 (packet contents)
132 and
133 .B c
134 (crypto details)
135 outputs provide extra detail for other outputs.  Specifying
136 .B p
137 without
138 .B r
139 or
140 .B t
141 isn't useful; neither is specifying
142 .B c
143 without one of
144 .BR s ,
145 .B x
146 or
147 .BR m .
148 .RE
149 .TP
150 .B "PORT"
151 Emits an
152 .B INFO
153 line containing just the number of the UDP port used by the
154 .B tripe
155 server.  If you've allowed your server to allocate a port dynamically,
156 this is how to find out which one it chose.
157 .TP
158 .B "DAEMON"
159 Causes the server to disassociate itself from its terminal and become a
160 background task.  This only works once.  A warning is issued.
161 .TP
162 .B "LIST"
163 For each currently-known peer, an
164 .B INFO
165 line is written containing the peer's name, as given to
166 .BR ADD .
167 .TP 
168 .BI "IFNAME " peer
169 Emits an
170 .B INFO
171 line containing the name of the network interface used to collect IP
172 packets which are to be encrypted and sent to
173 .IR peer .
174 Used by configuration scripts so that they can set up routing tables
175 appropriately after adding new peers.
176 .TP
177 .BI "ADDR " peer
178 Emits an
179 .B INFO
180 line reporting the IP address and port number stored for
181 .IR peer .
182 .TP
183 .BI "STATS " peer
184 Emits a number of
185 .B INFO
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.
189 .TP
190 .BI "KILL " peer
191 Causes the server to forget all about
192 .IR peer .
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.
196 .TP
197 .BI "ADD " "peer addr port"
198 Adds a new peer.  The peer is given the name
199 .IR peer ;
200 the peer's public key is assumed to be in the file
201 .B
202 (or whatever alternative file was specified in the
203 .B \-K
204 option on the command line).  The peer's
205 .B tripe
206 implementation may be contacted at the given UDP port and IP address.
207 .TP
208 .B "QUIT"
209 Instructs the server to exit immediately.  A warning is sent.
210 .SH "SEE ALSO"
211 .BR tripectl (1),
212 .BR tripe (8).
213 .PP
214 .IR "The Trivial IP Encryption Protocol" ,
215 .SH "AUTHOR"
216 Mark Wooding, <>