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