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