d6623498 |
1 | .\" -*-nroff-*- |
060ca767 |
2 | .\" |
3 | .ie t \{\ |
4 | . if \n(.g \{\ |
5 | . fam P |
6 | . \} |
7 | .\} |
d6623498 |
8 | .TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
9 | .SH NAME |
10 | tripe-admin \- administrator commands for TrIPE |
11 | .SH DESCRIPTION |
12 | This manual page describes the administration interface provided by the |
13 | .BR tripe (8) |
14 | daemon. |
15 | .PP |
16 | The |
17 | .BR tripectl (8) |
18 | program can be used either interactively or in scripts to communicate |
19 | with the server using this interface. Alternatively, simple custom |
20 | clients can be written in scripting languages such as Perl, Python or |
21 | Tcl, or more advanced clients such as GUI monitors can be written in C |
22 | with little difficulty. |
23 | .PP |
24 | By default, the server listens for admin connections on the Unix-domain |
25 | socket |
26 | .BR /var/lib/tripe/tripesock . |
27 | Administration commands use a simple textual protocol. Each client |
28 | command or server response consists of a line of ASCII text terminated |
8bc63560 |
29 | by a single linefeed character. No command may be longer than 255 |
30 | characters. |
d6623498 |
31 | .SS "General structure" |
32 | Each command or response line consists of a sequence of |
33 | whitespace-separated words. The number and nature of whitespace |
34 | characters separating two words in a client command is not significant; |
35 | the server always uses a single space character. The first word in a |
36 | line is a |
37 | .I keyword |
38 | identifying the type of command or response contained. Keywords in |
39 | client commands are not case-sensitive; the server always uses uppercase |
40 | for its keywords. |
de014da6 |
41 | .SS "Simple commands" |
42 | For simple client command, the server responds with zero or more |
d6623498 |
43 | .B INFO |
44 | lines, followed by either an |
45 | .B OK |
46 | line or a |
47 | .B FAIL |
48 | line. Each |
49 | .B INFO |
50 | provides information requested in the command. An |
51 | .B OK |
52 | response contains no further data. A |
53 | .B FAIL |
3cdc3f3a |
54 | code is followed by a machine-readable explanation of why the command |
d6623498 |
55 | failed. |
56 | .PP |
de014da6 |
57 | Simple command processing is strictly synchronous: the server reads a |
58 | command, processes it, and responds, before reading the next command. |
59 | All commands can be run as simple commands. Long-running commands |
60 | (e.g., |
61 | .B ADD |
62 | and |
63 | .BR PING ) |
64 | block the client until they finish, but the rest of the server continues |
65 | running. |
66 | .SS "Asynchronous messages" |
67 | There are three types of asynchronous messages which |
68 | aren't associated with any particular command. |
69 | .PP |
70 | The |
d6623498 |
71 | .B WARN |
3cdc3f3a |
72 | message contains a machine-readable message warning of an error |
d6623498 |
73 | encountered while processing a command, unexpected or unusual behaviour |
74 | by a peer, or a possible attack by an adversary. Under normal |
de014da6 |
75 | conditions, the server shouldn't emit any warnings. |
76 | .PP |
77 | The |
d6623498 |
78 | .B TRACE |
3cdc3f3a |
79 | message contains a human-readable tracing message containing diagnostic |
d6623498 |
80 | information. Trace messages are controlled using the |
81 | .B \-T |
82 | command-line option to the server, or the |
83 | .B TRACE |
84 | administration command (see below). Support for tracing can be disabled |
85 | when the package is being configured, and may not be available in your |
de014da6 |
86 | version. |
87 | .PP |
88 | Finally, the |
3cdc3f3a |
89 | .B NOTE |
90 | message is a machine-readable notification about some routine but |
91 | interesting event such as creation or destruction of peers. |
92 | .PP |
93 | The presence of asynchronous messages can be controlled using the |
94 | .B WATCH |
95 | command. |
de014da6 |
96 | .SS "Background commands" |
97 | Some commands (e.g., |
98 | .B ADD |
99 | and |
100 | .BR PING ) |
101 | take a long time to complete. To prevent these long-running commands |
102 | from tying up a server connection, they can be run in the background. |
103 | Not all commands can be run like this: the ones that can provide a |
104 | .B \-background |
105 | option, which must be supplied with a |
106 | .IR tag . |
107 | .PP |
108 | A command may fail before it starts running in the background. In this |
109 | case, the server emits a |
110 | .B FAIL |
111 | response, as usual. To indicate that a command has started running in |
112 | the background, the server emits a response of the form |
113 | .BI "BGDETACH " tag \fR, |
114 | where |
115 | .I tag |
116 | is the value passed to the |
117 | .B \-background |
118 | option. From this point on, the server is ready to process more |
119 | commands and reply to them. |
120 | .PP |
121 | Responses to background commands are indicated by a line beginning with |
122 | one of the tokens |
123 | .BR BGOK , |
124 | .BR BGFAIL , |
125 | or |
126 | .BR BGINFO , |
127 | followed by the command tag. These correspond to the |
128 | .BR OK , |
129 | .BR FAIL , |
130 | and |
131 | .B INFO |
132 | responses for simple commands: |
133 | .B BGINFO |
134 | indicates information from a background command which has not completed |
135 | yet; and |
136 | .B BGOK |
137 | and |
138 | .B BGFAIL |
139 | indicates that a background command succeeded or failed, respectively. |
140 | .PP |
141 | A background command will never issue an |
142 | .B OK |
060ca767 |
143 | or |
144 | .B BGINFO |
145 | response: it will always detach and then issue any |
146 | .B BGINFO |
147 | lines followed by |
de014da6 |
148 | .B BGOK |
149 | response. |
3cdc3f3a |
150 | .SS "Network addresses" |
151 | A network address is a sequence of words. The first is a token |
152 | identifying the network address family. The length of an address and |
153 | the meanings of the subsequent words depend on the address family. |
154 | Address family tokens are not case-sensitive on input; on output, they |
155 | are always in upper-case. |
156 | .PP |
157 | At present, only one address family is understood. |
158 | .TP |
159 | .BI "INET " address " " port |
160 | An Internet socket, naming an IPv4 address and UDP port. On output, the |
161 | address is always in numeric dotted-quad form, and the port is given as |
162 | a plain number. On input, DNS hostnames and symbolic port names are |
163 | permitted. Name resolution does not block the main server, but will |
164 | block the requesting client. This hopefully makes life simpler for |
165 | stupid clients. Complex clients which don't wish to be held up can open |
166 | extra connections or do the resolution themselves.) |
167 | .PP |
168 | If, on input, no recognised address family token is found, the following |
169 | words are assumed to represent an |
170 | .B INET |
171 | address. |
060ca767 |
172 | .SS "Key-value output" |
173 | Some commands (e.g., |
174 | .B STATS |
175 | and |
176 | .BR SERVINFO ) |
177 | produce output in the form of |
178 | .IB key = value |
179 | pairs, one per word. Neither the |
180 | .I key |
181 | nor the |
182 | .I value |
183 | contain spaces. |
184 | .SS "Trace lists" |
185 | Commands which enable or disable kinds of output (e.g., |
186 | .B TRACE |
187 | and |
188 | .BR WATCH ) |
189 | work in similar ways. They take a single optional argument, which |
190 | consists of a string of letters selecting message types, optionally |
191 | interspersed with |
192 | .RB ` + ' |
193 | to enable, or |
194 | .RB ` \- ' |
195 | to disable, the subsequently listed types. |
196 | .PP |
197 | If the argument is omitted, the available message types are displayed, |
198 | one to an |
199 | .B INFO |
200 | line, in a fixed-column format. Column zero contains the key letter for |
201 | selecting that message type; column one contains either a space or a |
202 | .RB ` + ' |
203 | sign, if the message type is disabled or enabled respectively; and a |
204 | textual description of the message type begins at column 3 and continues |
205 | to the end of the line. |
206 | .PP |
207 | Lowercase key letters control individual message types. Uppercase key |
208 | letters control collections of message types. |
3cdc3f3a |
209 | .SH "COMMAND REFERENCE" |
d6623498 |
210 | The commands provided are: |
211 | .TP |
42da2a58 |
212 | .BI "ADD " peer " \fR[" options "\fR] " address "\fR..." |
3cdc3f3a |
213 | Adds a new peer. The peer is given the name |
214 | .IR peer ; |
215 | the peer's public key is assumed to be in the file |
216 | .B keyring.pub |
217 | (or whatever alternative file was specified in the |
218 | .B \-K |
219 | option on the command line). The |
220 | .I address |
221 | is the network address (see above for the format) at which the peer can |
42da2a58 |
222 | be contacted. The following options are recognised. |
223 | .RS |
224 | .TP |
de014da6 |
225 | .BI "\-background " tag |
226 | Run the command in the background, using the given |
227 | .IR tag . |
228 | .TP |
0ba8de86 |
229 | .BI "\-keepalive " time |
230 | Send a no-op packet if we've not sent a packet to the peer in the last |
231 | .I time |
232 | interval. This is useful for persuading port-translating firewalls to |
233 | believe that the `connection' is still active. The |
234 | .I time |
235 | is expressed as a nonnegative integer followed optionally by |
236 | .BR d , |
237 | .BR h , |
238 | .BR m , |
239 | or |
240 | .BR s |
241 | for days, hours, minutes, or seconds respectively; if no suffix is |
242 | given, seconds are assumed. |
243 | .TP |
244 | .BI "\-tunnel " tunnel |
42da2a58 |
245 | Use the named tunnel driver, rather than the default. |
246 | .RE |
3cdc3f3a |
247 | .TP |
248 | .BI "ADDR " peer |
249 | Emits an |
250 | .B INFO |
251 | line reporting the IP address and port number stored for |
252 | .IR peer . |
253 | .TP |
254 | .B "DAEMON" |
255 | Causes the server to disassociate itself from its terminal and become a |
256 | background task. This only works once. A warning is issued. |
257 | .TP |
0ba8de86 |
258 | .BI "EPING \fR[" options "\fR] " peer |
259 | Sends an encrypted ping to the peer, and expects an encrypted response. |
260 | This checks that the peer is running (and not being impersonated), and |
261 | that it can encrypt and decrypt packets correctly. Options and |
262 | responses are the same as for the |
263 | .B PING |
264 | command. |
265 | .TP |
de014da6 |
266 | .BI "FORCEKX " peer |
267 | Requests the server to begin a new key exchange with |
268 | .I peer |
269 | immediately. |
270 | .TP |
d6623498 |
271 | .B "HELP" |
272 | Causes the server to emit an |
273 | .B INFO |
274 | line for each command it supports. Each line lists the command name, |
275 | followed by the names of the arguments. This may be helpful as a memory |
276 | aid for interactive use, or for program clients probing for features. |
3cdc3f3a |
277 | .TP |
278 | .BI "IFNAME " peer |
279 | Emits an |
280 | .B INFO |
281 | line containing the name of the network interface used to collect IP |
282 | packets which are to be encrypted and sent to |
283 | .IR peer . |
284 | Used by configuration scripts so that they can set up routing tables |
285 | appropriately after adding new peers. |
286 | .TP |
287 | .BI "KILL " peer |
288 | Causes the server to forget all about |
289 | .IR peer . |
290 | All keys are destroyed, and no more packets are sent. No notification |
291 | is sent to the peer: if it's important that the peer be notified, you |
292 | must think of a way to do that yourself. |
293 | .TP |
294 | .B "LIST" |
295 | For each currently-known peer, an |
296 | .B INFO |
297 | line is written containing the peer's name, as given to |
298 | .BR ADD . |
299 | .TP |
bd58d532 |
300 | .BI "NOTIFY " tokens\fR... |
301 | Issues a |
302 | .B USER |
303 | notification to all interested administration clients. |
304 | .TP |
060ca767 |
305 | .BI "PEERINFO " peer |
306 | Returns information about a peer, in key-value form. The following keys |
307 | are returned. |
308 | .RS |
309 | .TP |
310 | .B tunnel |
311 | The tunnel driver used for this peer. |
312 | .TP |
313 | .B keepalive |
314 | The keepalive interval, in seconds, or zero if no keepalives are to be |
315 | sent. |
316 | .RE |
317 | .TP |
0ba8de86 |
318 | .BI "PING \fR[" options "\fR] " peer |
319 | Send a transport-level ping to the peer. The ping and its response are |
320 | not encrypted or authenticated. This command, possibly in conjunction |
321 | with tracing, is useful for ensuring that UDP packets are actually |
322 | flowing in both directions. See also the |
323 | .B EPING |
324 | command. |
325 | .IP |
326 | An |
327 | .B INFO |
328 | line is printed describing the outcome: |
329 | .RS |
330 | .TP |
331 | .BI "ping-ok " millis |
332 | A response was received |
333 | .I millis |
334 | after the ping was sent. |
335 | .TP |
336 | .BI "ping-timeout" |
337 | No response was received within the time allowed. |
338 | .TP |
339 | .BI "ping-peer-died" |
340 | The peer was killed (probably by another admin connection) before a |
341 | response was received. |
342 | .RE |
343 | .IP |
344 | Options recognized for this command are: |
345 | .RS |
346 | .TP |
de014da6 |
347 | .BI "\-background " tag |
348 | Run the command in the background, using the given |
349 | .IR tag . |
350 | .TP |
0ba8de86 |
351 | .BI "\-timeout " time |
352 | Wait for |
353 | .I time |
354 | seconds before giving up on a response. The default is 5 seconds. (The |
355 | time format is the same as for the |
356 | .B "ADD \-keepalive" |
357 | option.) |
358 | .RE |
359 | .TP |
3cdc3f3a |
360 | .B "PORT" |
361 | Emits an |
362 | .B INFO |
363 | line containing just the number of the UDP port used by the |
364 | .B tripe |
365 | server. If you've allowed your server to allocate a port dynamically, |
366 | this is how to find out which one it chose. |
367 | .TP |
de014da6 |
368 | .B "RELOAD" |
369 | Instructs the server to recheck its keyring files. The server checks |
370 | these periodically anyway but it may be necessary to force a recheck, |
371 | for example after adding a new peer key. |
372 | .TP |
3cdc3f3a |
373 | .B "QUIT" |
374 | Instructs the server to exit immediately. A warning is sent. |
375 | .TP |
060ca767 |
376 | .B "SERVINFO" |
377 | Returns information about the server, in the form of key-value pairs. |
378 | The following keys are used. |
379 | .RS |
380 | .TP |
381 | .B implementation |
382 | A keyword naming the implementation of the |
383 | .BR tripe (8) |
384 | server. The current implementation is called |
385 | .BR edgeware-tripe . |
386 | .TP |
387 | .B version |
388 | The server's version number, as reported by |
389 | .BR VERSION . |
390 | .TP |
391 | .B daemon |
392 | Either |
393 | .B t |
394 | or |
395 | .BR nil , |
396 | if the server has or hasn't (respectively) become a daemon. |
397 | .RE |
398 | .TP |
3cdc3f3a |
399 | .BI "STATS " peer |
400 | Emits a number of |
401 | .B INFO |
402 | lines, each containing one or more statistics in the form |
403 | .IB name = value \fR. |
404 | The statistics-gathering is experimental and subject to change. |
d6623498 |
405 | .TP |
406 | .BR "TRACE " [\fIoptions\fP] |
060ca767 |
407 | Selects trace outputs: see |
408 | .B "Trace lists" |
409 | above. Message types provided are: |
d6623498 |
410 | .RS |
2d752320 |
411 | .PP |
d6623498 |
412 | Currently, the following tracing options are supported: |
413 | .TP |
414 | .B t |
415 | Tunnel events: reception of packets to be encrypted, and injection of |
416 | successfully-decrypted packets. |
417 | .TP |
418 | .B r |
419 | Peer management events: creation and destruction of peer attachments, |
420 | and arrival of messages. |
421 | .TP |
422 | .B a |
423 | Administration interface: acceptance of new connections, and handling of |
424 | the backgroud name-resolution required by the |
425 | .B ADD |
426 | command. |
427 | .TP |
428 | .B p |
429 | Display contents of packets sent and received by the tunnel and/or peer |
430 | modules. |
431 | .TP |
432 | .B c |
433 | Display inputs, outputs and intermediate results of cryptographic |
434 | operations. This includes plaintext and key material. Use with |
435 | caution. |
436 | .TP |
437 | .B s |
438 | Handling of symmetric keysets: creation and expiry of keysets, and |
439 | encryption and decryption of messages. |
440 | .TP |
441 | .B x |
442 | Key exchange: reception, parsing and emission of key exchange messages. |
443 | .TP |
444 | .B m |
445 | Key management: loading keys and checking for file modifications. |
446 | .PP |
447 | Note that the |
448 | .B p |
449 | (packet contents) |
450 | and |
451 | .B c |
452 | (crypto details) |
453 | outputs provide extra detail for other outputs. Specifying |
454 | .B p |
455 | without |
456 | .B r |
457 | or |
458 | .B t |
459 | isn't useful; neither is specifying |
460 | .B c |
461 | without one of |
462 | .BR s , |
463 | .B x |
464 | or |
465 | .BR m . |
3cdc3f3a |
466 | .TP |
467 | .B A |
468 | All of the above. |
d6623498 |
469 | .RE |
470 | .TP |
060ca767 |
471 | .B "TUNNELS" |
472 | For each available tunnel driver, an |
473 | .B INFO |
474 | line is printed giving its name. |
475 | .TP |
476 | .B "VERSION" |
477 | Causes the server to emit an |
478 | .B INFO |
479 | line stating its software version, as two words: the server name, and |
480 | its version string. The server name |
481 | .B tripe |
482 | is reserved to the Straylight/Edgeware implementation. |
483 | .TP |
3cdc3f3a |
484 | .BR "WATCH " [\fIoptions\fP] |
485 | Enables or disables asynchronous messages |
486 | .IR "for the current connection only" . |
060ca767 |
487 | See |
488 | .B "Trace lists" |
3cdc3f3a |
489 | above. The default watch state for the connection the server opens |
490 | automatically on stdin/stdout is to show warnings and trace messages; |
491 | other connections show no asynchronous messages. (This is done in order |
492 | to guarantee that a program reading the server's stdout does not miss |
493 | any warnings.) |
494 | .RS |
495 | .PP |
060ca767 |
496 | Message types provided are: |
3cdc3f3a |
497 | .TP |
498 | .B t |
499 | .B TRACE |
500 | messages. |
501 | .TP |
502 | .B n |
503 | .B NOTE |
504 | messages. |
505 | .TP |
506 | .B w |
507 | .B WARN |
508 | messages. |
509 | .TP |
510 | .B a |
511 | All of the above. |
512 | .RE |
513 | .TP |
bd58d532 |
514 | .BI "WARN " tokens\fR... |
515 | Issues a |
516 | .B USER |
517 | warning to all interested administration clients. |
3cdc3f3a |
518 | .SH "ERROR MESSAGES" |
519 | The following |
520 | .B FAIL |
de014da6 |
521 | (or |
522 | .BR BGFAIL ) |
3cdc3f3a |
523 | messages are sent to clients as a result of errors during command |
524 | processing. |
d6623498 |
525 | .TP |
3cdc3f3a |
526 | .BI "already-daemon" |
527 | (For |
528 | .BR DAEMON .) |
529 | The |
530 | .B tripe |
531 | server is already running as a daemon. |
d6623498 |
532 | .TP |
3cdc3f3a |
533 | .BI "bad-syntax \-\- " message |
534 | (For any command.) The command couldn't be understood: e.g., the number |
535 | of arguments was wrong. |
d6623498 |
536 | .TP |
0ba8de86 |
537 | .BI "bad-time-spec " word |
538 | The |
539 | .I word |
540 | is not a valid time interval specification. Acceptable time |
541 | specifications are nonnegative integers followed optionally by |
542 | .BR d , |
543 | .BR h , |
544 | .BR m , |
545 | or |
546 | .BR s , |
547 | for days, hours, minutes, or seconds, respectively. |
548 | .TP |
3cdc3f3a |
549 | .BI "bad-trace-option " char |
550 | (For |
551 | .BR TRACE .) |
552 | An unknown trace option was requested. |
553 | .TP |
554 | .BI "bad-watch-option " char |
555 | (For |
556 | .BR WATCH .) |
557 | An unknown watch option was requested. |
558 | .TP |
559 | .BI "daemon-error \-\- " message |
560 | (For |
561 | .BR DAEMON .) |
562 | An error occurred during the attempt to become a daemon, as reported by |
563 | .IR message . |
564 | .TP |
565 | .BI "invalid-port " number |
566 | (For |
567 | .BR ADD .) |
568 | The given port number is out of range. |
569 | .TP |
570 | .BI "peer-create-fail " peer |
571 | (For |
572 | .BR ADD .) |
573 | Adding |
574 | .I peer |
575 | failed for some reason. A warning should have been emitted explaining |
576 | why. |
577 | .TP |
578 | .BI "peer-exists " peer |
579 | (For |
580 | .BR ADD .) |
581 | There is already a peer named |
d6623498 |
582 | .IR peer . |
583 | .TP |
0ba8de86 |
584 | .B "ping-send-failed" |
585 | The attempt to send a ping packet failed, probably due to lack of |
586 | encryption keys. |
587 | .TP |
3cdc3f3a |
588 | .BI "resolve-error " hostname |
589 | (For |
590 | .BR ADD .) |
591 | The DNS name |
592 | .I hostname |
593 | could not be resolved. |
594 | .TP |
595 | .BI "resolver-timeout " hostname |
596 | (For |
597 | .BR ADD .) |
598 | The DNS name |
599 | .I hostname |
600 | took too long to resolve. |
601 | .TP |
602 | .BI "unknown-command " token |
603 | The command |
604 | .B token |
605 | was not recognised. |
606 | .TP |
607 | .BI "unknown-peer " name |
608 | (For |
609 | .BR ADDR , |
610 | .BR IFNAME , |
611 | .BR KILL , |
612 | and |
613 | .BR STATS .) |
614 | There is no peer called |
615 | .IR name . |
616 | .TP |
617 | .BI "unknown-service " service |
618 | (For |
619 | .BR ADD .) |
620 | The service name |
621 | .I service |
622 | couldn't be found in |
623 | .BR /etc/services . |
624 | .SH "NOTIFICATIONS" |
625 | The following notifications are sent to clients who request them. |
626 | .TP |
42da2a58 |
627 | .BI "ADD " peer " " ifname " " address \fR... |
3cdc3f3a |
628 | A new peer has been added. The peer's name is |
42da2a58 |
629 | .IR peer , |
630 | its tunnel is network interface |
631 | .IR ifname , |
3cdc3f3a |
632 | and its network address is |
633 | .IR address . |
634 | .TP |
635 | .BI "DAEMON" |
636 | The server has forked off into the sunset and become a daemon. |
d6623498 |
637 | .TP |
638 | .BI "KILL " peer |
3cdc3f3a |
639 | The peer |
640 | .I peer |
641 | has been killed. |
d6623498 |
642 | .TP |
3cdc3f3a |
643 | .BI "KXDONE " peer |
644 | Key exchange with |
645 | .I peer |
646 | finished successfully. |
647 | .TP |
648 | .BI "KXSTART " peer |
649 | Key exchange with |
650 | .I peer |
651 | has begun or restarted. If key exchange keeps failing, this message |
652 | will be repeated periodically. |
bd58d532 |
653 | .TP |
654 | .BI "USER " tokens\fR... |
655 | An administration client issued a notification using the |
656 | .B NOTIFY |
657 | command. |
3cdc3f3a |
658 | .SH "WARNINGS" |
659 | There are many possible warnings. They are categorized according to |
660 | their first tokens. |
661 | .SS "ABORT warnings" |
662 | These all indicate that the |
d6623498 |
663 | .B tripe |
3cdc3f3a |
664 | server has become unable to continue. If enabled, the server will dump |
665 | core in its configuration directory. |
d6623498 |
666 | .TP |
3cdc3f3a |
667 | .BI "ABORT repeated-select-errors" |
668 | The main event loop is repeatedly failing. If the server doesn't quit, |
669 | it will probably waste all available CPU doing nothing. |
670 | .SS "ADMIN warnings" |
671 | These indicate a problem with the administration socket interface. |
672 | .TP |
673 | .BI "ADMIN accept-error \-\- " message |
674 | There was an error while attempting to accept a connection from a new |
675 | client. |
676 | .TP |
677 | .BI "ADMIN client-read-error \-\- " message |
678 | There was an error sending data to a client. The connection to the |
679 | client has been closed. |
680 | .SS "KEYMGMT warnings" |
681 | These indicate a problem with the keyring files, or the keys stored in |
682 | them. |
683 | .TP |
684 | .BI "KEYMGMT bad-private-key \-\- " message |
685 | The private key could not be read, or failed a consistency check. If |
686 | there was a problem with the file, usually there will have been |
687 | .B key-file-error |
688 | warnings before this. |
689 | .TP |
690 | .BI "KEYMGMT bad-public-keyring \-\- " message |
691 | The public keyring couldn't be read. Usually, there will have been |
692 | .B key-file-error |
693 | warnings before this. |
694 | .TP |
695 | .BI "KEYMGMT key-file-error " file ":" line " \-\- " message |
696 | Reports a specific error with the named keyring file. This probably |
697 | indicates a bug in |
698 | .BR key (1). |
699 | .TP |
700 | .BI "KEYMGMT public-key " tag " " tokens\fR... |
701 | These messages all indicate a problem with the public key named |
702 | .IR tag . |
703 | .TP |
704 | .BI "KEYMGMT public-key " tag " algorithm-mismatch" |
705 | The algorithms specified on the public key don't match the ones for our |
706 | private key. All the peers in a network have to use the same |
707 | algorithms. |
708 | .TP |
709 | .BI "KEYMGMT public-key " tag " bad \-\- " message |
710 | The public key couldn't be read, or is invalid. |
711 | .TP |
712 | .BI "KEYMGMT public-key " tag " bad-public-group-element" |
713 | The public key is invalid. This may indicate a malicious attempt to |
714 | introduce a bogus key. |
715 | .TP |
716 | .BI "KEYMGMT public-key " tag " bad-algorithm-selection" |
717 | The algorithms listed on the public key couldn't be understood. The |
718 | algorithm selection attributes are probably malformed and need fixing. |
719 | .TP |
720 | .BI "KEYMGMT public-key " tag " incorrect-group" |
721 | The public key doesn't use the same group as our private key. All the |
722 | peers in a network have to use the same group. |
723 | .TP |
724 | .BI "KEYMGMT public-key " tag " not-found" |
725 | The public key for peer |
726 | .I tag |
727 | wasn't in the public keyring. |
728 | .TP |
729 | .BI "KEYMGMT public-key " tag " unknown-type" |
730 | The type of the public key isn't understood. Maybe you need to upgrade |
731 | your copy of |
732 | .BR tripe . |
733 | (Even if you do, you'll have to regenerate your keys.) |
734 | .SS "KX warnings" |
735 | These indicate problems during key-exchange. Many indicate either a bug |
736 | in the server (either yours or the remote one), or some kind of attack |
737 | in progress. All name a |
738 | .I peer |
739 | as the second token: this is the peer the packet is apparently from, |
740 | though it may have been sent by an attacker instead. |
741 | .PP |
742 | In the descriptions below, |
743 | .I msgtoken |
744 | is one of the tokens |
745 | .BR pre-challenge , |
746 | .BR cookie , |
747 | .BR challenge , |
748 | .BR reply , |
749 | .BR switch-rq , |
750 | or |
751 | .BR switch-ok . |
752 | .TP |
753 | .BI "KX " peer " bad-expected-reply-log" |
754 | The challenges |
755 | .B tripe |
756 | uses in its protocol contain a check value which proves that the |
757 | challenge is honest. This message indicates that the check value |
758 | supplied is wrong: someone is attempting to use bogus challenges to |
759 | persuade your |
760 | .B tripe |
761 | server to leak private key information. No chance! |
762 | .TP |
bd58d532 |
763 | .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok" |
3cdc3f3a |
764 | A symmetrically-encrypted portion of a key-exchange message failed to |
765 | decrypt. |
766 | .TP |
767 | .BI "KX " peer " invalid " msgtoken |
768 | A key-exchange message was malformed. This almost certainly indicates a |
769 | bug somewhere. |
770 | .TP |
bd58d532 |
771 | .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok" |
3cdc3f3a |
772 | A message didn't contain the right magic data. This may be a replay of |
773 | some old exchange, or random packets being sent in an attempt to waste |
774 | CPU. |
775 | .TP |
776 | .BI "KX " peer " public-key-expired" |
777 | The peer's public key has expired. It's maintainer should have given |
778 | you a replacement before now. |
779 | .TP |
780 | .BI "KX " peer " sending-cookie" |
781 | We've received too many bogus pre-challenge messages. Someone is trying |
782 | to flood us with key-exchange messages and make us waste CPU on doing |
783 | hard asymmetric crypto sums. |
784 | .TP |
785 | .BI "KX " peer " unexpected " msgtoken |
786 | The message received wasn't appropriate for this stage of the key |
787 | exchange process. This may mean that one of our previous packets got |
788 | lost. For |
789 | .BR pre-challenge , |
790 | it may simply mean that the peer has recently restarted. |
791 | .TP |
792 | .BI "KX " peer " unknown-challenge" |
793 | The peer is asking for an answer to a challenge which we don't know |
794 | about. This may mean that we've been inundated with challenges from |
795 | some malicious source |
796 | .I who can read our messages |
797 | and discarded the valid one. |
798 | .TP |
799 | .BI "KX " peer " unknown-message 0x" nn |
800 | An unknown key-exchange message arrived. |
801 | .SS "PEER warnings" |
802 | These are largely concerned with management of peers and the low-level |
803 | details of the network protocol. The second word is usually the name of |
804 | a peer, or |
805 | .RB ` \- ' |
806 | if none is relevant. |
807 | .TP |
3cdc3f3a |
808 | .BI "PEER " peer " bad-packet no-type" |
809 | An empty packet arrived. This is very strange. |
810 | .TP |
811 | .BI "PEER " peer " bad-packet unknown-category 0x" nn |
812 | The message category |
813 | .I nn |
814 | (in hex) isn't understood. Probably a strange random packet from |
815 | somewhere; could be an unlikely bug. |
816 | .TP |
817 | .BI "PEER " peer " bad-packet unknown-type 0x" nn |
818 | The message type |
819 | .I nn |
820 | (in hex) isn't understood. Probably a strange random packet from |
821 | somewhere; could be an unlikely bug. |
822 | .TP |
0ba8de86 |
823 | .BI "PEER " peer " corrupt-encrypted-ping" |
824 | The peer sent a ping response which matches an outstanding ping, but its |
825 | payload is wrong. There's definitely a bug somewhere. |
826 | .TP |
827 | .BI "PEER " peer " corrupt-transport-ping" |
828 | The peer (apparently) sent a ping response which matches an outstanding |
829 | ping, but its payload is wrong. Either there's a bug, or the bad guys |
830 | are playing tricks on you. |
831 | .TP |
3cdc3f3a |
832 | .BI "PEER " peer " decrypt-failed" |
833 | An encrypted IP packet failed to decrypt. It may have been mangled in |
834 | transit, or may be a very old packet from an expired previous session |
835 | key. There is usually a considerable overlap in the validity periods of |
836 | successive session keys, so this shouldn't occur unless the key exchange |
837 | takes ages or fails. |
838 | .TP |
0ba8de86 |
839 | .BI "PEER " peer " malformed-encrypted-ping" |
840 | The peer sent a ping response which is hopelessly invalid. There's |
841 | definitely a bug somewhere. |
842 | .TP |
843 | .BI "PEER " peer " malformed-transport-ping" |
844 | The peer (apparently) sent a ping response which is hopelessly invalid. |
845 | Either there's a bug, or the bad guys are playing tricks on you. |
846 | .TP |
3cdc3f3a |
847 | .BI "PEER " peer " packet-build-failed" |
848 | There wasn't enough space in our buffer to put the packet we wanted to |
849 | send. Shouldn't happen. |
850 | .TP |
851 | .BI "PEER \- socket-read-error \-\- " message |
852 | An error occurred trying to read an incoming packet. |
853 | .TP |
854 | .BI "PEER " peer " socket-write-error \-\- " message |
855 | An error occurred attempting to send a network packet. We lost that |
856 | one. |
0ba8de86 |
857 | .TP |
858 | .BI "PEER " peer " unexpected-encrypted-ping 0x" id |
859 | The peer sent an encrypted ping response whose id doesn't match any |
860 | outstanding ping. Maybe it was delayed for longer than the server was |
861 | willing to wait, or maybe the peer has gone mad. |
862 | .TP |
863 | .BI "PEER \- unexpected-source " address\fR... |
864 | A packet arrived from |
865 | .I address |
866 | (a network address \(en see above), but no peer is known at that |
867 | address. This may indicate a misconfiguration, or simply be a result of |
868 | one end of a connection being set up before the other. |
869 | .TP |
870 | .BI "PEER " peer " unexpected-transport-ping 0x" id |
871 | The peer (apparently) sent a transport ping response whose id doesn't |
872 | match any outstanding ping. Maybe it was delayed for longer than the |
873 | server was willing to wait, or maybe the peer has gone mad; or maybe |
874 | there are bad people trying to confuse you. |
3cdc3f3a |
875 | .SS "SERVER warnings" |
876 | These indicate problems concerning the server process as a whole. |
877 | .TP |
878 | .BI "SERVER ignore signal " name |
879 | A signal arrived, but the server ignored it. Currently this happens for |
880 | .B SIGHUP |
881 | because that's a popular way of telling daemons to re-read their |
882 | configuration files. Since |
883 | .B tripe |
884 | re-reads its keyrings automatically and has no other configuration |
885 | files, it's not relevant, but it seemed better to ignore the signal than |
886 | let the server die. |
887 | .TP |
888 | .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR] |
889 | A signal arrived and |
890 | .B tripe |
891 | is going to quit. |
892 | .TP |
893 | .BI "SERVER quit admin-request" |
894 | A client of the administration interface issued a |
895 | .B QUIT |
896 | command. |
897 | .TP |
898 | .BI "SERVER select-error \-\- " message |
899 | An error occurred in the server's main event loop. This is bad: if it |
900 | happens too many times, the server will abort. |
901 | .SS "SYMM warnings" |
902 | These are concerned with the symmetric encryption and decryption |
903 | process. |
904 | .TP |
905 | .BI "SYMM replay old-sequence" |
906 | A packet was received with an old sequence number. It may just have |
907 | been delayed or duplicated, or it may have been an attempt at a replay |
908 | attack. |
909 | .TP |
910 | .BI "SYMM replay duplicated-sequence" |
911 | A packet was received with a sequence number we've definitely seen |
912 | before. It may be an accidental duplication because the 'net is like |
913 | that, or a deliberate attempt at a replay. |
914 | .SS "TUN warnings" |
915 | These concern the workings of the system-specific tunnel driver. The |
916 | second word is the name of the tunnel interface in question, or |
917 | .RB ` \- ' |
918 | if none. |
919 | .TP |
920 | .BI "TUN \- bsd no-tunnel-devices" |
921 | The driver couldn't find an available tunnel device. Maybe if you |
922 | create some more |
923 | .BI /dev/tun nn |
924 | files, it will work. |
925 | .TP |
926 | .BI "TUN - open-error " device " \-\- " message |
927 | An attempt to open the tunnel device file |
928 | .I device |
929 | failed. |
930 | .TP |
3cdc3f3a |
931 | .BI "TUN \- linux config-error \-\- " message |
932 | Configuring the Linux TUN/TAP interface failed. |
933 | .TP |
42da2a58 |
934 | .BI "TUN " ifname " read-error \-\- " message |
935 | Reading from the tunnel device failed. |
3cdc3f3a |
936 | .TP |
42da2a58 |
937 | .BI "TUN " ifname " slip bad-escape" |
938 | The SLIP driver encountered a escaped byte it wasn't expecting to see. |
939 | The erroneous packet will be ignored. |
b9066fbb |
940 | .TP |
941 | .BI "TUN " ifname " slip eof" |
942 | The SLIP driver encountered end-of-file on its input descriptor. |
943 | Pending data is discarded, and no attempt is made to read any more data |
944 | from that interface ever. |
945 | .TP |
946 | .BI "TUN " ifname " slip escape-end" |
947 | The SLIP driver encountered an escaped `end' marker. This probably |
948 | means that someone's been sending it junk. The erroneous packet is |
949 | discarded, and we hope that we've rediscovered synchronization. |
950 | .TP |
42da2a58 |
951 | .BI "TUN \- slip fork-error \-\- " message |
952 | The SLIP driver encountered an error forking a child process while |
953 | allocating a new dynamic interface. |
954 | .TP |
955 | .BI "TUN \- slip no-slip-interfaces" |
956 | The driver ran out of static SLIP interfaces. Either preallocate more, |
957 | or use dynamic SLIP interface allocation. |
b9066fbb |
958 | .TP |
959 | .BI "TUN " ifname " slip overflow" |
960 | The SLIP driver gave up reading a packet because it got too large. |
42da2a58 |
961 | .TP |
962 | .BI "TUN \- slip pipe-error \-\- " message |
963 | The SLIP driver encountered an error creating pipes while allocating a |
964 | new dynamic interface. |
965 | .TP |
966 | .BI "TUN \- slip read-ifname-failed \-\- " message |
967 | The SLIP driver encountered an error reading the name of a dynamically |
968 | allocated interface. Maybe the allocation script is broken. |
969 | .TP |
970 | .BI "TUN \- unet config-error \-\- " message |
971 | Configuring the Linux Unet interface failed. Unet is obsolete and |
972 | shouldn't be used any more. |
973 | .TP |
974 | .BI "TUN \- unet getinfo-error \-\- " message |
975 | Reading information about the Unet interface failed. Unet is obsolete |
976 | and shouldn't be used any more. |
977 | .TP |
978 | .BI "TUN \- unet ifname-too-long \-\- " message |
979 | The Unet interface's name overflowed, so we couldn't read it properly. |
980 | Unet is obsolete and shouldn't be used any more. |
bd58d532 |
981 | .SS "USER warnings" |
982 | These are issued by administration clients using the |
983 | .B WARN |
984 | command. |
985 | .TP |
986 | .BI "USER " tokens\fR... |
987 | An administration client issued a warning. |
d6623498 |
988 | .SH "SEE ALSO" |
989 | .BR tripectl (1), |
990 | .BR tripe (8). |
991 | .PP |
3cdc3f3a |
992 | .IR "The Trivial IP Encryption Protocol" . |
d6623498 |
993 | .SH "AUTHOR" |
d36eda2a |
994 | Mark Wooding, <mdw@distorted.org.uk> |