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 | .\" | |
11ad66c2 MW |
12 | .\" TrIPE is free software: you can redistribute it and/or modify it under |
13 | .\" the terms of the GNU General Public License as published by the Free | |
14 | .\" Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
fc916a09 | 16 | .\" |
11ad66c2 MW |
17 | .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
fc916a09 MW |
21 | .\" |
22 | .\" You should have received a copy of the GNU General Public License | |
11ad66c2 | 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
fc916a09 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
0647ba7c | 29 | .TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
32 | .SH "NAME" | |
33 | . | |
d6623498 | 34 | tripe-admin \- administrator commands for TrIPE |
fc916a09 MW |
35 | . |
36 | .\"-------------------------------------------------------------------------- | |
37 | .SH "DESCRIPTION" | |
38 | . | |
d6623498 | 39 | This manual page describes the administration interface provided by the |
40 | .BR tripe (8) | |
41 | daemon. | |
42 | .PP | |
43 | The | |
44 | .BR tripectl (8) | |
45 | program can be used either interactively or in scripts to communicate | |
46 | with the server using this interface. Alternatively, simple custom | |
47 | clients can be written in scripting languages such as Perl, Python or | |
48 | Tcl, or more advanced clients such as GUI monitors can be written in C | |
49 | with little difficulty. | |
50 | .PP | |
37941236 | 51 | Administration commands use a textual protocol. Each client command or |
52 | server response consists of a line of ASCII text terminated by a single | |
53 | linefeed character. No command may be longer than 255 characters. | |
d6623498 | 54 | .SS "General structure" |
55 | Each command or response line consists of a sequence of | |
83487ded MW |
56 | whitespace-separated tokens. The number and nature of whitespace |
57 | characters separating two tokens in a client command is not significant; | |
58 | the server always uses a single space character. The first token in a | |
d6623498 | 59 | line is a |
60 | .I keyword | |
61 | identifying the type of command or response contained. Keywords in | |
62 | client commands are not case-sensitive; the server always uses uppercase | |
63 | for its keywords. | |
83487ded MW |
64 | .PP |
65 | In order to allow tokens to contain internal whitespace, a quoting | |
66 | mechanism is provided. Whitespace within matched pairs of quotes \(en | |
67 | either single | |
68 | .RB ` ' ' | |
69 | or double | |
70 | .RB ` """" ' | |
71 | \(en is considered to be internal. Any character (other than newline) | |
72 | may be escaped by preceding it with a backslash | |
73 | .RB ` \e ': | |
74 | in particular, this can be used to include quote characters. It is | |
75 | impossible for a token to contain a newline character. | |
76 | .PP | |
77 | On output, the server will use double quotes when necessary. | |
de014da6 | 78 | .SS "Simple commands" |
79 | For simple client command, the server responds with zero or more | |
d6623498 | 80 | .B INFO |
81 | lines, followed by either an | |
82 | .B OK | |
83 | line or a | |
84 | .B FAIL | |
85 | line. Each | |
86 | .B INFO | |
87 | provides information requested in the command. An | |
88 | .B OK | |
89 | response contains no further data. A | |
90 | .B FAIL | |
3cdc3f3a | 91 | code is followed by a machine-readable explanation of why the command |
d6623498 | 92 | failed. |
93 | .PP | |
de014da6 | 94 | Simple command processing is strictly synchronous: the server reads a |
95 | command, processes it, and responds, before reading the next command. | |
96 | All commands can be run as simple commands. Long-running commands | |
97 | (e.g., | |
98 | .B ADD | |
99 | and | |
100 | .BR PING ) | |
101 | block the client until they finish, but the rest of the server continues | |
bdc44f5b MW |
102 | running. See |
103 | .B "Background commands" | |
104 | to find out how to issue long-running commands without blocking. | |
105 | .SS "Asynchronous broadcasts" | |
106 | There are three types of asynchronous broadcast messages which aren't | |
107 | associated with any particular command. Clients can select which | |
108 | broadcast messages they're interested in using the | |
109 | .B WATCH | |
110 | command. | |
de014da6 | 111 | .PP |
112 | The | |
d6623498 | 113 | .B WARN |
3cdc3f3a | 114 | message contains a machine-readable message warning of an error |
d6623498 | 115 | encountered while processing a command, unexpected or unusual behaviour |
116 | by a peer, or a possible attack by an adversary. Under normal | |
de014da6 | 117 | conditions, the server shouldn't emit any warnings. |
118 | .PP | |
119 | The | |
d6623498 | 120 | .B TRACE |
3cdc3f3a | 121 | message contains a human-readable tracing message containing diagnostic |
d6623498 | 122 | information. Trace messages are controlled using the |
123 | .B \-T | |
124 | command-line option to the server, or the | |
125 | .B TRACE | |
126 | administration command (see below). Support for tracing can be disabled | |
127 | when the package is being configured, and may not be available in your | |
de014da6 | 128 | version. |
129 | .PP | |
130 | Finally, the | |
3cdc3f3a | 131 | .B NOTE |
132 | message is a machine-readable notification about some routine but | |
133 | interesting event such as creation or destruction of peers. | |
de014da6 | 134 | .SS "Background commands" |
135 | Some commands (e.g., | |
136 | .B ADD | |
137 | and | |
138 | .BR PING ) | |
139 | take a long time to complete. To prevent these long-running commands | |
140 | from tying up a server connection, they can be run in the background. | |
141 | Not all commands can be run like this: the ones that can provide a | |
142 | .B \-background | |
143 | option, which must be supplied with a | |
144 | .IR tag . | |
145 | .PP | |
146 | A command may fail before it starts running in the background. In this | |
147 | case, the server emits a | |
148 | .B FAIL | |
149 | response, as usual. To indicate that a command has started running in | |
150 | the background, the server emits a response of the form | |
151 | .BI "BGDETACH " tag \fR, | |
152 | where | |
153 | .I tag | |
154 | is the value passed to the | |
155 | .B \-background | |
156 | option. From this point on, the server is ready to process more | |
157 | commands and reply to them. | |
158 | .PP | |
159 | Responses to background commands are indicated by a line beginning with | |
e04c2d50 | 160 | one of the tokens |
de014da6 | 161 | .BR BGOK , |
162 | .BR BGFAIL , | |
163 | or | |
164 | .BR BGINFO , | |
e04c2d50 | 165 | followed by the command tag. These correspond to the |
de014da6 | 166 | .BR OK , |
167 | .BR FAIL , | |
168 | and | |
169 | .B INFO | |
170 | responses for simple commands: | |
171 | .B BGINFO | |
172 | indicates information from a background command which has not completed | |
173 | yet; and | |
174 | .B BGOK | |
175 | and | |
176 | .B BGFAIL | |
177 | indicates that a background command succeeded or failed, respectively. | |
178 | .PP | |
179 | A background command will never issue an | |
180 | .B OK | |
060ca767 | 181 | or |
9df937a3 | 182 | .B INFO |
060ca767 | 183 | response: it will always detach and then issue any |
184 | .B BGINFO | |
185 | lines followed by | |
de014da6 | 186 | .B BGOK |
187 | response. | |
bdc44f5b MW |
188 | .SS "Client-provided services" |
189 | .\"* 25 Service-related messages | |
190 | An administration client can provide services to other clients. | |
191 | Services are given names and versions. A client can attempt to | |
192 | .I claim | |
193 | a particular service by issuing the | |
194 | .B SVCCLAIM | |
195 | command. This may fail, for example, if some other client already | |
196 | provides the same or later version of the service. | |
197 | .PP | |
198 | Other clients can issue | |
199 | .I "service commands" | |
200 | using the | |
201 | .B "SVCSUBMIT" | |
202 | command; the service provider is expected to handle these commands and | |
203 | reply to them. | |
204 | .PP | |
205 | There are three important asynchronous messages which will be sent to | |
206 | service providers. | |
207 | .SP | |
208 | .BI "SVCCANCEL " jobid | |
209 | The named job has been cancelled, either because the issuing client has | |
210 | disconnected or explicitly cancelled the job using the | |
211 | .B BGCANCEL | |
212 | command. | |
213 | .SP | |
214 | .BI "SVCCLAIM " service " " version | |
215 | Another client has claimed a later version of the named | |
9df937a3 MW |
216 | .IR service . |
217 | The recipient is no longer the provider of this service. | |
bdc44f5b MW |
218 | .SP |
219 | .BI "SVCJOB " jobid " " service " " command " " args \fR... | |
220 | Announces the arrival of a new job. The | |
221 | .I jobid | |
222 | is a simple token consisting of alphanumeric characters which | |
223 | .B tripe | |
224 | uses to identify this job. | |
225 | .PP | |
226 | The service provider can reply to the job using the commands | |
227 | .BR SVCINFO , | |
228 | .B SVCOK | |
229 | and | |
230 | .BR SVCFAIL . | |
231 | The first of these sends an | |
232 | .B INFO | |
233 | response and leaves the job active; the other two send an | |
234 | .B OK | |
235 | or | |
236 | .B FAIL | |
237 | response respectively, and mark the job as being complete. | |
238 | .PP | |
239 | (Since | |
240 | .B SVCSUBMIT | |
241 | is a potentially long-running command, it can be run in the background. | |
242 | This detail is hidden from service providers: | |
243 | .B tripe | |
244 | will issue the corresponding | |
245 | .BR BG ... | |
246 | responses when appropriate.) | |
3cdc3f3a | 247 | .SS "Network addresses" |
83487ded | 248 | A network address is a sequence of tokens. The first is a token |
3cdc3f3a | 249 | identifying the network address family. The length of an address and |
83487ded | 250 | the meanings of the subsequent tokens depend on the address family. |
3cdc3f3a | 251 | Address family tokens are not case-sensitive on input; on output, they |
252 | are always in upper-case. | |
253 | .PP | |
870ff51a MW |
254 | The following address families are recognized. |
255 | .TP | |
256 | .BI "ANY " address " \fR[" port \fR] | |
257 | An address and port number for any supported address family. On output, | |
258 | .B tripe | |
259 | never uses this form. On input, the | |
260 | .I address | |
261 | is examined: if it is a numeric address for some recognized address | |
262 | family, then it is interpreted as such; otherwise it is looked up using | |
263 | the DNS (in the background). The background resolver's address-sorting | |
264 | rules apply, and | |
265 | .B tripe | |
266 | simply takes the first address in the returned list which is of a | |
267 | supported address family. Symbolic port numbers are permitted; if | |
268 | omitted, the default port 4070 is used. | |
3cdc3f3a | 269 | .TP |
165efde7 | 270 | .BI "INET " address " \fR[" port \fR] |
3cdc3f3a | 271 | An Internet socket, naming an IPv4 address and UDP port. On output, the |
870ff51a MW |
272 | .I address |
273 | is always in numeric dotted-quad form, and the | |
274 | .I port | |
275 | is given as a plain decimal number. On input, DNS hostnames and | |
276 | symbolic port names are permitted; if omitted, the default port 4070 is | |
277 | used. | |
47828bd9 MW |
278 | .TP |
279 | .BI "INET6 " address " \fR[" port \fR] | |
280 | An Internet socket, naming an IPv6 address and UDP port. On output, the | |
281 | .I address | |
282 | is always in numeric hex-and-colons form, and the | |
283 | .I port | |
284 | is given as a plain decimal number. On input, DNS hostnames and | |
285 | symbolic port names may be permitted, depending on how | |
286 | .B tripe | |
287 | was compiled; if omitted, the default port 4070 is used. | |
3cdc3f3a | 288 | .PP |
78dcf842 | 289 | If, on input, no recognized address family token is found, the following |
83487ded | 290 | tokens are assumed to represent an |
870ff51a | 291 | .B ANY |
2acd7cd6 | 292 | address. Addresses output by the server always have an address family |
870ff51a MW |
293 | token, and do not use |
294 | .BR ANY . | |
295 | .PP | |
296 | Name resolution never blocks the main server, but will block the | |
297 | requesting client, unless the command is run in the background. | |
060ca767 | 298 | .SS "Key-value output" |
299 | Some commands (e.g., | |
300 | .B STATS | |
301 | and | |
302 | .BR SERVINFO ) | |
303 | produce output in the form of | |
304 | .IB key = value | |
83487ded | 305 | pairs, one per token. Neither the |
060ca767 | 306 | .I key |
307 | nor the | |
308 | .I value | |
309 | contain spaces. | |
310 | .SS "Trace lists" | |
311 | Commands which enable or disable kinds of output (e.g., | |
312 | .B TRACE | |
313 | and | |
314 | .BR WATCH ) | |
315 | work in similar ways. They take a single optional argument, which | |
316 | consists of a string of letters selecting message types, optionally | |
317 | interspersed with | |
318 | .RB ` + ' | |
319 | to enable, or | |
320 | .RB ` \- ' | |
321 | to disable, the subsequently listed types. | |
322 | .PP | |
323 | If the argument is omitted, the available message types are displayed, | |
324 | one to an | |
325 | .B INFO | |
326 | line, in a fixed-column format. Column zero contains the key letter for | |
327 | selecting that message type; column one contains either a space or a | |
e04c2d50 | 328 | .RB ` + ' |
060ca767 | 329 | sign, if the message type is disabled or enabled respectively; and a |
330 | textual description of the message type begins at column 3 and continues | |
331 | to the end of the line. | |
332 | .PP | |
333 | Lowercase key letters control individual message types. Uppercase key | |
334 | letters control collections of message types. | |
fc916a09 MW |
335 | . |
336 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 337 | .SH "COMMAND REFERENCE" |
fc916a09 | 338 | . |
13a55605 | 339 | .\"* 10 Commands |
d6623498 | 340 | The commands provided are: |
13a55605 | 341 | .SP |
9986f0b5 | 342 | .BI "ADD \fR[" options "\fR] " peer " " address "\fR..." |
3cdc3f3a | 343 | Adds a new peer. The peer is given the name |
344 | .IR peer ; | |
345 | the peer's public key is assumed to be in the file | |
346 | .B keyring.pub | |
347 | (or whatever alternative file was specified in the | |
348 | .B \-K | |
349 | option on the command line). The | |
350 | .I address | |
351 | is the network address (see above for the format) at which the peer can | |
78dcf842 | 352 | be contacted. The following options are recognized. |
42da2a58 | 353 | .RS |
13a55605 | 354 | .\"+opts |
42da2a58 | 355 | .TP |
de014da6 | 356 | .BI "\-background " tag |
357 | Run the command in the background, using the given | |
358 | .IR tag . | |
359 | .TP | |
010e6f63 MW |
360 | .B "\-cork" |
361 | Don't send an immediate challenge to the peer; instead, wait until it | |
362 | sends us something before responding. | |
363 | .TP | |
067aa5f0 MW |
364 | .B "\-ephemeral" |
365 | The association with the peer is not intended to persist indefinitely. | |
136f3f44 | 366 | When a peer is killed, or the |
067aa5f0 | 367 | .BR tripe (8) |
136f3f44 | 368 | daemon is shut down, a |
067aa5f0 | 369 | .B bye |
136f3f44 | 370 | packet is to the peer(s). If a peer marked as ephemeral sends us a |
067aa5f0 MW |
371 | .B bye |
372 | packet then it is killed (but in this case no further | |
373 | .B bye | |
136f3f44 MW |
374 | packet is sent). A |
375 | .B bye | |
376 | packet from a peer which isn't marked as ephemeral leaves the peer alone | |
377 | in the hope that the connection can be reestablished. | |
067aa5f0 | 378 | .TP |
0ba8de86 | 379 | .BI "\-keepalive " time |
380 | Send a no-op packet if we've not sent a packet to the peer in the last | |
381 | .I time | |
382 | interval. This is useful for persuading port-translating firewalls to | |
383 | believe that the `connection' is still active. The | |
384 | .I time | |
385 | is expressed as a nonnegative integer followed optionally by | |
386 | .BR d , | |
387 | .BR h , | |
388 | .BR m , | |
389 | or | |
390 | .BR s | |
391 | for days, hours, minutes, or seconds respectively; if no suffix is | |
392 | given, seconds are assumed. | |
393 | .TP | |
48b84569 MW |
394 | .BI "\-key " tag |
395 | Use the public key | |
396 | .I tag | |
397 | to authenticate the peer. The default is to use the key tagged | |
398 | .IR peer . | |
399 | .TP | |
8362ac1c MW |
400 | .BI "\-knock \fR[" prefix .\fR] tag |
401 | Send the string | |
402 | .RI [ prefix\fB. ] tag | |
403 | in | |
404 | .B token-rq | |
405 | and | |
406 | .B knock | |
407 | messages to the peer during key-exchange. The string as a whole should | |
408 | name the local machine to the peer, and | |
409 | .I tag | |
410 | should name its public key. When such messages are received from a | |
411 | currently unknown peer, | |
412 | .BR tripe (8) | |
413 | emits a | |
414 | .B KNOCK | |
415 | notification stating the peer's (claimed) name and address. The server | |
416 | will already have verified that the sender is using the peer's private | |
c60b5015 | 417 | key by this point. Prior to version 1.6.0, this option used to imply |
067aa5f0 | 418 | .BR \-ephemeral . |
8362ac1c | 419 | .TP |
6411163d MW |
420 | .B "\-mobile" |
421 | The peer is a mobile device, and is likely to change address rapidly. | |
422 | If a packet arrives from an unknown address, the server's usual response | |
423 | is to log a warning and discard it. If the server knows of any mobile | |
424 | peers, however, it will attempt to decrypt the packet using their keys, | |
425 | and if one succeeds, the server will update its idea of the peer's | |
426 | address and emit an | |
427 | .B NEWADDR | |
c60b5015 | 428 | notification. Prior to version 1.6.0, this option used to imply |
067aa5f0 | 429 | .BR \-ephemeral . |
6411163d | 430 | .TP |
e1f1a2a0 MW |
431 | .BI "\-priv " tag |
432 | Use the private key | |
433 | .I tag | |
434 | to authenticate to the peer. The default is to use the key named in the | |
435 | .RB ` \-t ' | |
436 | command-line option, or a key with type | |
437 | .B tripe | |
438 | or | |
439 | .BR tripe-dh : | |
440 | see | |
441 | .BR tripe (8) | |
442 | for the details. | |
443 | .TP | |
0ba8de86 | 444 | .BI "\-tunnel " tunnel |
42da2a58 | 445 | Use the named tunnel driver, rather than the default. |
13a55605 | 446 | .\"-opts |
42da2a58 | 447 | .RE |
13a55605 | 448 | .SP |
3cdc3f3a | 449 | .BI "ADDR " peer |
450 | Emits an | |
451 | .B INFO | |
452 | line reporting the IP address and port number stored for | |
453 | .IR peer . | |
13a55605 | 454 | .SP |
35c8b547 | 455 | .BI "ALGS \fR[" peer \fR] |
449991a3 | 456 | Emits information about the cryptographic algorithms in use, in |
35c8b547 MW |
457 | key-value form. If a |
458 | .I peer | |
459 | is given, then describe the algorithms used in the association with that | |
460 | peer; otherwise describe the default algorithms. | |
449991a3 | 461 | .RS |
35c8b547 MW |
462 | .PP |
463 | The keys are as follows. | |
449991a3 MW |
464 | .TP |
465 | .B kx-group | |
466 | Type of key-exchange group in use, currently either | |
467 | .B ec | |
468 | or | |
469 | .BR prime . | |
470 | .TP | |
471 | .B kx-group-order-bits | |
472 | Length of the group order, in bits. This gives an approximate measure | |
473 | of the group strength. | |
474 | .TP | |
475 | .B kx-group-elt-bits | |
476 | Length of a group element, in bits. This may be useful when analyzing | |
477 | protocol traces. | |
478 | .TP | |
479 | .B hash | |
480 | The hash function in use, e.g., | |
481 | .BR sha256 . | |
482 | .TP | |
483 | .B mgf | |
484 | The mask-generating function in use, e.g., | |
485 | .BR whirlpool-mgf . | |
486 | .TP | |
487 | .B hashsz | |
488 | The size of the hash function's output, in octets. | |
489 | .TP | |
a93aacce MW |
490 | .B bulk-transform |
491 | The name of the bulk-crypto transform. | |
492 | .TP | |
493 | .B bulk-overhead | |
494 | The amount of overhead, in bytes, caused by the crypto transform. | |
495 | .TP | |
449991a3 MW |
496 | .B cipher |
497 | The name of the bulk data cipher in use, e.g., | |
498 | .BR blowfish-cbc . | |
499 | .TP | |
500 | .B cipher-keysz | |
501 | The length of key used by the bulk data cipher, in octets. | |
502 | .TP | |
503 | .B cipher-blksz | |
504 | The block size of the bulk data cipher, or zero if it's not based on a | |
505 | block cipher. | |
506 | .TP | |
507 | .B cipher-data-limit | |
508 | The maximum amount of data to be encrypted using a single key. (A new | |
509 | key exchange is instigated well before the limit is reached, in order to | |
510 | allow for a seamless changeover of keys.) | |
511 | .TP | |
512 | .B mac | |
513 | The message authentication algorithm in use, e.g., | |
494a7ac0 | 514 | .BR ripemd160-hmac . |
449991a3 MW |
515 | .TP |
516 | .B mac-keysz | |
517 | The length of the key used by the message authentication algorithm, in | |
518 | octets. | |
519 | .TP | |
520 | .B mac-tagsz | |
521 | The length of the message authentication tag, in octets. | |
b87bffcb MW |
522 | .TP |
523 | .B blkc | |
524 | The block cipher in use, e.g., | |
525 | .BR blowfish . | |
526 | .TP | |
527 | .B blkc-keysz | |
528 | The length of key used by the block cipher, in octets. | |
529 | .TP | |
530 | .B blkc-blksz | |
531 | The block size of the block cipher. | |
449991a3 MW |
532 | .PP |
533 | The various sizes are useful, for example, when computing the MTU for a | |
534 | tunnel interface. If | |
535 | .I MTU | |
536 | is the MTU of the path to the peer, then the tunnel MTU should be | |
537 | .IP | |
538 | .I MTU | |
47828bd9 MW |
539 | \- |
540 | .I header-length | |
541 | \- 9 \- | |
a93aacce | 542 | .I bulk-overhead |
449991a3 | 543 | .PP |
47828bd9 MW |
544 | allowing |
545 | .I header-length | |
546 | = 20 (IPv4) or 40 (IPv6) bytes of IP header, 8 bytes of UDP header, a | |
547 | packet type octet, and the bulk-crypto transform overhead (which | |
548 | includes the sequence number). | |
449991a3 MW |
549 | .RE |
550 | .SP | |
ff92ffd3 MW |
551 | .BI "BGCANCEL " tag |
552 | Cancels the background job with the named | |
553 | .IR tag . | |
554 | .SP | |
37941236 | 555 | .BI "CHECKCHAL " challenge |
556 | Verifies a challenge as being one earlier issued by | |
557 | .B GETCHAL | |
558 | and not previously either passed to | |
559 | .B CHECKCHAL | |
560 | or in a greeting message. | |
13a55605 | 561 | .SP |
3cdc3f3a | 562 | .B "DAEMON" |
563 | Causes the server to disassociate itself from its terminal and become a | |
c37b77e0 | 564 | background task. This only works once. A notification is issued. |
2acd7cd6 | 565 | .SP |
0ba8de86 | 566 | .BI "EPING \fR[" options "\fR] " peer |
567 | Sends an encrypted ping to the peer, and expects an encrypted response. | |
568 | This checks that the peer is running (and not being impersonated), and | |
569 | that it can encrypt and decrypt packets correctly. Options and | |
570 | responses are the same as for the | |
571 | .B PING | |
572 | command. | |
13a55605 | 573 | .SP |
de014da6 | 574 | .BI "FORCEKX " peer |
575 | Requests the server to begin a new key exchange with | |
576 | .I peer | |
577 | immediately. | |
13a55605 | 578 | .SP |
37941236 | 579 | .B "GETCHAL" |
580 | Requests a challenge. The challenge is returned in an | |
581 | .B INFO | |
582 | line, as a base64-encoded string. See | |
583 | .BR CHECKCHAL . | |
13a55605 | 584 | .SP |
37941236 | 585 | .BI "GREET " peer " " challenge |
586 | Sends a greeting packet containing the | |
587 | .I challenge | |
588 | (base-64 encoded) to the named | |
589 | .IR peer . | |
590 | The expectation is that this will cause the peer to recognize us and | |
591 | begin a key-exchange. | |
13a55605 | 592 | .SP |
d6623498 | 593 | .B "HELP" |
594 | Causes the server to emit an | |
595 | .B INFO | |
596 | line for each command it supports. Each line lists the command name, | |
597 | followed by the names of the arguments. This may be helpful as a memory | |
598 | aid for interactive use, or for program clients probing for features. | |
e04c2d50 | 599 | .SP |
3cdc3f3a | 600 | .BI "IFNAME " peer |
601 | Emits an | |
602 | .B INFO | |
603 | line containing the name of the network interface used to collect IP | |
604 | packets which are to be encrypted and sent to | |
605 | .IR peer . | |
606 | Used by configuration scripts so that they can set up routing tables | |
607 | appropriately after adding new peers. | |
13a55605 | 608 | .SP |
ff92ffd3 MW |
609 | .B "JOBS" |
610 | Emits an | |
611 | .B INFO | |
612 | line giving the tag for each outstanding background job. | |
613 | .SP | |
3cdc3f3a | 614 | .BI "KILL " peer |
615 | Causes the server to forget all about | |
616 | .IR peer . | |
534d2649 MW |
617 | All keys are destroyed, and no more packets are sent. A |
618 | .B bye | |
619 | message is sent to the peer if it's marked as | |
620 | .B "\-ephemeral" | |
621 | \(en see the | |
622 | .B "ADD" | |
623 | command. | |
13a55605 | 624 | .SP |
3cdc3f3a | 625 | .B "LIST" |
626 | For each currently-known peer, an | |
627 | .B INFO | |
628 | line is written containing the peer's name, as given to | |
629 | .BR ADD . | |
13a55605 | 630 | .SP |
bd58d532 | 631 | .BI "NOTIFY " tokens\fR... |
e04c2d50 | 632 | Issues a |
bd58d532 | 633 | .B USER |
634 | notification to all interested administration clients. | |
13a55605 | 635 | .SP |
060ca767 | 636 | .BI "PEERINFO " peer |
637 | Returns information about a peer, in key-value form. The following keys | |
638 | are returned. | |
639 | .RS | |
640 | .TP | |
641 | .B tunnel | |
642 | The tunnel driver used for this peer. | |
643 | .TP | |
644 | .B keepalive | |
645 | The keepalive interval, in seconds, or zero if no keepalives are to be | |
646 | sent. | |
48b84569 | 647 | .TP |
8362ac1c MW |
648 | .B knock |
649 | If present, the string sent to the peer to set up the association; see | |
650 | the | |
651 | .B \-knock | |
652 | option to | |
653 | .BR ADD , | |
654 | and the | |
655 | .B KNOCK | |
656 | notification. | |
657 | .TP | |
48b84569 | 658 | .B key |
fe2a5dcf | 659 | The (short) key tag being used for the peer, as passed to the |
48b84569 | 660 | .B ADD |
fe2a5dcf MW |
661 | command. |
662 | .TP | |
663 | .B current-key | |
664 | The full key tag of the peer's public key currently being used. This | |
665 | may change during the life of the association. | |
666 | .TP | |
667 | .B private-key | |
668 | The private key tag being used for the peer, as passed to the | |
669 | .B ADD | |
f3c6d21c MW |
670 | command, or the |
671 | .RB ` \-t ' | |
672 | command-line option. If neither of these was given explicitly, the | |
673 | private key tag is shown as | |
674 | .RB ` (default) ', | |
675 | since there is no fixed tag used under these circumstances. | |
fe2a5dcf MW |
676 | .TP |
677 | .B current-private-key | |
678 | The full key tag of the private key currently being used for this | |
679 | association. This may change during the life of the association. | |
bd322830 MW |
680 | .TP |
681 | .B corked | |
682 | Either | |
683 | .B t | |
684 | or | |
685 | .B nil | |
686 | depending on whether or not (respectively) key-exchange is waiting for | |
687 | the peer to initiate. | |
688 | .TP | |
689 | .B mobile | |
690 | Either | |
691 | .B t | |
692 | or | |
693 | .B nil | |
694 | depending on whether or not (respectively) the peer is expected to | |
695 | change its address unpredictably. | |
067aa5f0 MW |
696 | .TP |
697 | .B ephemeral | |
698 | Either | |
699 | .B t | |
700 | or | |
701 | .B nil | |
702 | depending on whether the association with the peer is expected to be | |
703 | temporary or persistent (respectively). | |
060ca767 | 704 | .RE |
13a55605 | 705 | .SP |
0ba8de86 | 706 | .BI "PING \fR[" options "\fR] " peer |
707 | Send a transport-level ping to the peer. The ping and its response are | |
708 | not encrypted or authenticated. This command, possibly in conjunction | |
709 | with tracing, is useful for ensuring that UDP packets are actually | |
710 | flowing in both directions. See also the | |
711 | .B EPING | |
712 | command. | |
713 | .IP | |
714 | An | |
715 | .B INFO | |
716 | line is printed describing the outcome: | |
717 | .RS | |
718 | .TP | |
719 | .BI "ping-ok " millis | |
e04c2d50 | 720 | A response was received |
0ba8de86 | 721 | .I millis |
722 | after the ping was sent. | |
723 | .TP | |
724 | .BI "ping-timeout" | |
725 | No response was received within the time allowed. | |
726 | .TP | |
727 | .BI "ping-peer-died" | |
728 | The peer was killed (probably by another admin connection) before a | |
729 | response was received. | |
730 | .RE | |
731 | .IP | |
732 | Options recognized for this command are: | |
733 | .RS | |
13a55605 | 734 | .\"+opts |
0ba8de86 | 735 | .TP |
de014da6 | 736 | .BI "\-background " tag |
737 | Run the command in the background, using the given | |
738 | .IR tag . | |
739 | .TP | |
0ba8de86 | 740 | .BI "\-timeout " time |
741 | Wait for | |
742 | .I time | |
2acd7cd6 MW |
743 | seconds before giving up on a response. The default is 5 seconds. The |
744 | .I time | |
745 | is expressed as a nonnegative integer followed optionally by | |
746 | .BR d , | |
747 | .BR h , | |
748 | .BR m , | |
749 | or | |
750 | .BR s | |
751 | for days, hours, minutes, or seconds respectively; if no suffix is | |
752 | given, seconds are assumed. | |
13a55605 | 753 | .\"-opts |
0ba8de86 | 754 | .RE |
13a55605 | 755 | .SP |
3cdc3f3a | 756 | .B "PORT" |
5d06f63e | 757 | .RI [ family ] |
3cdc3f3a | 758 | Emits an |
759 | .B INFO | |
760 | line containing just the number of the UDP port used by the | |
761 | .B tripe | |
5d06f63e MW |
762 | server, for the given address |
763 | .I family | |
764 | (or one chosen arbitrarily if omitted -- though | |
765 | .B tripe | |
766 | tries to use the same port number consistently so this is not a likely | |
767 | problem in practice). If you've allowed your server to allocate a port | |
768 | dynamically, this is how to find out which one it chose. | |
13a55605 | 769 | .SP |
de014da6 | 770 | .B "RELOAD" |
771 | Instructs the server to recheck its keyring files. The server checks | |
772 | these periodically anyway but it may be necessary to force a recheck, | |
773 | for example after adding a new peer key. | |
13a55605 | 774 | .SP |
3cdc3f3a | 775 | .B "QUIT" |
776 | Instructs the server to exit immediately. A warning is sent. | |
13a55605 | 777 | .SP |
060ca767 | 778 | .B "SERVINFO" |
779 | Returns information about the server, in the form of key-value pairs. | |
780 | The following keys are used. | |
781 | .RS | |
782 | .TP | |
783 | .B implementation | |
784 | A keyword naming the implementation of the | |
785 | .BR tripe (8) | |
786 | server. The current implementation is called | |
787 | .BR edgeware-tripe . | |
788 | .TP | |
789 | .B version | |
790 | The server's version number, as reported by | |
791 | .BR VERSION . | |
792 | .TP | |
793 | .B daemon | |
794 | Either | |
795 | .B t | |
796 | or | |
797 | .BR nil , | |
798 | if the server has or hasn't (respectively) become a daemon. | |
799 | .RE | |
13a55605 | 800 | .SP |
64cf2223 MW |
801 | .BI "SETIFNAME " peer " " new-name |
802 | Informs the server that the | |
803 | .IR peer 's | |
804 | tunnel-interface name has been changed to | |
805 | .IR new-name . | |
806 | This is useful if firewalling decisions are made based on interface | |
807 | names: a setup script for a particular peer can change the name, and | |
808 | then update the server's records so that they're accurate. | |
809 | .SP | |
405fc4da MW |
810 | .BI "STATS " peer |
811 | Emits a number of | |
812 | .B INFO | |
813 | lines, each containing one or more statistics in the form | |
814 | .IB name = value \fR. | |
815 | The statistics-gathering is experimental and subject to change. | |
816 | .SP | |
bdc44f5b MW |
817 | .BI "SVCCLAIM " service " " version |
818 | Attempts to claim the named | |
819 | .IR service , | |
820 | offering the given | |
821 | .IR version . | |
822 | The claim is successful if the service is currently unclaimed, or if | |
823 | a version earlier than | |
824 | .I version | |
825 | is provided; otherwise the command fails with the error | |
826 | .BR "service-exists" . | |
827 | .SP | |
828 | .BI "SVCENSURE " service " \fR[" version \fR] | |
e04c2d50 | 829 | Ensure that |
bdc44f5b MW |
830 | .I service |
831 | is provided, and (if specified) to at least the given | |
832 | .IR version . | |
833 | An error is reported if these conditions are not met; otherwise the | |
834 | command succeeds silently. | |
835 | .SP | |
836 | .BI "SVCFAIL " jobid " " tokens \fR... | |
837 | Send a | |
838 | .B FAIL | |
839 | (or | |
840 | .BR BGFAIL ) | |
841 | response to the service job with the given | |
842 | .IR jobid , | |
e04c2d50 | 843 | passing the |
bdc44f5b MW |
844 | .I tokens |
845 | as the reason for failure. The job is closed. | |
846 | .SP | |
847 | .BI "SVCINFO " jobid " " tokens \fR... | |
848 | Send an | |
849 | .B INFO | |
850 | (or | |
851 | .BR BGINFO ) | |
852 | response to the service job with the given | |
853 | .IR jobid , | |
854 | passing the | |
855 | .I tokens | |
856 | as the info message. The job remains open. | |
857 | .SP | |
858 | .B "SVCLIST" | |
859 | Output a line of the form | |
860 | .RS | |
861 | .IP | |
862 | .B INFO | |
863 | .I service | |
864 | .I version | |
865 | .PP | |
866 | for each service currently provided. | |
867 | .RE | |
868 | .SP | |
869 | .BI "SVCOK " jobid | |
870 | Send an | |
871 | .B OK | |
872 | (or | |
873 | .BR BGINFO ) | |
874 | response to the service job with the given | |
875 | .IR jobid . | |
876 | The job is closed. | |
877 | .SP | |
878 | .BI "SVCQUERY " service | |
879 | Emits a number of | |
880 | .B info | |
881 | lines in key-value format, describing the named | |
882 | .IR service. | |
883 | The following keys are used. | |
884 | .RS | |
885 | .TP | |
886 | .B name | |
887 | The service's name. | |
888 | .TP | |
889 | .B version | |
890 | The service's version string. | |
891 | .RE | |
892 | .SP | |
893 | .BI "SVCRELEASE " service | |
894 | Announce that the client no longer wishes to provide the named | |
895 | .IR service . | |
896 | .SP | |
897 | .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR... | |
898 | Submit a job to the provider of the given | |
899 | .IR service , | |
900 | passing it the named | |
901 | .I command | |
902 | and the given | |
903 | .IR arguments . | |
904 | The following options are accepted. | |
905 | .RS | |
906 | .\"+opts | |
907 | .TP | |
908 | .BI "\-background " tag | |
909 | Run the command in the background, using the given | |
910 | .IR tag . | |
911 | .TP | |
912 | .BI "\-version " version | |
913 | Ensure that at least the given | |
914 | .I version | |
915 | of the service is available before submitting the job. | |
916 | .RE | |
917 | .\"-opts | |
918 | .SP | |
d6623498 | 919 | .BR "TRACE " [\fIoptions\fP] |
060ca767 | 920 | Selects trace outputs: see |
e04c2d50 | 921 | .B "Trace lists" |
060ca767 | 922 | above. Message types provided are: |
d6623498 | 923 | .RS |
2d752320 | 924 | .PP |
d6623498 | 925 | Currently, the following tracing options are supported: |
926 | .TP | |
927 | .B t | |
928 | Tunnel events: reception of packets to be encrypted, and injection of | |
929 | successfully-decrypted packets. | |
930 | .TP | |
931 | .B r | |
932 | Peer management events: creation and destruction of peer attachments, | |
933 | and arrival of messages. | |
934 | .TP | |
935 | .B a | |
936 | Administration interface: acceptance of new connections, and handling of | |
937 | the backgroud name-resolution required by the | |
938 | .B ADD | |
939 | command. | |
940 | .TP | |
d6623498 | 941 | .B s |
942 | Handling of symmetric keysets: creation and expiry of keysets, and | |
943 | encryption and decryption of messages. | |
944 | .TP | |
945 | .B x | |
946 | Key exchange: reception, parsing and emission of key exchange messages. | |
947 | .TP | |
948 | .B m | |
949 | Key management: loading keys and checking for file modifications. | |
37941236 | 950 | .TP |
951 | .B l | |
952 | Display information about challenge issuing and verification. | |
953 | .TP | |
954 | .B p | |
955 | Display contents of packets sent and received by the tunnel and/or peer | |
956 | modules. | |
957 | .TP | |
958 | .B c | |
959 | Display inputs, outputs and intermediate results of cryptographic | |
960 | operations. This includes plaintext and key material. Use with | |
961 | caution. | |
962 | .TP | |
963 | .B A | |
964 | All of the above. | |
d6623498 | 965 | .PP |
966 | Note that the | |
967 | .B p | |
968 | (packet contents) | |
969 | and | |
970 | .B c | |
971 | (crypto details) | |
972 | outputs provide extra detail for other outputs. Specifying | |
973 | .B p | |
974 | without | |
37941236 | 975 | .BR r |
d6623498 | 976 | or |
977 | .B t | |
978 | isn't useful; neither is specifying | |
979 | .B c | |
980 | without one of | |
981 | .BR s , | |
37941236 | 982 | .BR l , |
d6623498 | 983 | .B x |
984 | or | |
985 | .BR m . | |
986 | .RE | |
13a55605 | 987 | .SP |
060ca767 | 988 | .B "TUNNELS" |
989 | For each available tunnel driver, an | |
990 | .B INFO | |
991 | line is printed giving its name. | |
13a55605 | 992 | .SP |
060ca767 | 993 | .B "VERSION" |
994 | Causes the server to emit an | |
995 | .B INFO | |
83487ded | 996 | line stating its software version, as two tokens: the server name, and |
060ca767 | 997 | its version string. The server name |
998 | .B tripe | |
999 | is reserved to the Straylight/Edgeware implementation. | |
13a55605 | 1000 | .SP |
3cdc3f3a | 1001 | .BR "WATCH " [\fIoptions\fP] |
bdc44f5b | 1002 | Enables or disables asynchronous broadcasts |
3cdc3f3a | 1003 | .IR "for the current connection only" . |
060ca767 | 1004 | See |
e04c2d50 | 1005 | .B "Trace lists" |
3cdc3f3a | 1006 | above. The default watch state for the connection the server opens |
1007 | automatically on stdin/stdout is to show warnings and trace messages; | |
bdc44f5b MW |
1008 | other connections show no asynchronous broadcast messages. (This is |
1009 | done in order to guarantee that a program reading the server's stdout | |
1010 | does not miss any warnings.) | |
3cdc3f3a | 1011 | .RS |
1012 | .PP | |
060ca767 | 1013 | Message types provided are: |
3cdc3f3a | 1014 | .TP |
1015 | .B t | |
1016 | .B TRACE | |
1017 | messages. | |
1018 | .TP | |
1019 | .B n | |
1020 | .B NOTE | |
1021 | messages. | |
1022 | .TP | |
1023 | .B w | |
1024 | .B WARN | |
1025 | messages. | |
1026 | .TP | |
37941236 | 1027 | .B A |
3cdc3f3a | 1028 | All of the above. |
1029 | .RE | |
13a55605 | 1030 | .SP |
bd58d532 | 1031 | .BI "WARN " tokens\fR... |
e04c2d50 | 1032 | Issues a |
bd58d532 | 1033 | .B USER |
1034 | warning to all interested administration clients. | |
fc916a09 MW |
1035 | . |
1036 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 1037 | .SH "ERROR MESSAGES" |
fc916a09 | 1038 | . |
13a55605 | 1039 | .\"* 20 Error messages (FAIL codes) |
3cdc3f3a | 1040 | The following |
1041 | .B FAIL | |
de014da6 | 1042 | (or |
1043 | .BR BGFAIL ) | |
3cdc3f3a | 1044 | messages are sent to clients as a result of errors during command |
1045 | processing. | |
13a55605 | 1046 | .SP |
3cdc3f3a | 1047 | .BI "already-daemon" |
1048 | (For | |
1049 | .BR DAEMON .) | |
1050 | The | |
1051 | .B tripe | |
1052 | server is already running as a daemon. | |
13a55605 | 1053 | .SP |
f43df819 | 1054 | .BI "bad-addr-syntax " message |
37941236 | 1055 | (For commands accepting socket addresses.) The address couldn't be |
1056 | understood. | |
13a55605 | 1057 | .SP |
37d4c59e MW |
1058 | .BI "bad-base64 " message |
1059 | (For commands accepting Base64-encoded input.) The Base64-encoded | |
1060 | string was invalid. | |
1061 | .SP | |
f43df819 | 1062 | .BI "bad-syntax " cmd " " message |
3cdc3f3a | 1063 | (For any command.) The command couldn't be understood: e.g., the number |
1064 | of arguments was wrong. | |
13a55605 | 1065 | .SP |
83487ded | 1066 | .BI "bad-time-spec " token |
0ba8de86 | 1067 | The |
83487ded | 1068 | .I token |
0ba8de86 | 1069 | is not a valid time interval specification. Acceptable time |
e04c2d50 | 1070 | specifications are nonnegative integers followed optionally by |
0ba8de86 | 1071 | .BR d , |
1072 | .BR h , | |
1073 | .BR m , | |
1074 | or | |
1075 | .BR s , | |
1076 | for days, hours, minutes, or seconds, respectively. | |
13a55605 | 1077 | .SP |
3cdc3f3a | 1078 | .BI "bad-trace-option " char |
1079 | (For | |
1080 | .BR TRACE .) | |
1081 | An unknown trace option was requested. | |
13a55605 | 1082 | .SP |
3cdc3f3a | 1083 | .BI "bad-watch-option " char |
1084 | (For | |
1085 | .BR WATCH .) | |
1086 | An unknown watch option was requested. | |
13a55605 | 1087 | .SP |
f43df819 | 1088 | .BI "daemon-error " ecode " " message |
3cdc3f3a | 1089 | (For |
1090 | .BR DAEMON .) | |
1091 | An error occurred during the attempt to become a daemon, as reported by | |
1092 | .IR message . | |
13a55605 | 1093 | .SP |
47828bd9 MW |
1094 | .BI "disabled-address-family " afam |
1095 | (For | |
1096 | .B ADD | |
1097 | and | |
1098 | .BR PORT .) | |
1099 | The address family | |
1100 | .I afam | |
1101 | is supported, but was disabled using command-line arguments. | |
1102 | .SP | |
3cdc3f3a | 1103 | .BI "invalid-port " number |
1104 | (For | |
1105 | .BR ADD .) | |
1106 | The given port number is out of range. | |
13a55605 | 1107 | .SP |
bdc44f5b | 1108 | .BI "not-service-provider " service |
e04c2d50 | 1109 | (For |
bdc44f5b MW |
1110 | .BR SVCRELEASE .) |
1111 | The invoking client is not the current provider of the named | |
1112 | .IR service , | |
1113 | and is therefore not allowed to release it. | |
1114 | .SP | |
3cdc3f3a | 1115 | .BI "peer-create-fail " peer |
1116 | (For | |
1117 | .BR ADD .) | |
1118 | Adding | |
1119 | .I peer | |
1120 | failed for some reason. A warning should have been emitted explaining | |
1121 | why. | |
13a55605 | 1122 | .SP |
c8e02c8a MW |
1123 | .BI "peer-addr-exists " address\fR... |
1124 | (For | |
1125 | .BR ADD .) | |
1126 | There is already a peer with the given | |
1127 | .IR address . | |
1128 | .SP | |
3cdc3f3a | 1129 | .BI "peer-exists " peer |
1130 | (For | |
1131 | .BR ADD .) | |
1132 | There is already a peer named | |
d6623498 | 1133 | .IR peer . |
13a55605 | 1134 | .SP |
0ba8de86 | 1135 | .B "ping-send-failed" |
1136 | The attempt to send a ping packet failed, probably due to lack of | |
1137 | encryption keys. | |
13a55605 | 1138 | .SP |
75566d17 MW |
1139 | .B "provider-failed" |
1140 | (For | |
1141 | .BR SVCSUBMIT .) | |
1142 | The service provider disconnected without sending back a final reply to | |
1143 | the job. | |
1144 | .SP | |
1145 | .B "provider-overloaded" | |
1146 | (For | |
1147 | .BR SVCSUBMIT .) | |
1148 | The service provider has too many jobs queued up for it already. | |
1149 | .SP | |
3cdc3f3a | 1150 | .BI "resolve-error " hostname |
1151 | (For | |
1152 | .BR ADD .) | |
1153 | The DNS name | |
1154 | .I hostname | |
1155 | could not be resolved. | |
13a55605 | 1156 | .SP |
3cdc3f3a | 1157 | .BI "resolver-timeout " hostname |
1158 | (For | |
1159 | .BR ADD .) | |
1160 | The DNS name | |
1161 | .I hostname | |
1162 | took too long to resolve. | |
13a55605 | 1163 | .SP |
bdc44f5b MW |
1164 | .BI "service-exists " service " " version |
1165 | (For | |
1166 | .BR SVCCLAIM .) | |
1167 | Another client is already providing the stated | |
1168 | .I version | |
1169 | of the | |
1170 | .IR service . | |
1171 | .SP | |
1172 | .BI "service-too-old " service " " version | |
1173 | (For | |
1174 | .B SVCENSURE | |
1175 | and | |
1176 | .BR SVCSUBMIT .) | |
1177 | Only the given | |
1178 | .I version | |
1179 | of the requested | |
1180 | .I service | |
1181 | is available, which does not meet the stated requirements. | |
1182 | .SP | |
ff92ffd3 MW |
1183 | .BI "tag-exists " tag |
1184 | (For long-running commands.) The named | |
1185 | .I tag | |
1186 | is already the tag of an outstanding job. | |
1187 | .SP | |
5d06f63e MW |
1188 | .BI "unknown-address-family " afam |
1189 | (For | |
1190 | .BR PORT .) | |
1191 | The address family | |
1192 | .I afam | |
1193 | is unrecognized. | |
1194 | .SP | |
3cdc3f3a | 1195 | .BI "unknown-command " token |
1196 | The command | |
9df937a3 | 1197 | .I token |
78dcf842 | 1198 | was not recognized. |
13a55605 | 1199 | .SP |
72482dfa MW |
1200 | .BI "unknown-jobid " jobid |
1201 | (For | |
1202 | .BR SVCOK , | |
1203 | .BR SVCFAIL , | |
1204 | and | |
1205 | .BR SVCINFO .) | |
1206 | The token | |
1207 | .I jobid | |
1208 | is not recognized as identifying an outstanding job. It may have just | |
1209 | been cancelled. | |
1210 | .SP | |
3cdc3f3a | 1211 | .BI "unknown-peer " name |
1212 | (For | |
1213 | .BR ADDR , | |
1214 | .BR IFNAME , | |
1215 | .BR KILL , | |
64cf2223 | 1216 | .BR SETIFNAME , |
3cdc3f3a | 1217 | and |
1218 | .BR STATS .) | |
1219 | There is no peer called | |
1220 | .IR name . | |
13a55605 | 1221 | .SP |
fd68efa9 | 1222 | .BI "unknown-port " port |
3cdc3f3a | 1223 | (For |
1224 | .BR ADD .) | |
fd68efa9 MW |
1225 | The port name |
1226 | .I port | |
e04c2d50 | 1227 | couldn't be found in |
3cdc3f3a | 1228 | .BR /etc/services . |
dad7eebc | 1229 | .SP |
bdc44f5b MW |
1230 | .BI "unknown-service " service |
1231 | (For | |
1232 | .BR SVCENSURE , | |
1233 | .BR SVCQUERY , | |
1234 | .BR SVCRELEASE , | |
1235 | and | |
1236 | .BR SVCSUBMIT .) | |
1237 | The token | |
1238 | .I service | |
1239 | is not recognized as the name of a client-provided service. | |
dad7eebc | 1240 | .SP |
ff92ffd3 MW |
1241 | .BI "unknown-tag " tag |
1242 | (For | |
1243 | .BR BGCANCEL .) | |
1244 | The given | |
1245 | .I tag | |
1246 | is not the tag for any outstanding background job. It may have just | |
1247 | finished. | |
75566d17 MW |
1248 | .SP |
1249 | .BI "unknown-tunnel " tun | |
1250 | (For | |
1251 | .BR ADD .) | |
1252 | The given | |
1253 | .I tun | |
1254 | is not the name of any known tunnel driver. | |
fc916a09 MW |
1255 | . |
1256 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 1257 | .SH "NOTIFICATIONS" |
fc916a09 | 1258 | . |
13a55605 | 1259 | .\"* 30 Notification broadcasts (NOTE codes) |
3cdc3f3a | 1260 | The following notifications are sent to clients who request them. |
13a55605 | 1261 | .SP |
42da2a58 | 1262 | .BI "ADD " peer " " ifname " " address \fR... |
3cdc3f3a | 1263 | A new peer has been added. The peer's name is |
42da2a58 | 1264 | .IR peer , |
1265 | its tunnel is network interface | |
1266 | .IR ifname , | |
3cdc3f3a | 1267 | and its network address is |
1268 | .IR address . | |
13a55605 | 1269 | .SP |
3cdc3f3a | 1270 | .BI "DAEMON" |
1271 | The server has forked off into the sunset and become a daemon. | |
13a55605 | 1272 | .SP |
37941236 | 1273 | .BI "GREET " challenge " " address \fR... |
1274 | A valid greeting was received, with the given challenge (exactly as it | |
1275 | was returned by | |
1276 | .B GETCHAL | |
1277 | earlier). | |
13a55605 | 1278 | .SP |
d6623498 | 1279 | .BI "KILL " peer |
3cdc3f3a | 1280 | The peer |
1281 | .I peer | |
1282 | has been killed. | |
13a55605 | 1283 | .SP |
8362ac1c MW |
1284 | .BI "KNOCK " peer " " address |
1285 | The currently unknown | |
1286 | .I peer | |
1287 | is attempting to connect from | |
1288 | .IR address . | |
1289 | .SP | |
3cdc3f3a | 1290 | .BI "KXDONE " peer |
1291 | Key exchange with | |
1292 | .I peer | |
1293 | finished successfully. | |
13a55605 | 1294 | .SP |
3cdc3f3a | 1295 | .BI "KXSTART " peer |
1296 | Key exchange with | |
1297 | .I peer | |
1298 | has begun or restarted. If key exchange keeps failing, this message | |
1299 | will be repeated periodically. | |
13a55605 | 1300 | .SP |
6411163d MW |
1301 | .BI "NEWADDR " peer " " address |
1302 | The given mobile | |
1303 | .IR peer 's | |
1304 | IP address has been changed to | |
1305 | .IR address . | |
1306 | .SP | |
64cf2223 MW |
1307 | .BI "NEWIFNAME " peer " " old-name " " new-name |
1308 | The given | |
1309 | .IR peer 's | |
1310 | tunnel interface name has been changed from | |
1311 | .I old-name | |
1312 | to | |
1313 | .IR new-name , | |
1314 | as a result of a | |
1315 | .B SETIFNAME | |
1316 | command. | |
1317 | .SP | |
bdc44f5b MW |
1318 | .BI "SVCCLAIM " service " " version |
1319 | The named | |
1320 | .I service | |
1321 | is now available, at the stated | |
1322 | .IR version . | |
1323 | .SP | |
1324 | .BI "SVCRELEASE " service | |
1325 | The named | |
1326 | .I service | |
1327 | is no longer available. | |
1328 | .SP | |
bd58d532 | 1329 | .BI "USER " tokens\fR... |
1330 | An administration client issued a notification using the | |
1331 | .B NOTIFY | |
1332 | command. | |
fc916a09 MW |
1333 | . |
1334 | .\"-------------------------------------------------------------------------- | |
3cdc3f3a | 1335 | .SH "WARNINGS" |
fc916a09 | 1336 | . |
13a55605 MW |
1337 | .\"* 40 Warning broadcasts (WARN codes) |
1338 | .\"+sep | |
3cdc3f3a | 1339 | There are many possible warnings. They are categorized according to |
1340 | their first tokens. | |
f43df819 MW |
1341 | .PP |
1342 | Many of these warnings report system errors. These are reported as a | |
1343 | pair of tokens, described below as | |
1344 | .I ecode | |
1345 | and | |
1346 | .IR message . | |
1347 | The | |
1348 | .I ecode | |
1349 | is a string of the form | |
1350 | .BI E number | |
1351 | giving the | |
1352 | .BR errno (3) | |
1353 | value of the error; the | |
1354 | .I message | |
1355 | is the `human-readable' form of the message, as reported by | |
1356 | .BR strerror (3). | |
3cdc3f3a | 1357 | .SS "ABORT warnings" |
1358 | These all indicate that the | |
d6623498 | 1359 | .B tripe |
3cdc3f3a | 1360 | server has become unable to continue. If enabled, the server will dump |
1361 | core in its configuration directory. | |
13a55605 | 1362 | .SP |
3cdc3f3a | 1363 | .BI "ABORT repeated-select-errors" |
1364 | The main event loop is repeatedly failing. If the server doesn't quit, | |
1365 | it will probably waste all available CPU doing nothing. | |
ac3a27f5 MW |
1366 | .SP |
1367 | .BI "ABORT hash-size-too-large hash " name " size " sz " limit " max | |
1368 | An internal inconsistency: the hash function | |
1369 | .I name | |
1370 | produces a | |
1371 | .IR sz -byte | |
1372 | hash, but the server has been compiled to assume that no hash function | |
1373 | returns more than | |
1374 | .I max | |
1375 | bytes. | |
3cdc3f3a | 1376 | .SS "ADMIN warnings" |
1377 | These indicate a problem with the administration socket interface. | |
13a55605 | 1378 | .SP |
f43df819 | 1379 | .BI "ADMIN accept-error " ecode " " message |
3cdc3f3a | 1380 | There was an error while attempting to accept a connection from a new |
1381 | client. | |
13a55605 | 1382 | .SP |
f43df819 | 1383 | .BI "ADMIN client-write-error " ecode " " message |
3cdc3f3a | 1384 | There was an error sending data to a client. The connection to the |
1385 | client has been closed. | |
5ae728a6 MW |
1386 | .SP |
1387 | .BI "ADMIN admin-socket " path " already-in-use" | |
1388 | The server failed to create the Unix-domain socket object in the | |
1389 | filesystem, because there's already a socket there, and some other | |
1390 | process is actively listening for incoming connections. | |
1391 | .SP | |
1392 | .BI "ADMIN admin-socket " path " bind-failed " ecode " " message | |
1393 | The server failed to create the Unix-domain socket object in the | |
1394 | filesystem for an unusual reason. (The usual reason is | |
1395 | .BR EADDRINUSE , | |
1396 | but this is handled specially.) | |
1397 | .SP | |
1398 | .BI "ADMIN admin-socket " path " chmod-failed " ecode " " message | |
1399 | The server failed to set the correct permissions of the Unix-domain | |
1400 | socket object. | |
1401 | .SP | |
1402 | .BI "ADMIN admin-socket " path " chown-failed " ecode " " message | |
1403 | The server failed to set the correct ownership of the Unix-domain socket | |
1404 | object. | |
1405 | .SP | |
1406 | .BI "ADMIN admin-socket " path " create-failed " ecode " " message | |
1407 | The server failed to create its administration socket. This is usually | |
1408 | because some system resource is unavailable. | |
1409 | .SP | |
1410 | .BI "ADMIN admin-socket " path " listen-failed " ecode " " message | |
1411 | The server failed to arrange to receive incoming connections on its | |
1412 | Unix-domain socket. | |
1413 | .SP | |
1414 | .BI "ADMIN admin-socket " path " name-too-long" | |
1415 | The server can't create its administration socket, because the chosen | |
1416 | pathname | |
1417 | .I path | |
1418 | is too long. There is, for historical reasons, a rather tight limit on | |
1419 | the length of name permitted for Unix-domain sockets, usually around 108 | |
1420 | bytes. | |
1421 | .SP | |
1422 | .BI "ADMIN admin-socket " path " stat-failed " ecode " " message | |
1423 | The server failed to create the Unix-domain socket object in the | |
1424 | filesystem, because there's already something there, but the server | |
1425 | couldn't discover what. | |
1426 | .SP | |
1427 | .BI "ADMIN admin-socket " path " too-many-retries" | |
1428 | The server failed to create the Unix-domain socket object in the | |
1429 | filesystem. This error indicates that another process is also | |
1430 | repeatedly trying to create a Unix-domain socket at the same | |
1431 | .IR path , | |
1432 | and then failing to actually listen for connections on it, but the | |
1433 | server always loses the applicable race for some reason. This situation | |
1434 | merits investigation. | |
1435 | .SP | |
1436 | .BI "ADMIN adns-init-failed " ecode " " message | |
1437 | The server failed to initialize the ADNS asynchronous DNS-resolution | |
1438 | library. | |
37941236 | 1439 | .SS "CHAL warnings" |
1440 | These indicate errors in challenges, either in the | |
1441 | .B CHECKCHAL | |
1442 | command or in greeting packets. | |
13a55605 | 1443 | .SP |
37941236 | 1444 | .B "CHAL impossible-challenge" |
1445 | The server hasn't issued any challenges yet. Quite how anyone else | |
1446 | thought he could make one up is hard to imagine. | |
13a55605 | 1447 | .SP |
37941236 | 1448 | .B "CHAL incorrect-tag" |
1449 | Challenge received contained the wrong authentication data. It might be | |
1450 | very stale, or a forgery. | |
13a55605 | 1451 | .SP |
37941236 | 1452 | .B "CHAL invalid-challenge" |
1453 | Challenge received was the wrong length. We might have changed MAC | |
1454 | algorithms since the challenge was issued, or it might just be rubbish. | |
13a55605 | 1455 | .SP |
37941236 | 1456 | .B "CHAL replay duplicated-sequence" |
1457 | Challenge received was a definite replay of an old challenge. Someone's | |
1458 | up to something! | |
13a55605 | 1459 | .SP |
37941236 | 1460 | .B "CHAL replay old-sequence" |
1461 | Challenge received was old, but maybe not actually a replay. Try again. | |
3cdc3f3a | 1462 | .SS "KEYMGMT warnings" |
1463 | These indicate a problem with the keyring files, or the keys stored in | |
4d36660a MW |
1464 | them. The first token is either |
1465 | .B private-keyring | |
1466 | or | |
1467 | .B public-keyring | |
1468 | (notated | |
1469 | .IB which -keyring | |
1470 | in the descriptions below) indicating which keyring file is problematic, | |
1471 | and the second token is the filename of the keyring. Frequently a key | |
1472 | tag may be given next, preceded by the token | |
1473 | .BR key . | |
1474 | .SP | |
1475 | .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch" | |
1476 | A peer's public key doesn't request the same algorithms as our private | |
1477 | key. | |
1478 | .SP | |
1479 | .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len | |
1480 | The key attributes specify the length of MAC tag as | |
1481 | .I len | |
1482 | but this is an invalid value \(en either too large or not a multiple of | |
1483 | eight. | |
1484 | .SP | |
1485 | .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str | |
1486 | The key attributes contain | |
1487 | .I str | |
1488 | where a MAC tag length was expected. The key was generated wrongly. | |
1489 | .SP | |
424de4ea MW |
1490 | .BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key" |
1491 | The private key doesn't record the correct corresponding public key. | |
1492 | .SP | |
1493 | .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message | |
1494 | A system error occurred while opening or reading the keyring file. | |
1495 | .SP | |
4d36660a MW |
1496 | .BI "KEYMGMT private-keyring " file " key " tag " changed-group" |
1497 | The private keyring has been changed, but the new private key can't be | |
1498 | used because it uses a different group for Diffie\(enHellman key | |
1499 | exchange. | |
1500 | .SP | |
424de4ea MW |
1501 | .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash |
1502 | No message authentication code was given explicitly, and there's no | |
1503 | implementation of HMAC for the selected hash function | |
1504 | .IR hash . | |
4d36660a | 1505 | .SP |
a93aacce MW |
1506 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk |
1507 | The key specifies the use of an unknown bulk-crypto transform | |
1508 | .IR bulk . | |
1509 | Maybe the key was generated wrongly, or maybe the version of Catacomb | |
1510 | installed is too old. | |
1511 | .SP | |
4d36660a MW |
1512 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher |
1513 | The key specifies the use of an unknown symmetric encryption algorithm | |
1514 | .IR cipher . | |
1515 | Maybe the key was generated wrongly, or maybe the version of | |
1516 | Catacomb installed is too old. | |
1517 | .SP | |
1518 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type | |
1519 | The key specifies the use of a Diffie\(enHellman group of an unknown | |
1520 | .IR type . | |
1521 | Maybe the key was generated wrongly, or maybe the version of | |
1522 | .BR tripe (8) | |
1523 | is too old. | |
1524 | .SP | |
1525 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash | |
1526 | The key specifies the use of an unknown hash function | |
1527 | .IR hash . | |
1528 | Maybe the key was generated wrongly, or maybe the version of Catacomb | |
1529 | installed is too old. | |
1530 | .SP | |
1531 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac | |
1532 | The key specifies the use of an unknown message authentication code | |
1533 | .IR mac . | |
1534 | Maybe the key was generated wrongly, or maybe the version of Catacomb | |
1535 | installed is too old. | |
1536 | .SP | |
1537 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf | |
1538 | The key specifies the use of an unknown symmetric encryption function | |
1539 | .I mgf | |
1540 | for mask generation. Maybe the key was generated wrongly, or maybe the | |
1541 | version of Catacomb installed is too old. | |
1542 | .SP | |
07bdda1f MW |
1543 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser |
1544 | The key specifies the use of an unknown serialization format | |
1545 | .I ser | |
1546 | for hashing group elements. Maybe the key was generated wrongly, or | |
1547 | maybe the version of Catacomb installed is too old. | |
1548 | .SP | |
32b550bd MW |
1549 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad" |
1550 | The key specifies the use of an authenticated encryption scheme | |
1551 | .I cipher | |
1552 | which does not support the processing of additional authenticated data. | |
1553 | The most prominent examples of such schemes are the | |
1554 | .IB cipher -naclbox | |
1555 | collection, where | |
1556 | .I cipher | |
1557 | is | |
1558 | .BR salsa20 , | |
1559 | .BR salsa20/12 , | |
1560 | .BR salsa20/8 , | |
1561 | .BR chacha20 , | |
1562 | .BR chacha12 , | |
1563 | or | |
1564 | .BR chacha8 ; | |
1565 | use the | |
1566 | .B naclbox | |
1567 | bulk transform rather than | |
1568 | .B aead | |
1569 | for these | |
1570 | (or switch to the IETF | |
1571 | .IB cipher -poly1305 | |
1572 | schemes instead). | |
1573 | .SP | |
1574 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small" | |
1575 | The key specifies the use of an authenticated encryption scheme | |
1576 | .I cipher | |
1577 | which doesn't even allow a 5-byte (40-bit) nonce. Catacomb doesn't | |
1578 | implement any such limited AE schemes: you must be doing something | |
1579 | strange. | |
1580 | .SP | |
1581 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large" | |
1582 | The key specifies the use of an authenticated encryption scheme | |
1583 | .I cipher | |
1584 | which doesn't support any nonce size smaller than 64 bytes (512 bits). | |
1585 | Catacomb doesn't implement any such extravagant AE schemes: you must be | |
1586 | doing something strange. | |
1587 | .SP | |
1588 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message" | |
1589 | The key specifies the use of an authenticated encryption scheme | |
1590 | .I cipher | |
1591 | which produces ciphertext output even when given a completely empty | |
1592 | message. Catacomb doesn't implement any such unhelpful AE schemes: you | |
1593 | must be doing something strange. | |
4d36660a MW |
1594 | .SP |
1595 | .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz | |
1596 | The | |
1597 | .I alg | |
1598 | token is either | |
1599 | .B cipher | |
1600 | or | |
1601 | .BR mac . | |
1602 | The named algorithm requires more key material than the hash function | |
1603 | can provide. You must change either the hash function, or the cipher or | |
1604 | MAC. | |
13a55605 | 1605 | .SP |
4d36660a MW |
1606 | .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule" |
1607 | The cipher selected for mask-generation is unsuitable because it can't | |
1608 | accept arbitrary-sized keys. | |
13a55605 | 1609 | .SP |
4d36660a MW |
1610 | .BI "KEYMGMT " which "-keyring " file " key-not-found " tag |
1611 | A key named | |
3cdc3f3a | 1612 | .I tag |
4d36660a | 1613 | couldn't be found in the keyring. |
13a55605 | 1614 | .SP |
fb6a9f13 MW |
1615 | .BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid |
1616 | A key with the given | |
1617 | .I keyid | |
1618 | (in hex) was requested but not found. | |
1619 | .SP | |
4d36660a MW |
1620 | .BI "KEYMGMT " which "-keyring " file " line " line " " message |
1621 | The contents of the keyring file are invalid. There may well be a bug | |
1622 | in the | |
1623 | .BR key (1) | |
1624 | program. | |
3cdc3f3a | 1625 | .SS "KX warnings" |
1626 | These indicate problems during key-exchange. Many indicate either a bug | |
1627 | in the server (either yours or the remote one), or some kind of attack | |
1628 | in progress. All name a | |
1629 | .I peer | |
1630 | as the second token: this is the peer the packet is apparently from, | |
1631 | though it may have been sent by an attacker instead. | |
1632 | .PP | |
1633 | In the descriptions below, | |
1634 | .I msgtoken | |
1635 | is one of the tokens | |
1636 | .BR pre-challenge , | |
1637 | .BR cookie , | |
1638 | .BR challenge , | |
1639 | .BR reply , | |
1640 | .BR switch-rq , | |
3cdc3f3a | 1641 | .BR switch-ok . |
8362ac1c MW |
1642 | .BR token-rq , |
1643 | .BR token , | |
1644 | or | |
1645 | .BR knock . | |
13a55605 | 1646 | .SP |
35c8b547 MW |
1647 | .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag |
1648 | The algorithms specified in the peer's public key | |
1649 | .I pubtag | |
1650 | don't match the ones described in the private key | |
1651 | .IR privtag . | |
1652 | .SP | |
3cdc3f3a | 1653 | .BI "KX " peer " bad-expected-reply-log" |
1654 | The challenges | |
1655 | .B tripe | |
1656 | uses in its protocol contain a check value which proves that the | |
1657 | challenge is honest. This message indicates that the check value | |
1658 | supplied is wrong: someone is attempting to use bogus challenges to | |
1659 | persuade your | |
1660 | .B tripe | |
1661 | server to leak private key information. No chance! | |
13a55605 | 1662 | .SP |
bd58d532 | 1663 | .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok" |
3cdc3f3a | 1664 | A symmetrically-encrypted portion of a key-exchange message failed to |
1665 | decrypt. | |
13a55605 | 1666 | .SP |
3cdc3f3a | 1667 | .BI "KX " peer " invalid " msgtoken |
1668 | A key-exchange message was malformed. This almost certainly indicates a | |
1669 | bug somewhere. | |
13a55605 | 1670 | .SP |
bd58d532 | 1671 | .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok" |
3cdc3f3a | 1672 | A message didn't contain the right magic data. This may be a replay of |
1673 | some old exchange, or random packets being sent in an attempt to waste | |
1674 | CPU. | |
13a55605 | 1675 | .SP |
35c8b547 MW |
1676 | .BI "KX " peer " " which "-key-expired" |
1677 | The local private key or the peer's public key (distinguished by | |
1678 | .IR which ) | |
1679 | has expired. Either you or the peer's maintainer should have arranged | |
1680 | for a replacement before now. | |
13a55605 | 1681 | .SP |
3cdc3f3a | 1682 | .BI "KX " peer " sending-cookie" |
1683 | We've received too many bogus pre-challenge messages. Someone is trying | |
1684 | to flood us with key-exchange messages and make us waste CPU on doing | |
1685 | hard asymmetric crypto sums. | |
13a55605 | 1686 | .SP |
3cdc3f3a | 1687 | .BI "KX " peer " unexpected " msgtoken |
1688 | The message received wasn't appropriate for this stage of the key | |
1689 | exchange process. This may mean that one of our previous packets got | |
e04c2d50 | 1690 | lost. For |
3cdc3f3a | 1691 | .BR pre-challenge , |
1692 | it may simply mean that the peer has recently restarted. | |
13a55605 | 1693 | .SP |
3cdc3f3a | 1694 | .BI "KX " peer " unknown-challenge" |
1695 | The peer is asking for an answer to a challenge which we don't know | |
1696 | about. This may mean that we've been inundated with challenges from | |
1697 | some malicious source | |
1698 | .I who can read our messages | |
1699 | and discarded the valid one. | |
13a55605 | 1700 | .SP |
3cdc3f3a | 1701 | .BI "KX " peer " unknown-message 0x" nn |
1702 | An unknown key-exchange message arrived. | |
1703 | .SS "PEER warnings" | |
1704 | These are largely concerned with management of peers and the low-level | |
83487ded | 1705 | details of the network protocol. The second token is usually the name of |
e04c2d50 | 1706 | a peer, or |
3cdc3f3a | 1707 | .RB ` \- ' |
1708 | if none is relevant. | |
13a55605 | 1709 | .SP |
3cdc3f3a | 1710 | .BI "PEER " peer " bad-packet no-type" |
1711 | An empty packet arrived. This is very strange. | |
13a55605 | 1712 | .SP |
3cdc3f3a | 1713 | .BI "PEER " peer " bad-packet unknown-category 0x" nn |
1714 | The message category | |
1715 | .I nn | |
1716 | (in hex) isn't understood. Probably a strange random packet from | |
1717 | somewhere; could be an unlikely bug. | |
13a55605 | 1718 | .SP |
3cdc3f3a | 1719 | .BI "PEER " peer " bad-packet unknown-type 0x" nn |
1720 | The message type | |
1721 | .I nn | |
1722 | (in hex) isn't understood. Probably a strange random packet from | |
1723 | somewhere; could be an unlikely bug. | |
13a55605 | 1724 | .SP |
0ba8de86 | 1725 | .BI "PEER " peer " corrupt-encrypted-ping" |
1726 | The peer sent a ping response which matches an outstanding ping, but its | |
1727 | payload is wrong. There's definitely a bug somewhere. | |
13a55605 | 1728 | .SP |
0ba8de86 | 1729 | .BI "PEER " peer " corrupt-transport-ping" |
1730 | The peer (apparently) sent a ping response which matches an outstanding | |
1731 | ping, but its payload is wrong. Either there's a bug, or the bad guys | |
1732 | are playing tricks on you. | |
13a55605 | 1733 | .SP |
3cdc3f3a | 1734 | .BI "PEER " peer " decrypt-failed" |
1735 | An encrypted IP packet failed to decrypt. It may have been mangled in | |
1736 | transit, or may be a very old packet from an expired previous session | |
1737 | key. There is usually a considerable overlap in the validity periods of | |
1738 | successive session keys, so this shouldn't occur unless the key exchange | |
1739 | takes ages or fails. | |
13a55605 | 1740 | .SP |
0ba8de86 | 1741 | .BI "PEER " peer " malformed-encrypted-ping" |
1742 | The peer sent a ping response which is hopelessly invalid. There's | |
1743 | definitely a bug somewhere. | |
13a55605 | 1744 | .SP |
0ba8de86 | 1745 | .BI "PEER " peer " malformed-transport-ping" |
1746 | The peer (apparently) sent a ping response which is hopelessly invalid. | |
1747 | Either there's a bug, or the bad guys are playing tricks on you. | |
13a55605 | 1748 | .SP |
3cdc3f3a | 1749 | .BI "PEER " peer " packet-build-failed" |
1750 | There wasn't enough space in our buffer to put the packet we wanted to | |
1751 | send. Shouldn't happen. | |
13a55605 | 1752 | .SP |
f43df819 | 1753 | .BI "PEER \- socket-read-error " ecode " " message |
3cdc3f3a | 1754 | An error occurred trying to read an incoming packet. |
13a55605 | 1755 | .SP |
f43df819 | 1756 | .BI "PEER " peer " socket-write-error " ecode " " message |
3cdc3f3a | 1757 | An error occurred attempting to send a network packet. We lost that |
1758 | one. | |
13a55605 | 1759 | .SP |
56c76774 MW |
1760 | .BI "PEER " address\fR... " disabled-address-family" |
1761 | An attempt was made to send a packet to an address for which support was | |
1762 | switched off by command-line options. | |
1763 | .SP | |
8362ac1c MW |
1764 | .BI "PEER " address\fR... " socket-write-error " ecode " " message |
1765 | An error occurred attempting to send a network packet. We lost that | |
1766 | one. | |
1767 | .SP | |
5ae728a6 MW |
1768 | .BI "PEER \- udp-socket " address-family " bind-failed " ecode " " message |
1769 | The server failed to associate a UDP socket with a local address. | |
1770 | .SP | |
1771 | .BI "PEER \- udp-socket " address-family " create-failed " ecode " " message | |
1772 | The server failed to create a UDP socket for the | |
1773 | .IR address-family . | |
1774 | .SP | |
1775 | .BI "PEER \- udp-socket " address-family " read-local-address-failed " ecode " " message | |
1776 | The server failed to discover the local address for one of its own UDP | |
1777 | sockets. | |
1778 | .SP | |
1779 | .BI "PEER \- udp-socket " address-family " set-buffers-failed " ecode " " message | |
1780 | The server failed to configure appropriate buffer sizes on a UDP socket. | |
1781 | .SP | |
1782 | .BI "PEER \- udp-socket INET6 set-v6only-failed " ecode " " message | |
1783 | The server failed to configure an IPv6 socket not to try to collect IPv4 | |
1784 | traffic too. | |
1785 | .SP | |
0ba8de86 | 1786 | .BI "PEER " peer " unexpected-encrypted-ping 0x" id |
1787 | The peer sent an encrypted ping response whose id doesn't match any | |
1788 | outstanding ping. Maybe it was delayed for longer than the server was | |
1789 | willing to wait, or maybe the peer has gone mad. | |
13a55605 | 1790 | .SP |
0ba8de86 | 1791 | .BI "PEER \- unexpected-source " address\fR... |
1792 | A packet arrived from | |
1793 | .I address | |
1794 | (a network address \(en see above), but no peer is known at that | |
1795 | address. This may indicate a misconfiguration, or simply be a result of | |
1796 | one end of a connection being set up before the other. | |
13a55605 | 1797 | .SP |
0ba8de86 | 1798 | .BI "PEER " peer " unexpected-transport-ping 0x" id |
1799 | The peer (apparently) sent a transport ping response whose id doesn't | |
1800 | match any outstanding ping. Maybe it was delayed for longer than the | |
1801 | server was willing to wait, or maybe the peer has gone mad; or maybe | |
1802 | there are bad people trying to confuse you. | |
e8ea4061 MW |
1803 | .SS "PRIVSEP warnings" |
1804 | These indicate problems with the privilege-separation helper process. | |
1805 | (The server tries to drop its privileges when it starts up, leaving a | |
1806 | privileged helper process behind which will create and hand over tunnel | |
1807 | descriptors on request, but hopefully not do anything else especially | |
1808 | dangerous. Tunnel descriptors are not completely safe, but this is | |
1809 | probably better than nothing.) | |
1810 | .SP | |
1811 | .BI "PRIVSEP child-exited " rc | |
1812 | The helper process exited normally with status | |
1813 | .IR rc . | |
1814 | Status 0 means that it thought the server didn't want it any more; 1 | |
1815 | means that it was invoked incorrectly; 127 means that some system call | |
1816 | failed. | |
1817 | .SP | |
1818 | .BI "PRIVSEP child-killed " sig | |
1819 | The helper process was killed by signal number | |
1820 | .IR sig . | |
1821 | .SP | |
1822 | .BI "PRIVSEP child-died " status | |
1823 | The helper process died in some unexpected way; | |
1824 | .I status is the raw status code returned by | |
1825 | .BR waitpid (2), | |
1826 | because the server didn't understand how to decode it. | |
1827 | .SP | |
1828 | .BI "PRIVSEP helper-died" | |
1829 | A tunnel driver requires a tunnel descriptor from the helper, but the | |
1830 | helper isn't running so this won't work. | |
1831 | .SP | |
1832 | .BI "PRIVSEP helper-read-error " ecode " " message | |
1833 | The server failed to read a response from the helper process. | |
1834 | .SP | |
1835 | .BI "PRIVSEP helper-short-read" | |
1836 | The helper process didn't send back enough data, and has likely crashed. | |
1837 | .SP | |
1838 | .BI "PRIVSEP helper-write-error " ecode " " message | |
1839 | The server failed to send a message to the helper process. | |
1840 | .SP | |
1841 | .BI "PRIVSEP no-fd-from-helper" | |
1842 | The helper process sent back a positive response, but didn't include the | |
1843 | requested tunnel descriptor. | |
1844 | .SP | |
5ae728a6 MW |
1845 | .BI "PRIVSEP socketpair-create-failed " ecode " " message |
1846 | The server couldn't create the socketpair it's supposed to use to | |
1847 | communicate with the helper process. | |
1848 | .SP | |
e8ea4061 MW |
1849 | .BI "PRIVSEP unknown-response-code" |
1850 | The helper process sent back an incomprehensible reply. It's probably | |
1851 | very confused and may crash. | |
3cdc3f3a | 1852 | .SS "SERVER warnings" |
1853 | These indicate problems concerning the server process as a whole. | |
13a55605 | 1854 | .SP |
3cdc3f3a | 1855 | .BI "SERVER ignore signal " name |
1856 | A signal arrived, but the server ignored it. Currently this happens for | |
1857 | .B SIGHUP | |
1858 | because that's a popular way of telling daemons to re-read their | |
1859 | configuration files. Since | |
1860 | .B tripe | |
1861 | re-reads its keyrings automatically and has no other configuration | |
1862 | files, it's not relevant, but it seemed better to ignore the signal than | |
1863 | let the server die. | |
13a55605 | 1864 | .SP |
3cdc3f3a | 1865 | .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR] |
1866 | A signal arrived and | |
1867 | .B tripe | |
1868 | is going to quit. | |
13a55605 | 1869 | .SP |
3cdc3f3a | 1870 | .BI "SERVER quit admin-request" |
1871 | A client of the administration interface issued a | |
1872 | .B QUIT | |
1873 | command. | |
13a55605 | 1874 | .SP |
5ae728a6 MW |
1875 | .BI "SERVER daemon-error " ecode " " message |
1876 | The server failed to become a daemon during initialization. | |
1877 | .SP | |
46dde080 MW |
1878 | .BI "SERVER quit foreground-eof" |
1879 | The server is running in foreground mode (the | |
1880 | .B \-F | |
1881 | option), and encountered end-of-file on standard input. | |
1882 | .SP | |
f43df819 | 1883 | .BI "SERVER select-error " ecode " " message |
3cdc3f3a | 1884 | An error occurred in the server's main event loop. This is bad: if it |
1885 | happens too many times, the server will abort. | |
e8ea4061 MW |
1886 | .SP |
1887 | .BI "SERVER waitpid-error " ecode " " message | |
1888 | The server was informed that one of its child processes had exited, but | |
1889 | couldn't retrieve the child's status. | |
3cdc3f3a | 1890 | .SS "SYMM warnings" |
1891 | These are concerned with the symmetric encryption and decryption | |
1892 | process. | |
13a55605 | 1893 | .SP |
3cdc3f3a | 1894 | .BI "SYMM replay old-sequence" |
1895 | A packet was received with an old sequence number. It may just have | |
1896 | been delayed or duplicated, or it may have been an attempt at a replay | |
1897 | attack. | |
13a55605 | 1898 | .SP |
3cdc3f3a | 1899 | .BI "SYMM replay duplicated-sequence" |
1900 | A packet was received with a sequence number we've definitely seen | |
1901 | before. It may be an accidental duplication because the 'net is like | |
1902 | that, or a deliberate attempt at a replay. | |
1903 | .SS "TUN warnings" | |
1904 | These concern the workings of the system-specific tunnel driver. The | |
83487ded | 1905 | second token is the name of the tunnel interface in question, or |
3cdc3f3a | 1906 | .RB ` \- ' |
1907 | if none. | |
13a55605 | 1908 | .SP |
3cdc3f3a | 1909 | .BI "TUN \- bsd no-tunnel-devices" |
1910 | The driver couldn't find an available tunnel device. Maybe if you | |
e04c2d50 | 1911 | create some more |
3cdc3f3a | 1912 | .BI /dev/tun nn |
1913 | files, it will work. | |
13a55605 | 1914 | .SP |
72917fe7 | 1915 | .BI "TUN \- " tun-name " open-error " device " " ecode " " message |
3cdc3f3a | 1916 | An attempt to open the tunnel device file |
1917 | .I device | |
1918 | failed. | |
13a55605 | 1919 | .SP |
f43df819 | 1920 | .BI "TUN \- linux config-error " ecode " " message |
3cdc3f3a | 1921 | Configuring the Linux TUN/TAP interface failed. |
13a55605 | 1922 | .SP |
f43df819 | 1923 | .BI "TUN " ifname " " tun-name " read-error " ecode " " message |
42da2a58 | 1924 | Reading from the tunnel device failed. |
13a55605 | 1925 | .SP |
898975ee MW |
1926 | .BI "TUN " ifname " " tun-name " write-error " ecode " " message |
1927 | Writing from the tunnel device failed. | |
1928 | .SP | |
42da2a58 | 1929 | .BI "TUN " ifname " slip bad-escape" |
1930 | The SLIP driver encountered a escaped byte it wasn't expecting to see. | |
1931 | The erroneous packet will be ignored. | |
13a55605 | 1932 | .SP |
5ae728a6 MW |
1933 | .BI "TUN \- slip bad-interface-list" |
1934 | The interface list, in the | |
1935 | .B TRIPE_SLIPIF | |
1936 | environment variable, is malformed. | |
1937 | .SP | |
b9066fbb | 1938 | .BI "TUN " ifname " slip eof" |
1939 | The SLIP driver encountered end-of-file on its input descriptor. | |
1940 | Pending data is discarded, and no attempt is made to read any more data | |
1941 | from that interface ever. | |
13a55605 | 1942 | .SP |
b9066fbb | 1943 | .BI "TUN " ifname " slip escape-end" |
1944 | The SLIP driver encountered an escaped `end' marker. This probably | |
1945 | means that someone's been sending it junk. The erroneous packet is | |
1946 | discarded, and we hope that we've rediscovered synchronization. | |
13a55605 | 1947 | .SP |
f43df819 | 1948 | .BI "TUN \- slip fork-error " ecode " " message |
42da2a58 | 1949 | The SLIP driver encountered an error forking a child process while |
1950 | allocating a new dynamic interface. | |
13a55605 | 1951 | .SP |
42da2a58 | 1952 | .BI "TUN \- slip no-slip-interfaces" |
1953 | The driver ran out of static SLIP interfaces. Either preallocate more, | |
1954 | or use dynamic SLIP interface allocation. | |
13a55605 | 1955 | .SP |
b9066fbb | 1956 | .BI "TUN " ifname " slip overflow" |
1957 | The SLIP driver gave up reading a packet because it got too large. | |
13a55605 | 1958 | .SP |
f43df819 | 1959 | .BI "TUN \- slip pipe-error " ecode " " message |
42da2a58 | 1960 | The SLIP driver encountered an error creating pipes while allocating a |
1961 | new dynamic interface. | |
13a55605 | 1962 | .SP |
f43df819 | 1963 | .BI "TUN \- slip read-ifname-failed " ecode " " message |
42da2a58 | 1964 | The SLIP driver encountered an error reading the name of a dynamically |
1965 | allocated interface. Maybe the allocation script is broken. | |
13a55605 | 1966 | .SP |
f43df819 | 1967 | .BI "TUN \- unet config-error " ecode " " message |
42da2a58 | 1968 | Configuring the Linux Unet interface failed. Unet is obsolete and |
1969 | shouldn't be used any more. | |
13a55605 | 1970 | .SP |
f43df819 | 1971 | .BI "TUN \- unet getinfo-error " ecode " " message |
42da2a58 | 1972 | Reading information about the Unet interface failed. Unet is obsolete |
1973 | and shouldn't be used any more. | |
bd58d532 | 1974 | .SS "USER warnings" |
1975 | These are issued by administration clients using the | |
1976 | .B WARN | |
1977 | command. | |
13a55605 | 1978 | .SP |
bd58d532 | 1979 | .BI "USER " tokens\fR... |
1980 | An administration client issued a warning. | |
13a55605 | 1981 | .\"-sep |
fc916a09 MW |
1982 | . |
1983 | .\"-------------------------------------------------------------------------- | |
13a55605 | 1984 | .SH "SUMMARY" |
fc916a09 | 1985 | . |
13a55605 MW |
1986 | .SS "Command responses" |
1987 | .nf | |
2acd7cd6 | 1988 | .BI "BGDETACH " tag |
13a55605 MW |
1989 | .BI "BGFAIL " tag " " tokens \fR... |
1990 | .BI "BGINFO " tag " " tokens \fR... | |
1991 | .BI "BGOK " tag | |
1992 | .BI "FAIL " tokens \fR... | |
1993 | .BI "INFO " tokens \fR... | |
1994 | .B OK | |
1995 | .fi | |
1996 | .\"= summary | |
fc916a09 MW |
1997 | . |
1998 | .\"-------------------------------------------------------------------------- | |
d6623498 | 1999 | .SH "SEE ALSO" |
fc916a09 | 2000 | . |
d6623498 | 2001 | .BR tripectl (1), |
2002 | .BR tripe (8). | |
2003 | .PP | |
3cdc3f3a | 2004 | .IR "The Trivial IP Encryption Protocol" . |
fc916a09 MW |
2005 | . |
2006 | .\"-------------------------------------------------------------------------- | |
d6623498 | 2007 | .SH "AUTHOR" |
fc916a09 | 2008 | . |
d36eda2a | 2009 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
2010 | . |
2011 | .\"----- That's all, folks -------------------------------------------------- |