Commit | Line | Data |
---|---|---|
d6623498 | 1 | .\" -*-nroff-*- |
fc916a09 MW |
2 | .\". |
3 | .\" Manual for the administration protocol | |
4 | .\" | |
5 | .\" (c) 2008 Straylight/Edgeware | |
060ca767 | 6 | .\" |
13a55605 | 7 | . |
fc916a09 MW |
8 | .\"----- Licensing notice --------------------------------------------------- |
9 | .\" | |
10 | .\" This file is part of Trivial IP Encryption (TrIPE). | |
11 | .\" | |
12 | .\" TrIPE is free software; you can redistribute it and/or modify | |
13 | .\" it under the terms of the GNU General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or | |
15 | .\" (at your option) any later version. | |
16 | .\" | |
17 | .\" TrIPE is distributed in the hope that it will be useful, | |
18 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | .\" GNU General Public License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public License | |
23 | .\" along with TrIPE; if not, write to the Free Software Foundation, | |
24 | .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | |
25 | . | |
26 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 27 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
28 | . |
29 | .\"-------------------------------------------------------------------------- | |
d6623498 | 30 | .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
31 | . |
32 | .\"-------------------------------------------------------------------------- | |
33 | .SH "NAME" | |
34 | . | |
d6623498 | 35 | tripe-admin \- administrator commands for TrIPE |
fc916a09 MW |
36 | . |
37 | .\"-------------------------------------------------------------------------- | |
38 | .SH "DESCRIPTION" | |
39 | . | |
d6623498 | 40 | This manual page describes the administration interface provided by the |
41 | .BR tripe (8) | |
42 | daemon. | |
43 | .PP | |
44 | The | |
45 | .BR tripectl (8) | |
46 | program can be used either interactively or in scripts to communicate | |
47 | with the server using this interface. Alternatively, simple custom | |
48 | clients can be written in scripting languages such as Perl, Python or | |
49 | Tcl, or more advanced clients such as GUI monitors can be written in C | |
50 | with little difficulty. | |
51 | .PP | |
37941236 | 52 | Administration commands use a textual protocol. Each client command or |
53 | server response consists of a line of ASCII text terminated by a single | |
54 | linefeed character. No command may be longer than 255 characters. | |
d6623498 | 55 | .SS "General structure" |
56 | Each command or response line consists of a sequence of | |
83487ded MW |
57 | whitespace-separated tokens. The number and nature of whitespace |
58 | characters separating two tokens in a client command is not significant; | |
59 | the server always uses a single space character. The first token in a | |
d6623498 | 60 | line is a |
61 | .I keyword | |
62 | identifying the type of command or response contained. Keywords in | |
63 | client commands are not case-sensitive; the server always uses uppercase | |
64 | for its keywords. | |
83487ded MW |
65 | .PP |
66 | In order to allow tokens to contain internal whitespace, a quoting | |
67 | mechanism is provided. Whitespace within matched pairs of quotes \(en | |
68 | either single | |
69 | .RB ` ' ' | |
70 | or double | |
71 | .RB ` """" ' | |
72 | \(en is considered to be internal. Any character (other than newline) | |
73 | may be escaped by preceding it with a backslash | |
74 | .RB ` \e ': | |
75 | in particular, this can be used to include quote characters. It is | |
76 | impossible for a token to contain a newline character. | |
77 | .PP | |
78 | On output, the server will use double quotes when necessary. | |
de014da6 | 79 | .SS "Simple commands" |
80 | For simple client command, the server responds with zero or more | |
d6623498 | 81 | .B INFO |
82 | lines, followed by either an | |
83 | .B OK | |
84 | line or a | |
85 | .B FAIL | |
86 | line. Each | |
87 | .B INFO | |
88 | provides information requested in the command. An | |
89 | .B OK | |
90 | response contains no further data. A | |
91 | .B FAIL | |
3cdc3f3a | 92 | code is followed by a machine-readable explanation of why the command |
d6623498 | 93 | failed. |
94 | .PP | |
de014da6 | 95 | Simple command processing is strictly synchronous: the server reads a |
96 | command, processes it, and responds, before reading the next command. | |
97 | All commands can be run as simple commands. Long-running commands | |
98 | (e.g., | |
99 | .B ADD | |
100 | and | |
101 | .BR PING ) | |
102 | block the client until they finish, but the rest of the server continues | |
bdc44f5b MW |
103 | running. See |
104 | .B "Background commands" | |
105 | to find out how to issue long-running commands without blocking. | |
106 | .SS "Asynchronous broadcasts" | |
107 | There are three types of asynchronous broadcast messages which aren't | |
108 | associated with any particular command. Clients can select which | |
109 | broadcast messages they're interested in using the | |
110 | .B WATCH | |
111 | command. | |
de014da6 | 112 | .PP |
113 | The | |
d6623498 | 114 | .B WARN |
3cdc3f3a | 115 | message contains a machine-readable message warning of an error |
d6623498 | 116 | encountered while processing a command, unexpected or unusual behaviour |
117 | by a peer, or a possible attack by an adversary. Under normal | |
de014da6 | 118 | conditions, the server shouldn't emit any warnings. |
119 | .PP | |
120 | The | |
d6623498 | 121 | .B TRACE |
3cdc3f3a | 122 | message contains a human-readable tracing message containing diagnostic |
d6623498 | 123 | information. Trace messages are controlled using the |
124 | .B \-T | |
125 | command-line option to the server, or the | |
126 | .B TRACE | |
127 | administration command (see below). Support for tracing can be disabled | |
128 | when the package is being configured, and may not be available in your | |
de014da6 | 129 | version. |
130 | .PP | |
131 | Finally, the | |
3cdc3f3a | 132 | .B NOTE |
133 | message is a machine-readable notification about some routine but | |
134 | interesting event such as creation or destruction of peers. | |
de014da6 | 135 | .SS "Background commands" |
136 | Some commands (e.g., | |
137 | .B ADD | |
138 | and | |
139 | .BR PING ) | |
140 | take a long time to complete. To prevent these long-running commands | |
141 | from tying up a server connection, they can be run in the background. | |
142 | Not all commands can be run like this: the ones that can provide a | |
143 | .B \-background | |
144 | option, which must be supplied with a | |
145 | .IR tag . | |
146 | .PP | |
147 | A command may fail before it starts running in the background. In this | |
148 | case, the server emits a | |
149 | .B FAIL | |
150 | response, as usual. To indicate that a command has started running in | |
151 | the background, the server emits a response of the form | |
152 | .BI "BGDETACH " tag \fR, | |
153 | where | |
154 | .I tag | |
155 | is the value passed to the | |
156 | .B \-background | |
157 | option. From this point on, the server is ready to process more | |
158 | commands and reply to them. | |
159 | .PP | |
160 | Responses to background commands are indicated by a line beginning with | |
e04c2d50 | 161 | one of the tokens |
de014da6 | 162 | .BR BGOK , |
163 | .BR BGFAIL , | |
164 | or | |
165 | .BR BGINFO , | |
e04c2d50 | 166 | followed by the command tag. These correspond to the |
de014da6 | 167 | .BR OK , |
168 | .BR FAIL , | |
169 | and | |
170 | .B INFO | |
171 | responses for simple commands: | |
172 | .B BGINFO | |
173 | indicates information from a background command which has not completed | |
174 | yet; and | |
175 | .B BGOK | |
176 | and | |
177 | .B BGFAIL | |
178 | indicates that a background command succeeded or failed, respectively. | |
179 | .PP | |
180 | A background command will never issue an | |
181 | .B OK | |
060ca767 | 182 | or |
9df937a3 | 183 | .B INFO |
060ca767 | 184 | response: it will always detach and then issue any |
185 | .B BGINFO | |
186 | lines followed by | |
de014da6 | 187 | .B BGOK |
188 | response. | |
bdc44f5b MW |
189 | .SS "Client-provided services" |
190 | .\"* 25 Service-related messages | |
191 | An administration client can provide services to other clients. | |
192 | Services are given names and versions. A client can attempt to | |
193 | .I claim | |
194 | a particular service by issuing the | |
195 | .B SVCCLAIM | |
196 | command. This may fail, for example, if some other client already | |
197 | provides the same or later version of the service. | |
198 | .PP | |
199 | Other clients can issue | |
200 | .I "service commands" | |
201 | using the | |
202 | .B "SVCSUBMIT" | |
203 | command; the service provider is expected to handle these commands and | |
204 | reply to them. | |
205 | .PP | |
206 | There are three important asynchronous messages which will be sent to | |
207 | service providers. | |
208 | .SP | |
209 | .BI "SVCCANCEL " jobid | |
210 | The named job has been cancelled, either because the issuing client has | |
211 | disconnected or explicitly cancelled the job using the | |
212 | .B BGCANCEL | |
213 | command. | |
214 | .SP | |
215 | .BI "SVCCLAIM " service " " version | |
216 | Another client has claimed a later version of the named | |
9df937a3 MW |
217 | .IR service . |
218 | The recipient is no longer the provider of this service. | |
bdc44f5b MW |
219 | .SP |
220 | .BI "SVCJOB " jobid " " service " " command " " args \fR... | |
221 | Announces the arrival of a new job. The | |
222 | .I jobid | |
223 | is a simple token consisting of alphanumeric characters which | |
224 | .B tripe | |
225 | uses to identify this job. | |
226 | .PP | |
227 | The service provider can reply to the job using the commands | |
228 | .BR SVCINFO , | |
229 | .B SVCOK | |
230 | and | |
231 | .BR SVCFAIL . | |
232 | The first of these sends an | |
233 | .B INFO | |
234 | response and leaves the job active; the other two send an | |
235 | .B OK | |
236 | or | |
237 | .B FAIL | |
238 | response respectively, and mark the job as being complete. | |
239 | .PP | |
240 | (Since | |
241 | .B SVCSUBMIT | |
242 | is a potentially long-running command, it can be run in the background. | |
243 | This detail is hidden from service providers: | |
244 | .B tripe | |
245 | will issue the corresponding | |
246 | .BR BG ... | |
247 | responses when appropriate.) | |
3cdc3f3a | 248 | .SS "Network addresses" |
83487ded | 249 | A network address is a sequence of tokens. The first is a token |
3cdc3f3a | 250 | identifying the network address family. The length of an address and |
83487ded | 251 | the meanings of the subsequent tokens depend on the address family. |
3cdc3f3a | 252 | Address family tokens are not case-sensitive on input; on output, they |
253 | are always in upper-case. | |
254 | .PP | |
255 | At present, only one address family is understood. | |
256 | .TP | |
165efde7 | 257 | .BI "INET " address " \fR[" port \fR] |
3cdc3f3a | 258 | An Internet socket, naming an IPv4 address and UDP port. On output, the |
259 | address is always in numeric dotted-quad form, and the port is given as | |
260 | a plain number. On input, DNS hostnames and symbolic port names are | |
165efde7 MW |
261 | permitted; if omitted, the default port 4070 is used. Name resolution |
262 | does not block the main server, but will block the requesting client, | |
263 | unless the command is run in the background. | |
3cdc3f3a | 264 | .PP |
78dcf842 | 265 | If, on input, no recognized address family token is found, the following |
83487ded | 266 | tokens are assumed to represent an |
3cdc3f3a | 267 | .B INET |
2acd7cd6 MW |
268 | address. Addresses output by the server always have an address family |
269 | token. | |
060ca767 | 270 | .SS "Key-value output" |
271 | Some commands (e.g., | |
272 | .B STATS | |
273 | and | |
274 | .BR SERVINFO ) | |
275 | produce output in the form of | |
276 | .IB key = value | |
83487ded | 277 | pairs, one per token. Neither the |
060ca767 | 278 | .I key |
279 | nor the | |
280 | .I value | |
281 | contain spaces. | |
282 | .SS "Trace lists" | |
283 | Commands which enable or disable kinds of output (e.g., | |
284 | .B TRACE | |
285 | and | |
286 | .BR WATCH ) | |
287 | work in similar ways. They take a single optional argument, which | |
288 | consists of a string of letters selecting message types, optionally | |
289 | interspersed with | |
290 | .RB ` + ' | |
291 | to enable, or | |
292 | .RB ` \- ' | |
293 | to disable, the subsequently listed types. | |
294 | .PP | |
295 | If the argument is omitted, the available message types are displayed, | |
296 | one to an | |
297 | .B INFO | |
298 | line, in a fixed-column format. Column zero contains the key letter for | |
299 | selecting that message type; column one contains either a space or a | |
e04c2d50 | 300 | .RB ` + ' |
060ca767 | 301 | sign, if the message type is disabled or enabled respectively; and a |
302 | textual description of the message type begins at column 3 and continues | |
303 | to the end of the line. | |
304 | .PP | |
305 | Lowercase key letters control individual message types. Uppercase key | |
306 | letters control collections of message types. | |
fc916a09 MW |
307 | . |
308 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 309 | .SH "COMMAND REFERENCE" |
fc916a09 | 310 | . |
13a55605 | 311 | .\"* 10 Commands |
d6623498 | 312 | The commands provided are: |
13a55605 | 313 | .SP |
9986f0b5 | 314 | .BI "ADD \fR[" options "\fR] " peer " " address "\fR..." |
3cdc3f3a | 315 | Adds a new peer. The peer is given the name |
316 | .IR peer ; | |
317 | the peer's public key is assumed to be in the file | |
318 | .B keyring.pub | |
319 | (or whatever alternative file was specified in the | |
320 | .B \-K | |
321 | option on the command line). The | |
322 | .I address | |
323 | is the network address (see above for the format) at which the peer can | |
78dcf842 | 324 | be contacted. The following options are recognized. |
42da2a58 | 325 | .RS |
13a55605 | 326 | .\"+opts |
42da2a58 | 327 | .TP |
de014da6 | 328 | .BI "\-background " tag |
329 | Run the command in the background, using the given | |
330 | .IR tag . | |
331 | .TP | |
010e6f63 MW |
332 | .B "\-cork" |
333 | Don't send an immediate challenge to the peer; instead, wait until it | |
334 | sends us something before responding. | |
335 | .TP | |
0ba8de86 | 336 | .BI "\-keepalive " time |
337 | Send a no-op packet if we've not sent a packet to the peer in the last | |
338 | .I time | |
339 | interval. This is useful for persuading port-translating firewalls to | |
340 | believe that the `connection' is still active. The | |
341 | .I time | |
342 | is expressed as a nonnegative integer followed optionally by | |
343 | .BR d , | |
344 | .BR h , | |
345 | .BR m , | |
346 | or | |
347 | .BR s | |
348 | for days, hours, minutes, or seconds respectively; if no suffix is | |
349 | given, seconds are assumed. | |
350 | .TP | |
48b84569 MW |
351 | .BI "\-key " tag |
352 | Use the public key | |
353 | .I tag | |
354 | to authenticate the peer. The default is to use the key tagged | |
355 | .IR peer . | |
356 | .TP | |
6411163d MW |
357 | .B "\-mobile" |
358 | The peer is a mobile device, and is likely to change address rapidly. | |
359 | If a packet arrives from an unknown address, the server's usual response | |
360 | is to log a warning and discard it. If the server knows of any mobile | |
361 | peers, however, it will attempt to decrypt the packet using their keys, | |
362 | and if one succeeds, the server will update its idea of the peer's | |
363 | address and emit an | |
364 | .B NEWADDR | |
365 | notification. | |
366 | .TP | |
0ba8de86 | 367 | .BI "\-tunnel " tunnel |
42da2a58 | 368 | Use the named tunnel driver, rather than the default. |
13a55605 | 369 | .\"-opts |
42da2a58 | 370 | .RE |
13a55605 | 371 | .SP |
3cdc3f3a | 372 | .BI "ADDR " peer |
373 | Emits an | |
374 | .B INFO | |
375 | line reporting the IP address and port number stored for | |
376 | .IR peer . | |
13a55605 | 377 | .SP |
449991a3 MW |
378 | .B "ALGS" |
379 | Emits information about the cryptographic algorithms in use, in | |
380 | key-value form. The keys are as follows. | |
381 | .RS | |
382 | .TP | |
383 | .B kx-group | |
384 | Type of key-exchange group in use, currently either | |
385 | .B ec | |
386 | or | |
387 | .BR prime . | |
388 | .TP | |
389 | .B kx-group-order-bits | |
390 | Length of the group order, in bits. This gives an approximate measure | |
391 | of the group strength. | |
392 | .TP | |
393 | .B kx-group-elt-bits | |
394 | Length of a group element, in bits. This may be useful when analyzing | |
395 | protocol traces. | |
396 | .TP | |
397 | .B hash | |
398 | The hash function in use, e.g., | |
399 | .BR sha256 . | |
400 | .TP | |
401 | .B mgf | |
402 | The mask-generating function in use, e.g., | |
403 | .BR whirlpool-mgf . | |
404 | .TP | |
405 | .B hashsz | |
406 | The size of the hash function's output, in octets. | |
407 | .TP | |
408 | .B cipher | |
409 | The name of the bulk data cipher in use, e.g., | |
410 | .BR blowfish-cbc . | |
411 | .TP | |
412 | .B cipher-keysz | |
413 | The length of key used by the bulk data cipher, in octets. | |
414 | .TP | |
415 | .B cipher-blksz | |
416 | The block size of the bulk data cipher, or zero if it's not based on a | |
417 | block cipher. | |
418 | .TP | |
419 | .B cipher-data-limit | |
420 | The maximum amount of data to be encrypted using a single key. (A new | |
421 | key exchange is instigated well before the limit is reached, in order to | |
422 | allow for a seamless changeover of keys.) | |
423 | .TP | |
424 | .B mac | |
425 | The message authentication algorithm in use, e.g., | |
426 | .BR ripemd160-hmac .. | |
427 | .TP | |
428 | .B mac-keysz | |
429 | The length of the key used by the message authentication algorithm, in | |
430 | octets. | |
431 | .TP | |
432 | .B mac-tagsz | |
433 | The length of the message authentication tag, in octets. | |
434 | .PP | |
435 | The various sizes are useful, for example, when computing the MTU for a | |
436 | tunnel interface. If | |
437 | .I MTU | |
438 | is the MTU of the path to the peer, then the tunnel MTU should be | |
439 | .IP | |
440 | .I MTU | |
441 | \- 33 \- | |
442 | .I cipher-blksz | |
443 | \- | |
444 | .I mac-tagsz | |
445 | .PP | |
446 | allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type | |
447 | octet, a four-octet sequence number, an IV, and a MAC tag. | |
448 | .RE | |
449 | .SP | |
ff92ffd3 MW |
450 | .BI "BGCANCEL " tag |
451 | Cancels the background job with the named | |
452 | .IR tag . | |
453 | .SP | |
37941236 | 454 | .BI "CHECKCHAL " challenge |
455 | Verifies a challenge as being one earlier issued by | |
456 | .B GETCHAL | |
457 | and not previously either passed to | |
458 | .B CHECKCHAL | |
459 | or in a greeting message. | |
13a55605 | 460 | .SP |
3cdc3f3a | 461 | .B "DAEMON" |
462 | Causes the server to disassociate itself from its terminal and become a | |
463 | background task. This only works once. A warning is issued. | |
2acd7cd6 | 464 | .SP |
0ba8de86 | 465 | .BI "EPING \fR[" options "\fR] " peer |
466 | Sends an encrypted ping to the peer, and expects an encrypted response. | |
467 | This checks that the peer is running (and not being impersonated), and | |
468 | that it can encrypt and decrypt packets correctly. Options and | |
469 | responses are the same as for the | |
470 | .B PING | |
471 | command. | |
13a55605 | 472 | .SP |
de014da6 | 473 | .BI "FORCEKX " peer |
474 | Requests the server to begin a new key exchange with | |
475 | .I peer | |
476 | immediately. | |
13a55605 | 477 | .SP |
37941236 | 478 | .B "GETCHAL" |
479 | Requests a challenge. The challenge is returned in an | |
480 | .B INFO | |
481 | line, as a base64-encoded string. See | |
482 | .BR CHECKCHAL . | |
13a55605 | 483 | .SP |
37941236 | 484 | .BI "GREET " peer " " challenge |
485 | Sends a greeting packet containing the | |
486 | .I challenge | |
487 | (base-64 encoded) to the named | |
488 | .IR peer . | |
489 | The expectation is that this will cause the peer to recognize us and | |
490 | begin a key-exchange. | |
13a55605 | 491 | .SP |
d6623498 | 492 | .B "HELP" |
493 | Causes the server to emit an | |
494 | .B INFO | |
495 | line for each command it supports. Each line lists the command name, | |
496 | followed by the names of the arguments. This may be helpful as a memory | |
497 | aid for interactive use, or for program clients probing for features. | |
e04c2d50 | 498 | .SP |
3cdc3f3a | 499 | .BI "IFNAME " peer |
500 | Emits an | |
501 | .B INFO | |
502 | line containing the name of the network interface used to collect IP | |
503 | packets which are to be encrypted and sent to | |
504 | .IR peer . | |
505 | Used by configuration scripts so that they can set up routing tables | |
506 | appropriately after adding new peers. | |
13a55605 | 507 | .SP |
ff92ffd3 MW |
508 | .B "JOBS" |
509 | Emits an | |
510 | .B INFO | |
511 | line giving the tag for each outstanding background job. | |
512 | .SP | |
3cdc3f3a | 513 | .BI "KILL " peer |
514 | Causes the server to forget all about | |
515 | .IR peer . | |
516 | All keys are destroyed, and no more packets are sent. No notification | |
517 | is sent to the peer: if it's important that the peer be notified, you | |
518 | must think of a way to do that yourself. | |
13a55605 | 519 | .SP |
3cdc3f3a | 520 | .B "LIST" |
521 | For each currently-known peer, an | |
522 | .B INFO | |
523 | line is written containing the peer's name, as given to | |
524 | .BR ADD . | |
13a55605 | 525 | .SP |
bd58d532 | 526 | .BI "NOTIFY " tokens\fR... |
e04c2d50 | 527 | Issues a |
bd58d532 | 528 | .B USER |
529 | notification to all interested administration clients. | |
13a55605 | 530 | .SP |
060ca767 | 531 | .BI "PEERINFO " peer |
532 | Returns information about a peer, in key-value form. The following keys | |
533 | are returned. | |
534 | .RS | |
535 | .TP | |
536 | .B tunnel | |
537 | The tunnel driver used for this peer. | |
538 | .TP | |
539 | .B keepalive | |
540 | The keepalive interval, in seconds, or zero if no keepalives are to be | |
541 | sent. | |
48b84569 MW |
542 | .TP |
543 | .B key | |
544 | The key tag being used for the peer, as passed to the | |
545 | .B ADD | |
546 | command. (You don't get a full key-id, since that might change while | |
547 | the daemon's running.) | |
060ca767 | 548 | .RE |
13a55605 | 549 | .SP |
0ba8de86 | 550 | .BI "PING \fR[" options "\fR] " peer |
551 | Send a transport-level ping to the peer. The ping and its response are | |
552 | not encrypted or authenticated. This command, possibly in conjunction | |
553 | with tracing, is useful for ensuring that UDP packets are actually | |
554 | flowing in both directions. See also the | |
555 | .B EPING | |
556 | command. | |
557 | .IP | |
558 | An | |
559 | .B INFO | |
560 | line is printed describing the outcome: | |
561 | .RS | |
562 | .TP | |
563 | .BI "ping-ok " millis | |
e04c2d50 | 564 | A response was received |
0ba8de86 | 565 | .I millis |
566 | after the ping was sent. | |
567 | .TP | |
568 | .BI "ping-timeout" | |
569 | No response was received within the time allowed. | |
570 | .TP | |
571 | .BI "ping-peer-died" | |
572 | The peer was killed (probably by another admin connection) before a | |
573 | response was received. | |
574 | .RE | |
575 | .IP | |
576 | Options recognized for this command are: | |
577 | .RS | |
13a55605 | 578 | .\"+opts |
0ba8de86 | 579 | .TP |
de014da6 | 580 | .BI "\-background " tag |
581 | Run the command in the background, using the given | |
582 | .IR tag . | |
583 | .TP | |
0ba8de86 | 584 | .BI "\-timeout " time |
585 | Wait for | |
586 | .I time | |
2acd7cd6 MW |
587 | seconds before giving up on a response. The default is 5 seconds. The |
588 | .I time | |
589 | is expressed as a nonnegative integer followed optionally by | |
590 | .BR d , | |
591 | .BR h , | |
592 | .BR m , | |
593 | or | |
594 | .BR s | |
595 | for days, hours, minutes, or seconds respectively; if no suffix is | |
596 | given, seconds are assumed. | |
13a55605 | 597 | .\"-opts |
0ba8de86 | 598 | .RE |
13a55605 | 599 | .SP |
3cdc3f3a | 600 | .B "PORT" |
601 | Emits an | |
602 | .B INFO | |
603 | line containing just the number of the UDP port used by the | |
604 | .B tripe | |
605 | server. If you've allowed your server to allocate a port dynamically, | |
606 | this is how to find out which one it chose. | |
13a55605 | 607 | .SP |
de014da6 | 608 | .B "RELOAD" |
609 | Instructs the server to recheck its keyring files. The server checks | |
610 | these periodically anyway but it may be necessary to force a recheck, | |
611 | for example after adding a new peer key. | |
13a55605 | 612 | .SP |
3cdc3f3a | 613 | .B "QUIT" |
614 | Instructs the server to exit immediately. A warning is sent. | |
13a55605 | 615 | .SP |
060ca767 | 616 | .B "SERVINFO" |
617 | Returns information about the server, in the form of key-value pairs. | |
618 | The following keys are used. | |
619 | .RS | |
620 | .TP | |
621 | .B implementation | |
622 | A keyword naming the implementation of the | |
623 | .BR tripe (8) | |
624 | server. The current implementation is called | |
625 | .BR edgeware-tripe . | |
626 | .TP | |
627 | .B version | |
628 | The server's version number, as reported by | |
629 | .BR VERSION . | |
630 | .TP | |
631 | .B daemon | |
632 | Either | |
633 | .B t | |
634 | or | |
635 | .BR nil , | |
636 | if the server has or hasn't (respectively) become a daemon. | |
637 | .RE | |
13a55605 | 638 | .SP |
64cf2223 MW |
639 | .BI "SETIFNAME " peer " " new-name |
640 | Informs the server that the | |
641 | .IR peer 's | |
642 | tunnel-interface name has been changed to | |
643 | .IR new-name . | |
644 | This is useful if firewalling decisions are made based on interface | |
645 | names: a setup script for a particular peer can change the name, and | |
646 | then update the server's records so that they're accurate. | |
647 | .SP | |
bdc44f5b MW |
648 | .BI "SVCCLAIM " service " " version |
649 | Attempts to claim the named | |
650 | .IR service , | |
651 | offering the given | |
652 | .IR version . | |
653 | The claim is successful if the service is currently unclaimed, or if | |
654 | a version earlier than | |
655 | .I version | |
656 | is provided; otherwise the command fails with the error | |
657 | .BR "service-exists" . | |
658 | .SP | |
659 | .BI "SVCENSURE " service " \fR[" version \fR] | |
e04c2d50 | 660 | Ensure that |
bdc44f5b MW |
661 | .I service |
662 | is provided, and (if specified) to at least the given | |
663 | .IR version . | |
664 | An error is reported if these conditions are not met; otherwise the | |
665 | command succeeds silently. | |
666 | .SP | |
667 | .BI "SVCFAIL " jobid " " tokens \fR... | |
668 | Send a | |
669 | .B FAIL | |
670 | (or | |
671 | .BR BGFAIL ) | |
672 | response to the service job with the given | |
673 | .IR jobid , | |
e04c2d50 | 674 | passing the |
bdc44f5b MW |
675 | .I tokens |
676 | as the reason for failure. The job is closed. | |
677 | .SP | |
678 | .BI "SVCINFO " jobid " " tokens \fR... | |
679 | Send an | |
680 | .B INFO | |
681 | (or | |
682 | .BR BGINFO ) | |
683 | response to the service job with the given | |
684 | .IR jobid , | |
685 | passing the | |
686 | .I tokens | |
687 | as the info message. The job remains open. | |
688 | .SP | |
689 | .B "SVCLIST" | |
690 | Output a line of the form | |
691 | .RS | |
692 | .IP | |
693 | .B INFO | |
694 | .I service | |
695 | .I version | |
696 | .PP | |
697 | for each service currently provided. | |
698 | .RE | |
699 | .SP | |
700 | .BI "SVCOK " jobid | |
701 | Send an | |
702 | .B OK | |
703 | (or | |
704 | .BR BGINFO ) | |
705 | response to the service job with the given | |
706 | .IR jobid . | |
707 | The job is closed. | |
708 | .SP | |
709 | .BI "SVCQUERY " service | |
710 | Emits a number of | |
711 | .B info | |
712 | lines in key-value format, describing the named | |
713 | .IR service. | |
714 | The following keys are used. | |
715 | .RS | |
716 | .TP | |
717 | .B name | |
718 | The service's name. | |
719 | .TP | |
720 | .B version | |
721 | The service's version string. | |
722 | .RE | |
723 | .SP | |
724 | .BI "SVCRELEASE " service | |
725 | Announce that the client no longer wishes to provide the named | |
726 | .IR service . | |
727 | .SP | |
728 | .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR... | |
729 | Submit a job to the provider of the given | |
730 | .IR service , | |
731 | passing it the named | |
732 | .I command | |
733 | and the given | |
734 | .IR arguments . | |
735 | The following options are accepted. | |
736 | .RS | |
737 | .\"+opts | |
738 | .TP | |
739 | .BI "\-background " tag | |
740 | Run the command in the background, using the given | |
741 | .IR tag . | |
742 | .TP | |
743 | .BI "\-version " version | |
744 | Ensure that at least the given | |
745 | .I version | |
746 | of the service is available before submitting the job. | |
747 | .RE | |
748 | .\"-opts | |
749 | .SP | |
3cdc3f3a | 750 | .BI "STATS " peer |
751 | Emits a number of | |
752 | .B INFO | |
753 | lines, each containing one or more statistics in the form | |
754 | .IB name = value \fR. | |
755 | The statistics-gathering is experimental and subject to change. | |
13a55605 | 756 | .SP |
d6623498 | 757 | .BR "TRACE " [\fIoptions\fP] |
060ca767 | 758 | Selects trace outputs: see |
e04c2d50 | 759 | .B "Trace lists" |
060ca767 | 760 | above. Message types provided are: |
d6623498 | 761 | .RS |
2d752320 | 762 | .PP |
d6623498 | 763 | Currently, the following tracing options are supported: |
764 | .TP | |
765 | .B t | |
766 | Tunnel events: reception of packets to be encrypted, and injection of | |
767 | successfully-decrypted packets. | |
768 | .TP | |
769 | .B r | |
770 | Peer management events: creation and destruction of peer attachments, | |
771 | and arrival of messages. | |
772 | .TP | |
773 | .B a | |
774 | Administration interface: acceptance of new connections, and handling of | |
775 | the backgroud name-resolution required by the | |
776 | .B ADD | |
777 | command. | |
778 | .TP | |
d6623498 | 779 | .B s |
780 | Handling of symmetric keysets: creation and expiry of keysets, and | |
781 | encryption and decryption of messages. | |
782 | .TP | |
783 | .B x | |
784 | Key exchange: reception, parsing and emission of key exchange messages. | |
785 | .TP | |
786 | .B m | |
787 | Key management: loading keys and checking for file modifications. | |
37941236 | 788 | .TP |
789 | .B l | |
790 | Display information about challenge issuing and verification. | |
791 | .TP | |
792 | .B p | |
793 | Display contents of packets sent and received by the tunnel and/or peer | |
794 | modules. | |
795 | .TP | |
796 | .B c | |
797 | Display inputs, outputs and intermediate results of cryptographic | |
798 | operations. This includes plaintext and key material. Use with | |
799 | caution. | |
800 | .TP | |
801 | .B A | |
802 | All of the above. | |
d6623498 | 803 | .PP |
804 | Note that the | |
805 | .B p | |
806 | (packet contents) | |
807 | and | |
808 | .B c | |
809 | (crypto details) | |
810 | outputs provide extra detail for other outputs. Specifying | |
811 | .B p | |
812 | without | |
37941236 | 813 | .BR r |
d6623498 | 814 | or |
815 | .B t | |
816 | isn't useful; neither is specifying | |
817 | .B c | |
818 | without one of | |
819 | .BR s , | |
37941236 | 820 | .BR l , |
d6623498 | 821 | .B x |
822 | or | |
823 | .BR m . | |
824 | .RE | |
13a55605 | 825 | .SP |
060ca767 | 826 | .B "TUNNELS" |
827 | For each available tunnel driver, an | |
828 | .B INFO | |
829 | line is printed giving its name. | |
13a55605 | 830 | .SP |
060ca767 | 831 | .B "VERSION" |
832 | Causes the server to emit an | |
833 | .B INFO | |
83487ded | 834 | line stating its software version, as two tokens: the server name, and |
060ca767 | 835 | its version string. The server name |
836 | .B tripe | |
837 | is reserved to the Straylight/Edgeware implementation. | |
13a55605 | 838 | .SP |
3cdc3f3a | 839 | .BR "WATCH " [\fIoptions\fP] |
bdc44f5b | 840 | Enables or disables asynchronous broadcasts |
3cdc3f3a | 841 | .IR "for the current connection only" . |
060ca767 | 842 | See |
e04c2d50 | 843 | .B "Trace lists" |
3cdc3f3a | 844 | above. The default watch state for the connection the server opens |
845 | automatically on stdin/stdout is to show warnings and trace messages; | |
bdc44f5b MW |
846 | other connections show no asynchronous broadcast messages. (This is |
847 | done in order to guarantee that a program reading the server's stdout | |
848 | does not miss any warnings.) | |
3cdc3f3a | 849 | .RS |
850 | .PP | |
060ca767 | 851 | Message types provided are: |
3cdc3f3a | 852 | .TP |
853 | .B t | |
854 | .B TRACE | |
855 | messages. | |
856 | .TP | |
857 | .B n | |
858 | .B NOTE | |
859 | messages. | |
860 | .TP | |
861 | .B w | |
862 | .B WARN | |
863 | messages. | |
864 | .TP | |
37941236 | 865 | .B A |
3cdc3f3a | 866 | All of the above. |
867 | .RE | |
13a55605 | 868 | .SP |
bd58d532 | 869 | .BI "WARN " tokens\fR... |
e04c2d50 | 870 | Issues a |
bd58d532 | 871 | .B USER |
872 | warning to all interested administration clients. | |
fc916a09 MW |
873 | . |
874 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 875 | .SH "ERROR MESSAGES" |
fc916a09 | 876 | . |
13a55605 | 877 | .\"* 20 Error messages (FAIL codes) |
3cdc3f3a | 878 | The following |
879 | .B FAIL | |
de014da6 | 880 | (or |
881 | .BR BGFAIL ) | |
3cdc3f3a | 882 | messages are sent to clients as a result of errors during command |
883 | processing. | |
13a55605 | 884 | .SP |
3cdc3f3a | 885 | .BI "already-daemon" |
886 | (For | |
887 | .BR DAEMON .) | |
888 | The | |
889 | .B tripe | |
890 | server is already running as a daemon. | |
13a55605 | 891 | .SP |
f43df819 | 892 | .BI "bad-addr-syntax " message |
37941236 | 893 | (For commands accepting socket addresses.) The address couldn't be |
894 | understood. | |
13a55605 | 895 | .SP |
f43df819 | 896 | .BI "bad-syntax " cmd " " message |
3cdc3f3a | 897 | (For any command.) The command couldn't be understood: e.g., the number |
898 | of arguments was wrong. | |
13a55605 | 899 | .SP |
83487ded | 900 | .BI "bad-time-spec " token |
0ba8de86 | 901 | The |
83487ded | 902 | .I token |
0ba8de86 | 903 | is not a valid time interval specification. Acceptable time |
e04c2d50 | 904 | specifications are nonnegative integers followed optionally by |
0ba8de86 | 905 | .BR d , |
906 | .BR h , | |
907 | .BR m , | |
908 | or | |
909 | .BR s , | |
910 | for days, hours, minutes, or seconds, respectively. | |
13a55605 | 911 | .SP |
3cdc3f3a | 912 | .BI "bad-trace-option " char |
913 | (For | |
914 | .BR TRACE .) | |
915 | An unknown trace option was requested. | |
13a55605 | 916 | .SP |
3cdc3f3a | 917 | .BI "bad-watch-option " char |
918 | (For | |
919 | .BR WATCH .) | |
920 | An unknown watch option was requested. | |
13a55605 | 921 | .SP |
f43df819 | 922 | .BI "daemon-error " ecode " " message |
3cdc3f3a | 923 | (For |
924 | .BR DAEMON .) | |
925 | An error occurred during the attempt to become a daemon, as reported by | |
926 | .IR message . | |
13a55605 | 927 | .SP |
3cdc3f3a | 928 | .BI "invalid-port " number |
929 | (For | |
930 | .BR ADD .) | |
931 | The given port number is out of range. | |
13a55605 | 932 | .SP |
bdc44f5b | 933 | .BI "not-service-provider " service |
e04c2d50 | 934 | (For |
bdc44f5b MW |
935 | .BR SVCRELEASE .) |
936 | The invoking client is not the current provider of the named | |
937 | .IR service , | |
938 | and is therefore not allowed to release it. | |
939 | .SP | |
3cdc3f3a | 940 | .BI "peer-create-fail " peer |
941 | (For | |
942 | .BR ADD .) | |
943 | Adding | |
944 | .I peer | |
945 | failed for some reason. A warning should have been emitted explaining | |
946 | why. | |
13a55605 | 947 | .SP |
c8e02c8a MW |
948 | .BI "peer-addr-exists " address\fR... |
949 | (For | |
950 | .BR ADD .) | |
951 | There is already a peer with the given | |
952 | .IR address . | |
953 | .SP | |
3cdc3f3a | 954 | .BI "peer-exists " peer |
955 | (For | |
956 | .BR ADD .) | |
957 | There is already a peer named | |
d6623498 | 958 | .IR peer . |
13a55605 | 959 | .SP |
0ba8de86 | 960 | .B "ping-send-failed" |
961 | The attempt to send a ping packet failed, probably due to lack of | |
962 | encryption keys. | |
13a55605 | 963 | .SP |
3cdc3f3a | 964 | .BI "resolve-error " hostname |
965 | (For | |
966 | .BR ADD .) | |
967 | The DNS name | |
968 | .I hostname | |
969 | could not be resolved. | |
13a55605 | 970 | .SP |
3cdc3f3a | 971 | .BI "resolver-timeout " hostname |
972 | (For | |
973 | .BR ADD .) | |
974 | The DNS name | |
975 | .I hostname | |
976 | took too long to resolve. | |
13a55605 | 977 | .SP |
bdc44f5b MW |
978 | .BI "service-exists " service " " version |
979 | (For | |
980 | .BR SVCCLAIM .) | |
981 | Another client is already providing the stated | |
982 | .I version | |
983 | of the | |
984 | .IR service . | |
985 | .SP | |
986 | .BI "service-too-old " service " " version | |
987 | (For | |
988 | .B SVCENSURE | |
989 | and | |
990 | .BR SVCSUBMIT .) | |
991 | Only the given | |
992 | .I version | |
993 | of the requested | |
994 | .I service | |
995 | is available, which does not meet the stated requirements. | |
996 | .SP | |
ff92ffd3 MW |
997 | .BI "tag-exists " tag |
998 | (For long-running commands.) The named | |
999 | .I tag | |
1000 | is already the tag of an outstanding job. | |
1001 | .SP | |
3cdc3f3a | 1002 | .BI "unknown-command " token |
1003 | The command | |
9df937a3 | 1004 | .I token |
78dcf842 | 1005 | was not recognized. |
13a55605 | 1006 | .SP |
72482dfa MW |
1007 | .BI "unknown-jobid " jobid |
1008 | (For | |
1009 | .BR SVCOK , | |
1010 | .BR SVCFAIL , | |
1011 | and | |
1012 | .BR SVCINFO .) | |
1013 | The token | |
1014 | .I jobid | |
1015 | is not recognized as identifying an outstanding job. It may have just | |
1016 | been cancelled. | |
1017 | .SP | |
3cdc3f3a | 1018 | .BI "unknown-peer " name |
1019 | (For | |
1020 | .BR ADDR , | |
1021 | .BR IFNAME , | |
1022 | .BR KILL , | |
64cf2223 | 1023 | .BR SETIFNAME , |
3cdc3f3a | 1024 | and |
1025 | .BR STATS .) | |
1026 | There is no peer called | |
1027 | .IR name . | |
13a55605 | 1028 | .SP |
fd68efa9 | 1029 | .BI "unknown-port " port |
3cdc3f3a | 1030 | (For |
1031 | .BR ADD .) | |
fd68efa9 MW |
1032 | The port name |
1033 | .I port | |
e04c2d50 | 1034 | couldn't be found in |
3cdc3f3a | 1035 | .BR /etc/services . |
ff92ffd3 | 1036 | .TP |
bdc44f5b MW |
1037 | .BI "unknown-service " service |
1038 | (For | |
1039 | .BR SVCENSURE , | |
1040 | .BR SVCQUERY , | |
1041 | .BR SVCRELEASE , | |
1042 | and | |
1043 | .BR SVCSUBMIT .) | |
1044 | The token | |
1045 | .I service | |
1046 | is not recognized as the name of a client-provided service. | |
1047 | .TP | |
ff92ffd3 MW |
1048 | .BI "unknown-tag " tag |
1049 | (For | |
1050 | .BR BGCANCEL .) | |
1051 | The given | |
1052 | .I tag | |
1053 | is not the tag for any outstanding background job. It may have just | |
1054 | finished. | |
fc916a09 MW |
1055 | . |
1056 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 1057 | .SH "NOTIFICATIONS" |
fc916a09 | 1058 | . |
13a55605 | 1059 | .\"* 30 Notification broadcasts (NOTE codes) |
3cdc3f3a | 1060 | The following notifications are sent to clients who request them. |
13a55605 | 1061 | .SP |
42da2a58 | 1062 | .BI "ADD " peer " " ifname " " address \fR... |
3cdc3f3a | 1063 | A new peer has been added. The peer's name is |
42da2a58 | 1064 | .IR peer , |
1065 | its tunnel is network interface | |
1066 | .IR ifname , | |
3cdc3f3a | 1067 | and its network address is |
1068 | .IR address . | |
13a55605 | 1069 | .SP |
3cdc3f3a | 1070 | .BI "DAEMON" |
1071 | The server has forked off into the sunset and become a daemon. | |
13a55605 | 1072 | .SP |
37941236 | 1073 | .BI "GREET " challenge " " address \fR... |
1074 | A valid greeting was received, with the given challenge (exactly as it | |
1075 | was returned by | |
1076 | .B GETCHAL | |
1077 | earlier). | |
13a55605 | 1078 | .SP |
d6623498 | 1079 | .BI "KILL " peer |
3cdc3f3a | 1080 | The peer |
1081 | .I peer | |
1082 | has been killed. | |
13a55605 | 1083 | .SP |
3cdc3f3a | 1084 | .BI "KXDONE " peer |
1085 | Key exchange with | |
1086 | .I peer | |
1087 | finished successfully. | |
13a55605 | 1088 | .SP |
3cdc3f3a | 1089 | .BI "KXSTART " peer |
1090 | Key exchange with | |
1091 | .I peer | |
1092 | has begun or restarted. If key exchange keeps failing, this message | |
1093 | will be repeated periodically. | |
13a55605 | 1094 | .SP |
6411163d MW |
1095 | .BI "NEWADDR " peer " " address |
1096 | The given mobile | |
1097 | .IR peer 's | |
1098 | IP address has been changed to | |
1099 | .IR address . | |
1100 | .SP | |
64cf2223 MW |
1101 | .BI "NEWIFNAME " peer " " old-name " " new-name |
1102 | The given | |
1103 | .IR peer 's | |
1104 | tunnel interface name has been changed from | |
1105 | .I old-name | |
1106 | to | |
1107 | .IR new-name , | |
1108 | as a result of a | |
1109 | .B SETIFNAME | |
1110 | command. | |
1111 | .SP | |
bdc44f5b MW |
1112 | .BI "SVCCLAIM " service " " version |
1113 | The named | |
1114 | .I service | |
1115 | is now available, at the stated | |
1116 | .IR version . | |
1117 | .SP | |
1118 | .BI "SVCRELEASE " service | |
1119 | The named | |
1120 | .I service | |
1121 | is no longer available. | |
1122 | .SP | |
bd58d532 | 1123 | .BI "USER " tokens\fR... |
1124 | An administration client issued a notification using the | |
1125 | .B NOTIFY | |
1126 | command. | |
fc916a09 MW |
1127 | . |
1128 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 1129 | .SH "WARNINGS" |
fc916a09 | 1130 | . |
13a55605 MW |
1131 | .\"* 40 Warning broadcasts (WARN codes) |
1132 | .\"+sep | |
3cdc3f3a | 1133 | There are many possible warnings. They are categorized according to |
1134 | their first tokens. | |
f43df819 MW |
1135 | .PP |
1136 | Many of these warnings report system errors. These are reported as a | |
1137 | pair of tokens, described below as | |
1138 | .I ecode | |
1139 | and | |
1140 | .IR message . | |
1141 | The | |
1142 | .I ecode | |
1143 | is a string of the form | |
1144 | .BI E number | |
1145 | giving the | |
1146 | .BR errno (3) | |
1147 | value of the error; the | |
1148 | .I message | |
1149 | is the `human-readable' form of the message, as reported by | |
1150 | .BR strerror (3). | |
3cdc3f3a | 1151 | .SS "ABORT warnings" |
1152 | These all indicate that the | |
d6623498 | 1153 | .B tripe |
3cdc3f3a | 1154 | server has become unable to continue. If enabled, the server will dump |
1155 | core in its configuration directory. | |
13a55605 | 1156 | .SP |
3cdc3f3a | 1157 | .BI "ABORT repeated-select-errors" |
1158 | The main event loop is repeatedly failing. If the server doesn't quit, | |
1159 | it will probably waste all available CPU doing nothing. | |
1160 | .SS "ADMIN warnings" | |
1161 | These indicate a problem with the administration socket interface. | |
13a55605 | 1162 | .SP |
f43df819 | 1163 | .BI "ADMIN accept-error " ecode " " message |
3cdc3f3a | 1164 | There was an error while attempting to accept a connection from a new |
1165 | client. | |
13a55605 | 1166 | .SP |
f43df819 | 1167 | .BI "ADMIN client-write-error " ecode " " message |
3cdc3f3a | 1168 | There was an error sending data to a client. The connection to the |
1169 | client has been closed. | |
37941236 | 1170 | .SS "CHAL warnings" |
1171 | These indicate errors in challenges, either in the | |
1172 | .B CHECKCHAL | |
1173 | command or in greeting packets. | |
13a55605 | 1174 | .SP |
37941236 | 1175 | .B "CHAL impossible-challenge" |
1176 | The server hasn't issued any challenges yet. Quite how anyone else | |
1177 | thought he could make one up is hard to imagine. | |
13a55605 | 1178 | .SP |
37941236 | 1179 | .B "CHAL incorrect-tag" |
1180 | Challenge received contained the wrong authentication data. It might be | |
1181 | very stale, or a forgery. | |
13a55605 | 1182 | .SP |
37941236 | 1183 | .B "CHAL invalid-challenge" |
1184 | Challenge received was the wrong length. We might have changed MAC | |
1185 | algorithms since the challenge was issued, or it might just be rubbish. | |
13a55605 | 1186 | .SP |
37941236 | 1187 | .B "CHAL replay duplicated-sequence" |
1188 | Challenge received was a definite replay of an old challenge. Someone's | |
1189 | up to something! | |
13a55605 | 1190 | .SP |
37941236 | 1191 | .B "CHAL replay old-sequence" |
1192 | Challenge received was old, but maybe not actually a replay. Try again. | |
3cdc3f3a | 1193 | .SS "KEYMGMT warnings" |
1194 | These indicate a problem with the keyring files, or the keys stored in | |
1195 | them. | |
13a55605 | 1196 | .SP |
f43df819 | 1197 | .BI "KEYMGMT bad-private-key " message |
3cdc3f3a | 1198 | The private key could not be read, or failed a consistency check. If |
1199 | there was a problem with the file, usually there will have been | |
1200 | .B key-file-error | |
1201 | warnings before this. | |
13a55605 | 1202 | .SP |
f43df819 | 1203 | .BI "KEYMGMT bad-public-keyring " message |
e04c2d50 | 1204 | The public keyring couldn't be read. Usually, there will have been |
3cdc3f3a | 1205 | .B key-file-error |
1206 | warnings before this. | |
13a55605 | 1207 | .SP |
f43df819 | 1208 | .BI "KEYMGMT key-file-error " file ":" line " " message |
3cdc3f3a | 1209 | Reports a specific error with the named keyring file. This probably |
1210 | indicates a bug in | |
1211 | .BR key (1). | |
13a55605 | 1212 | .SP |
3cdc3f3a | 1213 | .BI "KEYMGMT public-key " tag " " tokens\fR... |
1214 | These messages all indicate a problem with the public key named | |
1215 | .IR tag . | |
13a55605 | 1216 | .SP |
3cdc3f3a | 1217 | .BI "KEYMGMT public-key " tag " algorithm-mismatch" |
1218 | The algorithms specified on the public key don't match the ones for our | |
1219 | private key. All the peers in a network have to use the same | |
1220 | algorithms. | |
13a55605 | 1221 | .SP |
f43df819 | 1222 | .BI "KEYMGMT public-key " tag " bad " message |
3cdc3f3a | 1223 | The public key couldn't be read, or is invalid. |
13a55605 | 1224 | .SP |
3cdc3f3a | 1225 | .BI "KEYMGMT public-key " tag " bad-public-group-element" |
1226 | The public key is invalid. This may indicate a malicious attempt to | |
1227 | introduce a bogus key. | |
13a55605 | 1228 | .SP |
3cdc3f3a | 1229 | .BI "KEYMGMT public-key " tag " bad-algorithm-selection" |
1230 | The algorithms listed on the public key couldn't be understood. The | |
1231 | algorithm selection attributes are probably malformed and need fixing. | |
13a55605 | 1232 | .SP |
3cdc3f3a | 1233 | .BI "KEYMGMT public-key " tag " incorrect-group" |
1234 | The public key doesn't use the same group as our private key. All the | |
1235 | peers in a network have to use the same group. | |
13a55605 | 1236 | .SP |
3cdc3f3a | 1237 | .BI "KEYMGMT public-key " tag " not-found" |
1238 | The public key for peer | |
1239 | .I tag | |
1240 | wasn't in the public keyring. | |
13a55605 | 1241 | .SP |
3cdc3f3a | 1242 | .BI "KEYMGMT public-key " tag " unknown-type" |
1243 | The type of the public key isn't understood. Maybe you need to upgrade | |
1244 | your copy of | |
1245 | .BR tripe . | |
1246 | (Even if you do, you'll have to regenerate your keys.) | |
1247 | .SS "KX warnings" | |
1248 | These indicate problems during key-exchange. Many indicate either a bug | |
1249 | in the server (either yours or the remote one), or some kind of attack | |
1250 | in progress. All name a | |
1251 | .I peer | |
1252 | as the second token: this is the peer the packet is apparently from, | |
1253 | though it may have been sent by an attacker instead. | |
1254 | .PP | |
1255 | In the descriptions below, | |
1256 | .I msgtoken | |
1257 | is one of the tokens | |
1258 | .BR pre-challenge , | |
1259 | .BR cookie , | |
1260 | .BR challenge , | |
1261 | .BR reply , | |
1262 | .BR switch-rq , | |
1263 | or | |
1264 | .BR switch-ok . | |
13a55605 | 1265 | .SP |
3cdc3f3a | 1266 | .BI "KX " peer " bad-expected-reply-log" |
1267 | The challenges | |
1268 | .B tripe | |
1269 | uses in its protocol contain a check value which proves that the | |
1270 | challenge is honest. This message indicates that the check value | |
1271 | supplied is wrong: someone is attempting to use bogus challenges to | |
1272 | persuade your | |
1273 | .B tripe | |
1274 | server to leak private key information. No chance! | |
13a55605 | 1275 | .SP |
bd58d532 | 1276 | .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok" |
3cdc3f3a | 1277 | A symmetrically-encrypted portion of a key-exchange message failed to |
1278 | decrypt. | |
13a55605 | 1279 | .SP |
3cdc3f3a | 1280 | .BI "KX " peer " invalid " msgtoken |
1281 | A key-exchange message was malformed. This almost certainly indicates a | |
1282 | bug somewhere. | |
13a55605 | 1283 | .SP |
bd58d532 | 1284 | .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok" |
3cdc3f3a | 1285 | A message didn't contain the right magic data. This may be a replay of |
1286 | some old exchange, or random packets being sent in an attempt to waste | |
1287 | CPU. | |
13a55605 | 1288 | .SP |
3cdc3f3a | 1289 | .BI "KX " peer " public-key-expired" |
1290 | The peer's public key has expired. It's maintainer should have given | |
1291 | you a replacement before now. | |
13a55605 | 1292 | .SP |
3cdc3f3a | 1293 | .BI "KX " peer " sending-cookie" |
1294 | We've received too many bogus pre-challenge messages. Someone is trying | |
1295 | to flood us with key-exchange messages and make us waste CPU on doing | |
1296 | hard asymmetric crypto sums. | |
13a55605 | 1297 | .SP |
3cdc3f3a | 1298 | .BI "KX " peer " unexpected " msgtoken |
1299 | The message received wasn't appropriate for this stage of the key | |
1300 | exchange process. This may mean that one of our previous packets got | |
e04c2d50 | 1301 | lost. For |
3cdc3f3a | 1302 | .BR pre-challenge , |
1303 | it may simply mean that the peer has recently restarted. | |
13a55605 | 1304 | .SP |
3cdc3f3a | 1305 | .BI "KX " peer " unknown-challenge" |
1306 | The peer is asking for an answer to a challenge which we don't know | |
1307 | about. This may mean that we've been inundated with challenges from | |
1308 | some malicious source | |
1309 | .I who can read our messages | |
1310 | and discarded the valid one. | |
13a55605 | 1311 | .SP |
3cdc3f3a | 1312 | .BI "KX " peer " unknown-message 0x" nn |
1313 | An unknown key-exchange message arrived. | |
1314 | .SS "PEER warnings" | |
1315 | These are largely concerned with management of peers and the low-level | |
83487ded | 1316 | details of the network protocol. The second token is usually the name of |
e04c2d50 | 1317 | a peer, or |
3cdc3f3a | 1318 | .RB ` \- ' |
1319 | if none is relevant. | |
13a55605 | 1320 | .SP |
3cdc3f3a | 1321 | .BI "PEER " peer " bad-packet no-type" |
1322 | An empty packet arrived. This is very strange. | |
13a55605 | 1323 | .SP |
3cdc3f3a | 1324 | .BI "PEER " peer " bad-packet unknown-category 0x" nn |
1325 | The message category | |
1326 | .I nn | |
1327 | (in hex) isn't understood. Probably a strange random packet from | |
1328 | somewhere; could be an unlikely bug. | |
13a55605 | 1329 | .SP |
3cdc3f3a | 1330 | .BI "PEER " peer " bad-packet unknown-type 0x" nn |
1331 | The message type | |
1332 | .I nn | |
1333 | (in hex) isn't understood. Probably a strange random packet from | |
1334 | somewhere; could be an unlikely bug. | |
13a55605 | 1335 | .SP |
0ba8de86 | 1336 | .BI "PEER " peer " corrupt-encrypted-ping" |
1337 | The peer sent a ping response which matches an outstanding ping, but its | |
1338 | payload is wrong. There's definitely a bug somewhere. | |
13a55605 | 1339 | .SP |
0ba8de86 | 1340 | .BI "PEER " peer " corrupt-transport-ping" |
1341 | The peer (apparently) sent a ping response which matches an outstanding | |
1342 | ping, but its payload is wrong. Either there's a bug, or the bad guys | |
1343 | are playing tricks on you. | |
13a55605 | 1344 | .SP |
3cdc3f3a | 1345 | .BI "PEER " peer " decrypt-failed" |
1346 | An encrypted IP packet failed to decrypt. It may have been mangled in | |
1347 | transit, or may be a very old packet from an expired previous session | |
1348 | key. There is usually a considerable overlap in the validity periods of | |
1349 | successive session keys, so this shouldn't occur unless the key exchange | |
1350 | takes ages or fails. | |
13a55605 | 1351 | .SP |
0ba8de86 | 1352 | .BI "PEER " peer " malformed-encrypted-ping" |
1353 | The peer sent a ping response which is hopelessly invalid. There's | |
1354 | definitely a bug somewhere. | |
13a55605 | 1355 | .SP |
0ba8de86 | 1356 | .BI "PEER " peer " malformed-transport-ping" |
1357 | The peer (apparently) sent a ping response which is hopelessly invalid. | |
1358 | Either there's a bug, or the bad guys are playing tricks on you. | |
13a55605 | 1359 | .SP |
3cdc3f3a | 1360 | .BI "PEER " peer " packet-build-failed" |
1361 | There wasn't enough space in our buffer to put the packet we wanted to | |
1362 | send. Shouldn't happen. | |
13a55605 | 1363 | .SP |
f43df819 | 1364 | .BI "PEER \- socket-read-error " ecode " " message |
3cdc3f3a | 1365 | An error occurred trying to read an incoming packet. |
13a55605 | 1366 | .SP |
f43df819 | 1367 | .BI "PEER " peer " socket-write-error " ecode " " message |
3cdc3f3a | 1368 | An error occurred attempting to send a network packet. We lost that |
1369 | one. | |
13a55605 | 1370 | .SP |
0ba8de86 | 1371 | .BI "PEER " peer " unexpected-encrypted-ping 0x" id |
1372 | The peer sent an encrypted ping response whose id doesn't match any | |
1373 | outstanding ping. Maybe it was delayed for longer than the server was | |
1374 | willing to wait, or maybe the peer has gone mad. | |
13a55605 | 1375 | .SP |
0ba8de86 | 1376 | .BI "PEER \- unexpected-source " address\fR... |
1377 | A packet arrived from | |
1378 | .I address | |
1379 | (a network address \(en see above), but no peer is known at that | |
1380 | address. This may indicate a misconfiguration, or simply be a result of | |
1381 | one end of a connection being set up before the other. | |
13a55605 | 1382 | .SP |
0ba8de86 | 1383 | .BI "PEER " peer " unexpected-transport-ping 0x" id |
1384 | The peer (apparently) sent a transport ping response whose id doesn't | |
1385 | match any outstanding ping. Maybe it was delayed for longer than the | |
1386 | server was willing to wait, or maybe the peer has gone mad; or maybe | |
1387 | there are bad people trying to confuse you. | |
3cdc3f3a | 1388 | .SS "SERVER warnings" |
1389 | These indicate problems concerning the server process as a whole. | |
13a55605 | 1390 | .SP |
3cdc3f3a | 1391 | .BI "SERVER ignore signal " name |
1392 | A signal arrived, but the server ignored it. Currently this happens for | |
1393 | .B SIGHUP | |
1394 | because that's a popular way of telling daemons to re-read their | |
1395 | configuration files. Since | |
1396 | .B tripe | |
1397 | re-reads its keyrings automatically and has no other configuration | |
1398 | files, it's not relevant, but it seemed better to ignore the signal than | |
1399 | let the server die. | |
13a55605 | 1400 | .SP |
3cdc3f3a | 1401 | .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR] |
1402 | A signal arrived and | |
1403 | .B tripe | |
1404 | is going to quit. | |
13a55605 | 1405 | .SP |
3cdc3f3a | 1406 | .BI "SERVER quit admin-request" |
1407 | A client of the administration interface issued a | |
1408 | .B QUIT | |
1409 | command. | |
13a55605 | 1410 | .SP |
46dde080 MW |
1411 | .BI "SERVER quit foreground-eof" |
1412 | The server is running in foreground mode (the | |
1413 | .B \-F | |
1414 | option), and encountered end-of-file on standard input. | |
1415 | .SP | |
f43df819 | 1416 | .BI "SERVER select-error " ecode " " message |
3cdc3f3a | 1417 | An error occurred in the server's main event loop. This is bad: if it |
1418 | happens too many times, the server will abort. | |
1419 | .SS "SYMM warnings" | |
1420 | These are concerned with the symmetric encryption and decryption | |
1421 | process. | |
13a55605 | 1422 | .SP |
3cdc3f3a | 1423 | .BI "SYMM replay old-sequence" |
1424 | A packet was received with an old sequence number. It may just have | |
1425 | been delayed or duplicated, or it may have been an attempt at a replay | |
1426 | attack. | |
13a55605 | 1427 | .SP |
3cdc3f3a | 1428 | .BI "SYMM replay duplicated-sequence" |
1429 | A packet was received with a sequence number we've definitely seen | |
1430 | before. It may be an accidental duplication because the 'net is like | |
1431 | that, or a deliberate attempt at a replay. | |
1432 | .SS "TUN warnings" | |
1433 | These concern the workings of the system-specific tunnel driver. The | |
83487ded | 1434 | second token is the name of the tunnel interface in question, or |
3cdc3f3a | 1435 | .RB ` \- ' |
1436 | if none. | |
13a55605 | 1437 | .SP |
3cdc3f3a | 1438 | .BI "TUN \- bsd no-tunnel-devices" |
1439 | The driver couldn't find an available tunnel device. Maybe if you | |
e04c2d50 | 1440 | create some more |
3cdc3f3a | 1441 | .BI /dev/tun nn |
1442 | files, it will work. | |
13a55605 | 1443 | .SP |
72917fe7 | 1444 | .BI "TUN \- " tun-name " open-error " device " " ecode " " message |
3cdc3f3a | 1445 | An attempt to open the tunnel device file |
1446 | .I device | |
1447 | failed. | |
13a55605 | 1448 | .SP |
f43df819 | 1449 | .BI "TUN \- linux config-error " ecode " " message |
3cdc3f3a | 1450 | Configuring the Linux TUN/TAP interface failed. |
13a55605 | 1451 | .SP |
f43df819 | 1452 | .BI "TUN " ifname " " tun-name " read-error " ecode " " message |
42da2a58 | 1453 | Reading from the tunnel device failed. |
13a55605 | 1454 | .SP |
898975ee MW |
1455 | .BI "TUN " ifname " " tun-name " write-error " ecode " " message |
1456 | Writing from the tunnel device failed. | |
1457 | .SP | |
42da2a58 | 1458 | .BI "TUN " ifname " slip bad-escape" |
1459 | The SLIP driver encountered a escaped byte it wasn't expecting to see. | |
1460 | The erroneous packet will be ignored. | |
13a55605 | 1461 | .SP |
b9066fbb | 1462 | .BI "TUN " ifname " slip eof" |
1463 | The SLIP driver encountered end-of-file on its input descriptor. | |
1464 | Pending data is discarded, and no attempt is made to read any more data | |
1465 | from that interface ever. | |
13a55605 | 1466 | .SP |
b9066fbb | 1467 | .BI "TUN " ifname " slip escape-end" |
1468 | The SLIP driver encountered an escaped `end' marker. This probably | |
1469 | means that someone's been sending it junk. The erroneous packet is | |
1470 | discarded, and we hope that we've rediscovered synchronization. | |
13a55605 | 1471 | .SP |
f43df819 | 1472 | .BI "TUN \- slip fork-error " ecode " " message |
42da2a58 | 1473 | The SLIP driver encountered an error forking a child process while |
1474 | allocating a new dynamic interface. | |
13a55605 | 1475 | .SP |
42da2a58 | 1476 | .BI "TUN \- slip no-slip-interfaces" |
1477 | The driver ran out of static SLIP interfaces. Either preallocate more, | |
1478 | or use dynamic SLIP interface allocation. | |
13a55605 | 1479 | .SP |
b9066fbb | 1480 | .BI "TUN " ifname " slip overflow" |
1481 | The SLIP driver gave up reading a packet because it got too large. | |
13a55605 | 1482 | .SP |
f43df819 | 1483 | .BI "TUN \- slip pipe-error " ecode " " message |
42da2a58 | 1484 | The SLIP driver encountered an error creating pipes while allocating a |
1485 | new dynamic interface. | |
13a55605 | 1486 | .SP |
f43df819 | 1487 | .BI "TUN \- slip read-ifname-failed " ecode " " message |
42da2a58 | 1488 | The SLIP driver encountered an error reading the name of a dynamically |
1489 | allocated interface. Maybe the allocation script is broken. | |
13a55605 | 1490 | .SP |
f43df819 | 1491 | .BI "TUN \- unet config-error " ecode " " message |
42da2a58 | 1492 | Configuring the Linux Unet interface failed. Unet is obsolete and |
1493 | shouldn't be used any more. | |
13a55605 | 1494 | .SP |
f43df819 | 1495 | .BI "TUN \- unet getinfo-error " ecode " " message |
42da2a58 | 1496 | Reading information about the Unet interface failed. Unet is obsolete |
1497 | and shouldn't be used any more. | |
bd58d532 | 1498 | .SS "USER warnings" |
1499 | These are issued by administration clients using the | |
1500 | .B WARN | |
1501 | command. | |
13a55605 | 1502 | .SP |
bd58d532 | 1503 | .BI "USER " tokens\fR... |
1504 | An administration client issued a warning. | |
13a55605 | 1505 | .\"-sep |
fc916a09 MW |
1506 | . |
1507 | .\"-------------------------------------------------------------------------- | |
13a55605 | 1508 | .SH "SUMMARY" |
fc916a09 | 1509 | . |
13a55605 MW |
1510 | .SS "Command responses" |
1511 | .nf | |
2acd7cd6 | 1512 | .BI "BGDETACH " tag |
13a55605 MW |
1513 | .BI "BGFAIL " tag " " tokens \fR... |
1514 | .BI "BGINFO " tag " " tokens \fR... | |
1515 | .BI "BGOK " tag | |
1516 | .BI "FAIL " tokens \fR... | |
1517 | .BI "INFO " tokens \fR... | |
1518 | .B OK | |
1519 | .fi | |
1520 | .\"= summary | |
fc916a09 MW |
1521 | . |
1522 | .\"-------------------------------------------------------------------------- | |
d6623498 | 1523 | .SH "SEE ALSO" |
fc916a09 | 1524 | . |
d6623498 | 1525 | .BR tripectl (1), |
1526 | .BR tripe (8). | |
1527 | .PP | |
3cdc3f3a | 1528 | .IR "The Trivial IP Encryption Protocol" . |
fc916a09 MW |
1529 | . |
1530 | .\"-------------------------------------------------------------------------- | |
d6623498 | 1531 | .SH "AUTHOR" |
fc916a09 | 1532 | . |
d36eda2a | 1533 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
1534 | . |
1535 | .\"----- That's all, folks -------------------------------------------------- |