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 |
8bc63560 |
23 | by a single linefeed character. No command may be longer than 255 |
24 | characters. |
d6623498 |
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 |
58 | .B TRACE |
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 |
63 | .B TRACE |
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 keyring.pub |
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, <mdw@nsict.org> |