| 1 | .\" -*-nroff-*- |
| 2 | .\". |
| 3 | .\" Manual for the administration protocol |
| 4 | .\" |
| 5 | .\" (c) 2008 Straylight/Edgeware |
| 6 | .\" |
| 7 | . |
| 8 | .\"----- Licensing notice --------------------------------------------------- |
| 9 | .\" |
| 10 | .\" This file is part of Trivial IP Encryption (TrIPE). |
| 11 | .\" |
| 12 | .\" TrIPE is free software: you can redistribute it and/or modify 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. |
| 16 | .\" |
| 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. |
| 21 | .\" |
| 22 | .\" You should have received a copy of the GNU General Public License |
| 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
| 24 | . |
| 25 | .\"-------------------------------------------------------------------------- |
| 26 | .so ../common/defs.man \" @@@PRE@@@ |
| 27 | . |
| 28 | .\"-------------------------------------------------------------------------- |
| 29 | .TH tripe-admin 5tripe "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
| 30 | . |
| 31 | .\"-------------------------------------------------------------------------- |
| 32 | .SH "NAME" |
| 33 | . |
| 34 | tripe-admin \- administrator commands for TrIPE |
| 35 | . |
| 36 | .\"-------------------------------------------------------------------------- |
| 37 | .SH "DESCRIPTION" |
| 38 | . |
| 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 |
| 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. |
| 54 | .SS "General structure" |
| 55 | Each command or response line consists of a sequence of |
| 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 |
| 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. |
| 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. |
| 78 | .SS "Simple commands" |
| 79 | For simple client command, the server responds with zero or more |
| 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 |
| 91 | code is followed by a machine-readable explanation of why the command |
| 92 | failed. |
| 93 | .PP |
| 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 |
| 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. |
| 111 | .PP |
| 112 | The |
| 113 | .B WARN |
| 114 | message contains a machine-readable message warning of an error |
| 115 | encountered while processing a command, unexpected or unusual behaviour |
| 116 | by a peer, or a possible attack by an adversary. Under normal |
| 117 | conditions, the server shouldn't emit any warnings. |
| 118 | .PP |
| 119 | The |
| 120 | .B TRACE |
| 121 | message contains a human-readable tracing message containing diagnostic |
| 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 |
| 128 | version. |
| 129 | .PP |
| 130 | Finally, the |
| 131 | .B NOTE |
| 132 | message is a machine-readable notification about some routine but |
| 133 | interesting event such as creation or destruction of peers. |
| 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 |
| 160 | one of the tokens |
| 161 | .BR BGOK , |
| 162 | .BR BGFAIL , |
| 163 | or |
| 164 | .BR BGINFO , |
| 165 | followed by the command tag. These correspond to the |
| 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 |
| 181 | or |
| 182 | .B INFO |
| 183 | response: it will always detach and then issue any |
| 184 | .B BGINFO |
| 185 | lines followed by |
| 186 | .B BGOK |
| 187 | response. |
| 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 |
| 216 | .IR service . |
| 217 | The recipient is no longer the provider of this service. |
| 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.) |
| 247 | .SS "Network addresses" |
| 248 | A network address is a sequence of tokens. The first is a token |
| 249 | identifying the network address family. The length of an address and |
| 250 | the meanings of the subsequent tokens depend on the address family. |
| 251 | Address family tokens are not case-sensitive on input; on output, they |
| 252 | are always in upper-case. |
| 253 | .PP |
| 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. |
| 269 | .TP |
| 270 | .BI "INET " address " \fR[" port \fR] |
| 271 | An Internet socket, naming an IPv4 address and UDP port. On output, the |
| 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. |
| 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. |
| 288 | .PP |
| 289 | If, on input, no recognized address family token is found, the following |
| 290 | tokens are assumed to represent an |
| 291 | .B ANY |
| 292 | address. Addresses output by the server always have an address family |
| 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. |
| 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 |
| 305 | pairs, one per token. Neither the |
| 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 |
| 328 | .RB ` + ' |
| 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. |
| 335 | . |
| 336 | .\"-------------------------------------------------------------------------- |
| 337 | .SH "COMMAND REFERENCE" |
| 338 | . |
| 339 | .\"* 10 Commands |
| 340 | The commands provided are: |
| 341 | .SP |
| 342 | .BI "ADD \fR[" options "\fR] " peer " " address "\fR..." |
| 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 |
| 352 | be contacted. The following options are recognized. |
| 353 | .RS |
| 354 | .\"+opts |
| 355 | .TP |
| 356 | .BI "\-background " tag |
| 357 | Run the command in the background, using the given |
| 358 | .IR tag . |
| 359 | .TP |
| 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 |
| 364 | .B "\-ephemeral" |
| 365 | The association with the peer is not intended to persist indefinitely. |
| 366 | When a peer is killed, or the |
| 367 | .BR tripe (8) |
| 368 | daemon is shut down, a |
| 369 | .B bye |
| 370 | packet is to the peer(s). If a peer marked as ephemeral sends us a |
| 371 | .B bye |
| 372 | packet then it is killed (but in this case no further |
| 373 | .B bye |
| 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. |
| 378 | .TP |
| 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 |
| 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 |
| 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 |
| 417 | key by this point. Prior to version 1.6.0, this option used to imply |
| 418 | .BR \-ephemeral . |
| 419 | .TP |
| 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 |
| 428 | notification. Prior to version 1.6.0, this option used to imply |
| 429 | .BR \-ephemeral . |
| 430 | .TP |
| 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 |
| 444 | .BI "\-tunnel " tunnel |
| 445 | Use the named tunnel driver, rather than the default. |
| 446 | .\"-opts |
| 447 | .RE |
| 448 | .SP |
| 449 | .BI "ADDR " peer |
| 450 | Emits an |
| 451 | .B INFO |
| 452 | line reporting the IP address and port number stored for |
| 453 | .IR peer . |
| 454 | .SP |
| 455 | .BI "ALGS \fR[" peer \fR] |
| 456 | Emits information about the cryptographic algorithms in use, in |
| 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. |
| 461 | .RS |
| 462 | .PP |
| 463 | The keys are as follows. |
| 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 |
| 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 |
| 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., |
| 514 | .BR ripemd160-hmac . |
| 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. |
| 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. |
| 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 |
| 539 | \- |
| 540 | .I header-length |
| 541 | \- 9 \- |
| 542 | .I bulk-overhead |
| 543 | .PP |
| 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). |
| 549 | .RE |
| 550 | .SP |
| 551 | .BI "BGCANCEL " tag |
| 552 | Cancels the background job with the named |
| 553 | .IR tag . |
| 554 | .SP |
| 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. |
| 561 | .SP |
| 562 | .B "DAEMON" |
| 563 | Causes the server to disassociate itself from its terminal and become a |
| 564 | background task. This only works once. A notification is issued. |
| 565 | .SP |
| 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. |
| 573 | .SP |
| 574 | .BI "FORCEKX " peer |
| 575 | Requests the server to begin a new key exchange with |
| 576 | .I peer |
| 577 | immediately. |
| 578 | .SP |
| 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 . |
| 584 | .SP |
| 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. |
| 592 | .SP |
| 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. |
| 599 | .SP |
| 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. |
| 608 | .SP |
| 609 | .B "JOBS" |
| 610 | Emits an |
| 611 | .B INFO |
| 612 | line giving the tag for each outstanding background job. |
| 613 | .SP |
| 614 | .BI "KILL " peer |
| 615 | Causes the server to forget all about |
| 616 | .IR peer . |
| 617 | All keys are destroyed, and no more packets are sent. No notification |
| 618 | is sent to the peer: if it's important that the peer be notified, you |
| 619 | must think of a way to do that yourself. |
| 620 | .SP |
| 621 | .B "LIST" |
| 622 | For each currently-known peer, an |
| 623 | .B INFO |
| 624 | line is written containing the peer's name, as given to |
| 625 | .BR ADD . |
| 626 | .SP |
| 627 | .BI "NOTIFY " tokens\fR... |
| 628 | Issues a |
| 629 | .B USER |
| 630 | notification to all interested administration clients. |
| 631 | .SP |
| 632 | .BI "PEERINFO " peer |
| 633 | Returns information about a peer, in key-value form. The following keys |
| 634 | are returned. |
| 635 | .RS |
| 636 | .TP |
| 637 | .B tunnel |
| 638 | The tunnel driver used for this peer. |
| 639 | .TP |
| 640 | .B keepalive |
| 641 | The keepalive interval, in seconds, or zero if no keepalives are to be |
| 642 | sent. |
| 643 | .TP |
| 644 | .B knock |
| 645 | If present, the string sent to the peer to set up the association; see |
| 646 | the |
| 647 | .B \-knock |
| 648 | option to |
| 649 | .BR ADD , |
| 650 | and the |
| 651 | .B KNOCK |
| 652 | notification. |
| 653 | .TP |
| 654 | .B key |
| 655 | The (short) key tag being used for the peer, as passed to the |
| 656 | .B ADD |
| 657 | command. |
| 658 | .TP |
| 659 | .B current-key |
| 660 | The full key tag of the peer's public key currently being used. This |
| 661 | may change during the life of the association. |
| 662 | .TP |
| 663 | .B private-key |
| 664 | The private key tag being used for the peer, as passed to the |
| 665 | .B ADD |
| 666 | command, or the |
| 667 | .RB ` \-t ' |
| 668 | command-line option. If neither of these was given explicitly, the |
| 669 | private key tag is shown as |
| 670 | .RB ` (default) ', |
| 671 | since there is no fixed tag used under these circumstances. |
| 672 | .TP |
| 673 | .B current-private-key |
| 674 | The full key tag of the private key currently being used for this |
| 675 | association. This may change during the life of the association. |
| 676 | .TP |
| 677 | .B corked |
| 678 | Either |
| 679 | .B t |
| 680 | or |
| 681 | .B nil |
| 682 | depending on whether or not (respectively) key-exchange is waiting for |
| 683 | the peer to initiate. |
| 684 | .TP |
| 685 | .B mobile |
| 686 | Either |
| 687 | .B t |
| 688 | or |
| 689 | .B nil |
| 690 | depending on whether or not (respectively) the peer is expected to |
| 691 | change its address unpredictably. |
| 692 | .TP |
| 693 | .B ephemeral |
| 694 | Either |
| 695 | .B t |
| 696 | or |
| 697 | .B nil |
| 698 | depending on whether the association with the peer is expected to be |
| 699 | temporary or persistent (respectively). |
| 700 | .RE |
| 701 | .SP |
| 702 | .BI "PING \fR[" options "\fR] " peer |
| 703 | Send a transport-level ping to the peer. The ping and its response are |
| 704 | not encrypted or authenticated. This command, possibly in conjunction |
| 705 | with tracing, is useful for ensuring that UDP packets are actually |
| 706 | flowing in both directions. See also the |
| 707 | .B EPING |
| 708 | command. |
| 709 | .IP |
| 710 | An |
| 711 | .B INFO |
| 712 | line is printed describing the outcome: |
| 713 | .RS |
| 714 | .TP |
| 715 | .BI "ping-ok " millis |
| 716 | A response was received |
| 717 | .I millis |
| 718 | after the ping was sent. |
| 719 | .TP |
| 720 | .BI "ping-timeout" |
| 721 | No response was received within the time allowed. |
| 722 | .TP |
| 723 | .BI "ping-peer-died" |
| 724 | The peer was killed (probably by another admin connection) before a |
| 725 | response was received. |
| 726 | .RE |
| 727 | .IP |
| 728 | Options recognized for this command are: |
| 729 | .RS |
| 730 | .\"+opts |
| 731 | .TP |
| 732 | .BI "\-background " tag |
| 733 | Run the command in the background, using the given |
| 734 | .IR tag . |
| 735 | .TP |
| 736 | .BI "\-timeout " time |
| 737 | Wait for |
| 738 | .I time |
| 739 | seconds before giving up on a response. The default is 5 seconds. The |
| 740 | .I time |
| 741 | is expressed as a nonnegative integer followed optionally by |
| 742 | .BR d , |
| 743 | .BR h , |
| 744 | .BR m , |
| 745 | or |
| 746 | .BR s |
| 747 | for days, hours, minutes, or seconds respectively; if no suffix is |
| 748 | given, seconds are assumed. |
| 749 | .\"-opts |
| 750 | .RE |
| 751 | .SP |
| 752 | .B "PORT" |
| 753 | .RI [ family ] |
| 754 | Emits an |
| 755 | .B INFO |
| 756 | line containing just the number of the UDP port used by the |
| 757 | .B tripe |
| 758 | server, for the given address |
| 759 | .I family |
| 760 | (or one chosen arbitrarily if omitted -- though |
| 761 | .B tripe |
| 762 | tries to use the same port number consistently so this is not a likely |
| 763 | problem in practice). If you've allowed your server to allocate a port |
| 764 | dynamically, this is how to find out which one it chose. |
| 765 | .SP |
| 766 | .B "RELOAD" |
| 767 | Instructs the server to recheck its keyring files. The server checks |
| 768 | these periodically anyway but it may be necessary to force a recheck, |
| 769 | for example after adding a new peer key. |
| 770 | .SP |
| 771 | .B "QUIT" |
| 772 | Instructs the server to exit immediately. A warning is sent. |
| 773 | .SP |
| 774 | .B "SERVINFO" |
| 775 | Returns information about the server, in the form of key-value pairs. |
| 776 | The following keys are used. |
| 777 | .RS |
| 778 | .TP |
| 779 | .B implementation |
| 780 | A keyword naming the implementation of the |
| 781 | .BR tripe (8) |
| 782 | server. The current implementation is called |
| 783 | .BR edgeware-tripe . |
| 784 | .TP |
| 785 | .B version |
| 786 | The server's version number, as reported by |
| 787 | .BR VERSION . |
| 788 | .TP |
| 789 | .B daemon |
| 790 | Either |
| 791 | .B t |
| 792 | or |
| 793 | .BR nil , |
| 794 | if the server has or hasn't (respectively) become a daemon. |
| 795 | .RE |
| 796 | .SP |
| 797 | .BI "SETIFNAME " peer " " new-name |
| 798 | Informs the server that the |
| 799 | .IR peer 's |
| 800 | tunnel-interface name has been changed to |
| 801 | .IR new-name . |
| 802 | This is useful if firewalling decisions are made based on interface |
| 803 | names: a setup script for a particular peer can change the name, and |
| 804 | then update the server's records so that they're accurate. |
| 805 | .SP |
| 806 | .BI "STATS " peer |
| 807 | Emits a number of |
| 808 | .B INFO |
| 809 | lines, each containing one or more statistics in the form |
| 810 | .IB name = value \fR. |
| 811 | The statistics-gathering is experimental and subject to change. |
| 812 | .SP |
| 813 | .BI "SVCCLAIM " service " " version |
| 814 | Attempts to claim the named |
| 815 | .IR service , |
| 816 | offering the given |
| 817 | .IR version . |
| 818 | The claim is successful if the service is currently unclaimed, or if |
| 819 | a version earlier than |
| 820 | .I version |
| 821 | is provided; otherwise the command fails with the error |
| 822 | .BR "service-exists" . |
| 823 | .SP |
| 824 | .BI "SVCENSURE " service " \fR[" version \fR] |
| 825 | Ensure that |
| 826 | .I service |
| 827 | is provided, and (if specified) to at least the given |
| 828 | .IR version . |
| 829 | An error is reported if these conditions are not met; otherwise the |
| 830 | command succeeds silently. |
| 831 | .SP |
| 832 | .BI "SVCFAIL " jobid " " tokens \fR... |
| 833 | Send a |
| 834 | .B FAIL |
| 835 | (or |
| 836 | .BR BGFAIL ) |
| 837 | response to the service job with the given |
| 838 | .IR jobid , |
| 839 | passing the |
| 840 | .I tokens |
| 841 | as the reason for failure. The job is closed. |
| 842 | .SP |
| 843 | .BI "SVCINFO " jobid " " tokens \fR... |
| 844 | Send an |
| 845 | .B INFO |
| 846 | (or |
| 847 | .BR BGINFO ) |
| 848 | response to the service job with the given |
| 849 | .IR jobid , |
| 850 | passing the |
| 851 | .I tokens |
| 852 | as the info message. The job remains open. |
| 853 | .SP |
| 854 | .B "SVCLIST" |
| 855 | Output a line of the form |
| 856 | .RS |
| 857 | .IP |
| 858 | .B INFO |
| 859 | .I service |
| 860 | .I version |
| 861 | .PP |
| 862 | for each service currently provided. |
| 863 | .RE |
| 864 | .SP |
| 865 | .BI "SVCOK " jobid |
| 866 | Send an |
| 867 | .B OK |
| 868 | (or |
| 869 | .BR BGINFO ) |
| 870 | response to the service job with the given |
| 871 | .IR jobid . |
| 872 | The job is closed. |
| 873 | .SP |
| 874 | .BI "SVCQUERY " service |
| 875 | Emits a number of |
| 876 | .B info |
| 877 | lines in key-value format, describing the named |
| 878 | .IR service. |
| 879 | The following keys are used. |
| 880 | .RS |
| 881 | .TP |
| 882 | .B name |
| 883 | The service's name. |
| 884 | .TP |
| 885 | .B version |
| 886 | The service's version string. |
| 887 | .RE |
| 888 | .SP |
| 889 | .BI "SVCRELEASE " service |
| 890 | Announce that the client no longer wishes to provide the named |
| 891 | .IR service . |
| 892 | .SP |
| 893 | .BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR... |
| 894 | Submit a job to the provider of the given |
| 895 | .IR service , |
| 896 | passing it the named |
| 897 | .I command |
| 898 | and the given |
| 899 | .IR arguments . |
| 900 | The following options are accepted. |
| 901 | .RS |
| 902 | .\"+opts |
| 903 | .TP |
| 904 | .BI "\-background " tag |
| 905 | Run the command in the background, using the given |
| 906 | .IR tag . |
| 907 | .TP |
| 908 | .BI "\-version " version |
| 909 | Ensure that at least the given |
| 910 | .I version |
| 911 | of the service is available before submitting the job. |
| 912 | .RE |
| 913 | .\"-opts |
| 914 | .SP |
| 915 | .BR "TRACE " [\fIoptions\fP] |
| 916 | Selects trace outputs: see |
| 917 | .B "Trace lists" |
| 918 | above. Message types provided are: |
| 919 | .RS |
| 920 | .PP |
| 921 | Currently, the following tracing options are supported: |
| 922 | .TP |
| 923 | .B t |
| 924 | Tunnel events: reception of packets to be encrypted, and injection of |
| 925 | successfully-decrypted packets. |
| 926 | .TP |
| 927 | .B r |
| 928 | Peer management events: creation and destruction of peer attachments, |
| 929 | and arrival of messages. |
| 930 | .TP |
| 931 | .B a |
| 932 | Administration interface: acceptance of new connections, and handling of |
| 933 | the backgroud name-resolution required by the |
| 934 | .B ADD |
| 935 | command. |
| 936 | .TP |
| 937 | .B s |
| 938 | Handling of symmetric keysets: creation and expiry of keysets, and |
| 939 | encryption and decryption of messages. |
| 940 | .TP |
| 941 | .B x |
| 942 | Key exchange: reception, parsing and emission of key exchange messages. |
| 943 | .TP |
| 944 | .B m |
| 945 | Key management: loading keys and checking for file modifications. |
| 946 | .TP |
| 947 | .B l |
| 948 | Display information about challenge issuing and verification. |
| 949 | .TP |
| 950 | .B p |
| 951 | Display contents of packets sent and received by the tunnel and/or peer |
| 952 | modules. |
| 953 | .TP |
| 954 | .B c |
| 955 | Display inputs, outputs and intermediate results of cryptographic |
| 956 | operations. This includes plaintext and key material. Use with |
| 957 | caution. |
| 958 | .TP |
| 959 | .B A |
| 960 | All of the above. |
| 961 | .PP |
| 962 | Note that the |
| 963 | .B p |
| 964 | (packet contents) |
| 965 | and |
| 966 | .B c |
| 967 | (crypto details) |
| 968 | outputs provide extra detail for other outputs. Specifying |
| 969 | .B p |
| 970 | without |
| 971 | .BR r |
| 972 | or |
| 973 | .B t |
| 974 | isn't useful; neither is specifying |
| 975 | .B c |
| 976 | without one of |
| 977 | .BR s , |
| 978 | .BR l , |
| 979 | .B x |
| 980 | or |
| 981 | .BR m . |
| 982 | .RE |
| 983 | .SP |
| 984 | .B "TUNNELS" |
| 985 | For each available tunnel driver, an |
| 986 | .B INFO |
| 987 | line is printed giving its name. |
| 988 | .SP |
| 989 | .B "VERSION" |
| 990 | Causes the server to emit an |
| 991 | .B INFO |
| 992 | line stating its software version, as two tokens: the server name, and |
| 993 | its version string. The server name |
| 994 | .B tripe |
| 995 | is reserved to the Straylight/Edgeware implementation. |
| 996 | .SP |
| 997 | .BR "WATCH " [\fIoptions\fP] |
| 998 | Enables or disables asynchronous broadcasts |
| 999 | .IR "for the current connection only" . |
| 1000 | See |
| 1001 | .B "Trace lists" |
| 1002 | above. The default watch state for the connection the server opens |
| 1003 | automatically on stdin/stdout is to show warnings and trace messages; |
| 1004 | other connections show no asynchronous broadcast messages. (This is |
| 1005 | done in order to guarantee that a program reading the server's stdout |
| 1006 | does not miss any warnings.) |
| 1007 | .RS |
| 1008 | .PP |
| 1009 | Message types provided are: |
| 1010 | .TP |
| 1011 | .B t |
| 1012 | .B TRACE |
| 1013 | messages. |
| 1014 | .TP |
| 1015 | .B n |
| 1016 | .B NOTE |
| 1017 | messages. |
| 1018 | .TP |
| 1019 | .B w |
| 1020 | .B WARN |
| 1021 | messages. |
| 1022 | .TP |
| 1023 | .B A |
| 1024 | All of the above. |
| 1025 | .RE |
| 1026 | .SP |
| 1027 | .BI "WARN " tokens\fR... |
| 1028 | Issues a |
| 1029 | .B USER |
| 1030 | warning to all interested administration clients. |
| 1031 | . |
| 1032 | .\"-------------------------------------------------------------------------- |
| 1033 | .SH "ERROR MESSAGES" |
| 1034 | . |
| 1035 | .\"* 20 Error messages (FAIL codes) |
| 1036 | The following |
| 1037 | .B FAIL |
| 1038 | (or |
| 1039 | .BR BGFAIL ) |
| 1040 | messages are sent to clients as a result of errors during command |
| 1041 | processing. |
| 1042 | .SP |
| 1043 | .BI "already-daemon" |
| 1044 | (For |
| 1045 | .BR DAEMON .) |
| 1046 | The |
| 1047 | .B tripe |
| 1048 | server is already running as a daemon. |
| 1049 | .SP |
| 1050 | .BI "bad-addr-syntax " message |
| 1051 | (For commands accepting socket addresses.) The address couldn't be |
| 1052 | understood. |
| 1053 | .SP |
| 1054 | .BI "bad-base64 " message |
| 1055 | (For commands accepting Base64-encoded input.) The Base64-encoded |
| 1056 | string was invalid. |
| 1057 | .SP |
| 1058 | .BI "bad-syntax " cmd " " message |
| 1059 | (For any command.) The command couldn't be understood: e.g., the number |
| 1060 | of arguments was wrong. |
| 1061 | .SP |
| 1062 | .BI "bad-time-spec " token |
| 1063 | The |
| 1064 | .I token |
| 1065 | is not a valid time interval specification. Acceptable time |
| 1066 | specifications are nonnegative integers followed optionally by |
| 1067 | .BR d , |
| 1068 | .BR h , |
| 1069 | .BR m , |
| 1070 | or |
| 1071 | .BR s , |
| 1072 | for days, hours, minutes, or seconds, respectively. |
| 1073 | .SP |
| 1074 | .BI "bad-trace-option " char |
| 1075 | (For |
| 1076 | .BR TRACE .) |
| 1077 | An unknown trace option was requested. |
| 1078 | .SP |
| 1079 | .BI "bad-watch-option " char |
| 1080 | (For |
| 1081 | .BR WATCH .) |
| 1082 | An unknown watch option was requested. |
| 1083 | .SP |
| 1084 | .BI "daemon-error " ecode " " message |
| 1085 | (For |
| 1086 | .BR DAEMON .) |
| 1087 | An error occurred during the attempt to become a daemon, as reported by |
| 1088 | .IR message . |
| 1089 | .SP |
| 1090 | .BI "disabled-address-family " afam |
| 1091 | (For |
| 1092 | .B ADD |
| 1093 | and |
| 1094 | .BR PORT .) |
| 1095 | The address family |
| 1096 | .I afam |
| 1097 | is supported, but was disabled using command-line arguments. |
| 1098 | .SP |
| 1099 | .BI "invalid-port " number |
| 1100 | (For |
| 1101 | .BR ADD .) |
| 1102 | The given port number is out of range. |
| 1103 | .SP |
| 1104 | .BI "not-service-provider " service |
| 1105 | (For |
| 1106 | .BR SVCRELEASE .) |
| 1107 | The invoking client is not the current provider of the named |
| 1108 | .IR service , |
| 1109 | and is therefore not allowed to release it. |
| 1110 | .SP |
| 1111 | .BI "peer-create-fail " peer |
| 1112 | (For |
| 1113 | .BR ADD .) |
| 1114 | Adding |
| 1115 | .I peer |
| 1116 | failed for some reason. A warning should have been emitted explaining |
| 1117 | why. |
| 1118 | .SP |
| 1119 | .BI "peer-addr-exists " address\fR... |
| 1120 | (For |
| 1121 | .BR ADD .) |
| 1122 | There is already a peer with the given |
| 1123 | .IR address . |
| 1124 | .SP |
| 1125 | .BI "peer-exists " peer |
| 1126 | (For |
| 1127 | .BR ADD .) |
| 1128 | There is already a peer named |
| 1129 | .IR peer . |
| 1130 | .SP |
| 1131 | .B "ping-send-failed" |
| 1132 | The attempt to send a ping packet failed, probably due to lack of |
| 1133 | encryption keys. |
| 1134 | .SP |
| 1135 | .B "provider-failed" |
| 1136 | (For |
| 1137 | .BR SVCSUBMIT .) |
| 1138 | The service provider disconnected without sending back a final reply to |
| 1139 | the job. |
| 1140 | .SP |
| 1141 | .B "provider-overloaded" |
| 1142 | (For |
| 1143 | .BR SVCSUBMIT .) |
| 1144 | The service provider has too many jobs queued up for it already. |
| 1145 | .SP |
| 1146 | .BI "resolve-error " hostname |
| 1147 | (For |
| 1148 | .BR ADD .) |
| 1149 | The DNS name |
| 1150 | .I hostname |
| 1151 | could not be resolved. |
| 1152 | .SP |
| 1153 | .BI "resolver-timeout " hostname |
| 1154 | (For |
| 1155 | .BR ADD .) |
| 1156 | The DNS name |
| 1157 | .I hostname |
| 1158 | took too long to resolve. |
| 1159 | .SP |
| 1160 | .BI "service-exists " service " " version |
| 1161 | (For |
| 1162 | .BR SVCCLAIM .) |
| 1163 | Another client is already providing the stated |
| 1164 | .I version |
| 1165 | of the |
| 1166 | .IR service . |
| 1167 | .SP |
| 1168 | .BI "service-too-old " service " " version |
| 1169 | (For |
| 1170 | .B SVCENSURE |
| 1171 | and |
| 1172 | .BR SVCSUBMIT .) |
| 1173 | Only the given |
| 1174 | .I version |
| 1175 | of the requested |
| 1176 | .I service |
| 1177 | is available, which does not meet the stated requirements. |
| 1178 | .SP |
| 1179 | .BI "tag-exists " tag |
| 1180 | (For long-running commands.) The named |
| 1181 | .I tag |
| 1182 | is already the tag of an outstanding job. |
| 1183 | .SP |
| 1184 | .BI "unknown-address-family " afam |
| 1185 | (For |
| 1186 | .BR PORT .) |
| 1187 | The address family |
| 1188 | .I afam |
| 1189 | is unrecognized. |
| 1190 | .SP |
| 1191 | .BI "unknown-command " token |
| 1192 | The command |
| 1193 | .I token |
| 1194 | was not recognized. |
| 1195 | .SP |
| 1196 | .BI "unknown-jobid " jobid |
| 1197 | (For |
| 1198 | .BR SVCOK , |
| 1199 | .BR SVCFAIL , |
| 1200 | and |
| 1201 | .BR SVCINFO .) |
| 1202 | The token |
| 1203 | .I jobid |
| 1204 | is not recognized as identifying an outstanding job. It may have just |
| 1205 | been cancelled. |
| 1206 | .SP |
| 1207 | .BI "unknown-peer " name |
| 1208 | (For |
| 1209 | .BR ADDR , |
| 1210 | .BR IFNAME , |
| 1211 | .BR KILL , |
| 1212 | .BR SETIFNAME , |
| 1213 | and |
| 1214 | .BR STATS .) |
| 1215 | There is no peer called |
| 1216 | .IR name . |
| 1217 | .SP |
| 1218 | .BI "unknown-port " port |
| 1219 | (For |
| 1220 | .BR ADD .) |
| 1221 | The port name |
| 1222 | .I port |
| 1223 | couldn't be found in |
| 1224 | .BR /etc/services . |
| 1225 | .SP |
| 1226 | .BI "unknown-service " service |
| 1227 | (For |
| 1228 | .BR SVCENSURE , |
| 1229 | .BR SVCQUERY , |
| 1230 | .BR SVCRELEASE , |
| 1231 | and |
| 1232 | .BR SVCSUBMIT .) |
| 1233 | The token |
| 1234 | .I service |
| 1235 | is not recognized as the name of a client-provided service. |
| 1236 | .SP |
| 1237 | .BI "unknown-tag " tag |
| 1238 | (For |
| 1239 | .BR BGCANCEL .) |
| 1240 | The given |
| 1241 | .I tag |
| 1242 | is not the tag for any outstanding background job. It may have just |
| 1243 | finished. |
| 1244 | .SP |
| 1245 | .BI "unknown-tunnel " tun |
| 1246 | (For |
| 1247 | .BR ADD .) |
| 1248 | The given |
| 1249 | .I tun |
| 1250 | is not the name of any known tunnel driver. |
| 1251 | . |
| 1252 | .\"-------------------------------------------------------------------------- |
| 1253 | .SH "NOTIFICATIONS" |
| 1254 | . |
| 1255 | .\"* 30 Notification broadcasts (NOTE codes) |
| 1256 | The following notifications are sent to clients who request them. |
| 1257 | .SP |
| 1258 | .BI "ADD " peer " " ifname " " address \fR... |
| 1259 | A new peer has been added. The peer's name is |
| 1260 | .IR peer , |
| 1261 | its tunnel is network interface |
| 1262 | .IR ifname , |
| 1263 | and its network address is |
| 1264 | .IR address . |
| 1265 | .SP |
| 1266 | .BI "DAEMON" |
| 1267 | The server has forked off into the sunset and become a daemon. |
| 1268 | .SP |
| 1269 | .BI "GREET " challenge " " address \fR... |
| 1270 | A valid greeting was received, with the given challenge (exactly as it |
| 1271 | was returned by |
| 1272 | .B GETCHAL |
| 1273 | earlier). |
| 1274 | .SP |
| 1275 | .BI "KILL " peer |
| 1276 | The peer |
| 1277 | .I peer |
| 1278 | has been killed. |
| 1279 | .SP |
| 1280 | .BI "KNOCK " peer " " address |
| 1281 | The currently unknown |
| 1282 | .I peer |
| 1283 | is attempting to connect from |
| 1284 | .IR address . |
| 1285 | .SP |
| 1286 | .BI "KXDONE " peer |
| 1287 | Key exchange with |
| 1288 | .I peer |
| 1289 | finished successfully. |
| 1290 | .SP |
| 1291 | .BI "KXSTART " peer |
| 1292 | Key exchange with |
| 1293 | .I peer |
| 1294 | has begun or restarted. If key exchange keeps failing, this message |
| 1295 | will be repeated periodically. |
| 1296 | .SP |
| 1297 | .BI "NEWADDR " peer " " address |
| 1298 | The given mobile |
| 1299 | .IR peer 's |
| 1300 | IP address has been changed to |
| 1301 | .IR address . |
| 1302 | .SP |
| 1303 | .BI "NEWIFNAME " peer " " old-name " " new-name |
| 1304 | The given |
| 1305 | .IR peer 's |
| 1306 | tunnel interface name has been changed from |
| 1307 | .I old-name |
| 1308 | to |
| 1309 | .IR new-name , |
| 1310 | as a result of a |
| 1311 | .B SETIFNAME |
| 1312 | command. |
| 1313 | .SP |
| 1314 | .BI "SVCCLAIM " service " " version |
| 1315 | The named |
| 1316 | .I service |
| 1317 | is now available, at the stated |
| 1318 | .IR version . |
| 1319 | .SP |
| 1320 | .BI "SVCRELEASE " service |
| 1321 | The named |
| 1322 | .I service |
| 1323 | is no longer available. |
| 1324 | .SP |
| 1325 | .BI "USER " tokens\fR... |
| 1326 | An administration client issued a notification using the |
| 1327 | .B NOTIFY |
| 1328 | command. |
| 1329 | . |
| 1330 | .\"-------------------------------------------------------------------------- |
| 1331 | .SH "WARNINGS" |
| 1332 | . |
| 1333 | .\"* 40 Warning broadcasts (WARN codes) |
| 1334 | .\"+sep |
| 1335 | There are many possible warnings. They are categorized according to |
| 1336 | their first tokens. |
| 1337 | .PP |
| 1338 | Many of these warnings report system errors. These are reported as a |
| 1339 | pair of tokens, described below as |
| 1340 | .I ecode |
| 1341 | and |
| 1342 | .IR message . |
| 1343 | The |
| 1344 | .I ecode |
| 1345 | is a string of the form |
| 1346 | .BI E number |
| 1347 | giving the |
| 1348 | .BR errno (3) |
| 1349 | value of the error; the |
| 1350 | .I message |
| 1351 | is the `human-readable' form of the message, as reported by |
| 1352 | .BR strerror (3). |
| 1353 | .SS "ABORT warnings" |
| 1354 | These all indicate that the |
| 1355 | .B tripe |
| 1356 | server has become unable to continue. If enabled, the server will dump |
| 1357 | core in its configuration directory. |
| 1358 | .SP |
| 1359 | .BI "ABORT repeated-select-errors" |
| 1360 | The main event loop is repeatedly failing. If the server doesn't quit, |
| 1361 | it will probably waste all available CPU doing nothing. |
| 1362 | .SP |
| 1363 | .BI "ABORT hash-size-too-large hash " name " size " sz " limit " max |
| 1364 | An internal inconsistency: the hash function |
| 1365 | .I name |
| 1366 | produces a |
| 1367 | .IR sz -byte |
| 1368 | hash, but the server has been compiled to assume that no hash function |
| 1369 | returns more than |
| 1370 | .I max |
| 1371 | bytes. |
| 1372 | .SS "ADMIN warnings" |
| 1373 | These indicate a problem with the administration socket interface. |
| 1374 | .SP |
| 1375 | .BI "ADMIN accept-error " ecode " " message |
| 1376 | There was an error while attempting to accept a connection from a new |
| 1377 | client. |
| 1378 | .SP |
| 1379 | .BI "ADMIN client-write-error " ecode " " message |
| 1380 | There was an error sending data to a client. The connection to the |
| 1381 | client has been closed. |
| 1382 | .SP |
| 1383 | .BI "ADMIN admin-socket " path " already-in-use" |
| 1384 | The server failed to create the Unix-domain socket object in the |
| 1385 | filesystem, because there's already a socket there, and some other |
| 1386 | process is actively listening for incoming connections. |
| 1387 | .SP |
| 1388 | .BI "ADMIN admin-socket " path " bind-failed " ecode " " message |
| 1389 | The server failed to create the Unix-domain socket object in the |
| 1390 | filesystem for an unusual reason. (The usual reason is |
| 1391 | .BR EADDRINUSE , |
| 1392 | but this is handled specially.) |
| 1393 | .SP |
| 1394 | .BI "ADMIN admin-socket " path " chmod-failed " ecode " " message |
| 1395 | The server failed to set the correct permissions of the Unix-domain |
| 1396 | socket object. |
| 1397 | .SP |
| 1398 | .BI "ADMIN admin-socket " path " chown-failed " ecode " " message |
| 1399 | The server failed to set the correct ownership of the Unix-domain socket |
| 1400 | object. |
| 1401 | .SP |
| 1402 | .BI "ADMIN admin-socket " path " create-failed " ecode " " message |
| 1403 | The server failed to create its administration socket. This is usually |
| 1404 | because some system resource is unavailable. |
| 1405 | .SP |
| 1406 | .BI "ADMIN admin-socket " path " listen-failed " ecode " " message |
| 1407 | The server failed to arrange to receive incoming connections on its |
| 1408 | Unix-domain socket. |
| 1409 | .SP |
| 1410 | .BI "ADMIN admin-socket " path " name-too-long" |
| 1411 | The server can't create its administration socket, because the chosen |
| 1412 | pathname |
| 1413 | .I path |
| 1414 | is too long. There is, for historical reasons, a rather tight limit on |
| 1415 | the length of name permitted for Unix-domain sockets, usually around 108 |
| 1416 | bytes. |
| 1417 | .SP |
| 1418 | .BI "ADMIN admin-socket " path " stat-failed " ecode " " message |
| 1419 | The server failed to create the Unix-domain socket object in the |
| 1420 | filesystem, because there's already something there, but the server |
| 1421 | couldn't discover what. |
| 1422 | .SP |
| 1423 | .BI "ADMIN admin-socket " path " too-many-retries" |
| 1424 | The server failed to create the Unix-domain socket object in the |
| 1425 | filesystem. This error indicates that another process is also |
| 1426 | repeatedly trying to create a Unix-domain socket at the same |
| 1427 | .IR path , |
| 1428 | and then failing to actually listen for connections on it, but the |
| 1429 | server always loses the applicable race for some reason. This situation |
| 1430 | merits investigation. |
| 1431 | .SP |
| 1432 | .BI "ADMIN adns-init-failed " ecode " " message |
| 1433 | The server failed to initialize the ADNS asynchronous DNS-resolution |
| 1434 | library. |
| 1435 | .SS "CHAL warnings" |
| 1436 | These indicate errors in challenges, either in the |
| 1437 | .B CHECKCHAL |
| 1438 | command or in greeting packets. |
| 1439 | .SP |
| 1440 | .B "CHAL impossible-challenge" |
| 1441 | The server hasn't issued any challenges yet. Quite how anyone else |
| 1442 | thought they could make one up is hard to imagine. |
| 1443 | .SP |
| 1444 | .B "CHAL incorrect-tag" |
| 1445 | Challenge received contained the wrong authentication data. It might be |
| 1446 | very stale, or a forgery. |
| 1447 | .SP |
| 1448 | .B "CHAL invalid-challenge" |
| 1449 | Challenge received was the wrong length. We might have changed MAC |
| 1450 | algorithms since the challenge was issued, or it might just be rubbish. |
| 1451 | .SP |
| 1452 | .B "CHAL replay duplicated-sequence" |
| 1453 | Challenge received was a definite replay of an old challenge. Someone's |
| 1454 | up to something! |
| 1455 | .SP |
| 1456 | .B "CHAL replay old-sequence" |
| 1457 | Challenge received was old, but maybe not actually a replay. Try again. |
| 1458 | .SS "KEYMGMT warnings" |
| 1459 | These indicate a problem with the keyring files, or the keys stored in |
| 1460 | them. The first token is either |
| 1461 | .B private-keyring |
| 1462 | or |
| 1463 | .B public-keyring |
| 1464 | (notated |
| 1465 | .IB which -keyring |
| 1466 | in the descriptions below) indicating which keyring file is problematic, |
| 1467 | and the second token is the filename of the keyring. Frequently a key |
| 1468 | tag may be given next, preceded by the token |
| 1469 | .BR key . |
| 1470 | .SP |
| 1471 | .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch" |
| 1472 | A peer's public key doesn't request the same algorithms as our private |
| 1473 | key. |
| 1474 | .SP |
| 1475 | .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length " len |
| 1476 | The key attributes specify the length of MAC tag as |
| 1477 | .I len |
| 1478 | but this is an invalid value \(en either too large or not a multiple of |
| 1479 | eight. |
| 1480 | .SP |
| 1481 | .BI "KEYMGMT " which "-keyring " file " key " tag " bad-tag-length-string " str |
| 1482 | The key attributes contain |
| 1483 | .I str |
| 1484 | where a MAC tag length was expected. The key was generated wrongly. |
| 1485 | .SP |
| 1486 | .BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key" |
| 1487 | The private key doesn't record the correct corresponding public key. |
| 1488 | .SP |
| 1489 | .BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message |
| 1490 | A system error occurred while opening or reading the keyring file. |
| 1491 | .SP |
| 1492 | .BI "KEYMGMT private-keyring " file " key " tag " changed-group" |
| 1493 | The private keyring has been changed, but the new private key can't be |
| 1494 | used because it uses a different group for Diffie\(enHellman key |
| 1495 | exchange. |
| 1496 | .SP |
| 1497 | .BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash |
| 1498 | No message authentication code was given explicitly, and there's no |
| 1499 | implementation of HMAC for the selected hash function |
| 1500 | .IR hash . |
| 1501 | .SP |
| 1502 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk |
| 1503 | The key specifies the use of an unknown bulk-crypto transform |
| 1504 | .IR bulk . |
| 1505 | Maybe the key was generated wrongly, or maybe the version of Catacomb |
| 1506 | installed is too old. |
| 1507 | .SP |
| 1508 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher |
| 1509 | The key specifies the use of an unknown symmetric encryption algorithm |
| 1510 | .IR cipher . |
| 1511 | Maybe the key was generated wrongly, or maybe the version of |
| 1512 | Catacomb installed is too old. |
| 1513 | .SP |
| 1514 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-group-type " type |
| 1515 | The key specifies the use of a Diffie\(enHellman group of an unknown |
| 1516 | .IR type . |
| 1517 | Maybe the key was generated wrongly, or maybe the version of |
| 1518 | .BR tripe (8) |
| 1519 | is too old. |
| 1520 | .SP |
| 1521 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-hash " hash |
| 1522 | The key specifies the use of an unknown hash function |
| 1523 | .IR hash . |
| 1524 | Maybe the key was generated wrongly, or maybe the version of Catacomb |
| 1525 | installed is too old. |
| 1526 | .SP |
| 1527 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mac " mac |
| 1528 | The key specifies the use of an unknown message authentication code |
| 1529 | .IR mac . |
| 1530 | Maybe the key was generated wrongly, or maybe the version of Catacomb |
| 1531 | installed is too old. |
| 1532 | .SP |
| 1533 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-mgf-cipher " mgf |
| 1534 | The key specifies the use of an unknown symmetric encryption function |
| 1535 | .I mgf |
| 1536 | for mask generation. Maybe the key was generated wrongly, or maybe the |
| 1537 | version of Catacomb installed is too old. |
| 1538 | .SP |
| 1539 | .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-serialization-format " ser |
| 1540 | The key specifies the use of an unknown serialization format |
| 1541 | .I ser |
| 1542 | for hashing group elements. Maybe the key was generated wrongly, or |
| 1543 | maybe the version of Catacomb installed is too old. |
| 1544 | .SP |
| 1545 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad" |
| 1546 | The key specifies the use of an authenticated encryption scheme |
| 1547 | .I cipher |
| 1548 | which does not support the processing of additional authenticated data. |
| 1549 | The most prominent examples of such schemes are the |
| 1550 | .IB cipher -naclbox |
| 1551 | collection, where |
| 1552 | .I cipher |
| 1553 | is |
| 1554 | .BR salsa20 , |
| 1555 | .BR salsa20/12 , |
| 1556 | .BR salsa20/8 , |
| 1557 | .BR chacha20 , |
| 1558 | .BR chacha12 , |
| 1559 | or |
| 1560 | .BR chacha8 ; |
| 1561 | use the |
| 1562 | .B naclbox |
| 1563 | bulk transform rather than |
| 1564 | .B aead |
| 1565 | for these |
| 1566 | (or switch to the IETF |
| 1567 | .IB cipher -poly1305 |
| 1568 | schemes instead). |
| 1569 | .SP |
| 1570 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small" |
| 1571 | The key specifies the use of an authenticated encryption scheme |
| 1572 | .I cipher |
| 1573 | which doesn't even allow a 5-byte (40-bit) nonce. Catacomb doesn't |
| 1574 | implement any such limited AE schemes: you must be doing something |
| 1575 | strange. |
| 1576 | .SP |
| 1577 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large" |
| 1578 | The key specifies the use of an authenticated encryption scheme |
| 1579 | .I cipher |
| 1580 | which doesn't support any nonce size smaller than 64 bytes (512 bits). |
| 1581 | Catacomb doesn't implement any such extravagant AE schemes: you must be |
| 1582 | doing something strange. |
| 1583 | .SP |
| 1584 | .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message" |
| 1585 | The key specifies the use of an authenticated encryption scheme |
| 1586 | .I cipher |
| 1587 | which produces ciphertext output even when given a completely empty |
| 1588 | message. Catacomb doesn't implement any such unhelpful AE schemes: you |
| 1589 | must be doing something strange. |
| 1590 | .SP |
| 1591 | .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz |
| 1592 | The |
| 1593 | .I alg |
| 1594 | token is either |
| 1595 | .B cipher |
| 1596 | or |
| 1597 | .BR mac . |
| 1598 | The named algorithm requires more key material than the hash function |
| 1599 | can provide. You must change either the hash function, or the cipher or |
| 1600 | MAC. |
| 1601 | .SP |
| 1602 | .BI "KEYMGMT " which "-keyring " file " key " tag " mgf " mgf " restrictive-key-schedule" |
| 1603 | The cipher selected for mask-generation is unsuitable because it can't |
| 1604 | accept arbitrary-sized keys. |
| 1605 | .SP |
| 1606 | .BI "KEYMGMT " which "-keyring " file " key-not-found " tag |
| 1607 | A key named |
| 1608 | .I tag |
| 1609 | couldn't be found in the keyring. |
| 1610 | .SP |
| 1611 | .BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid |
| 1612 | A key with the given |
| 1613 | .I keyid |
| 1614 | (in hex) was requested but not found. |
| 1615 | .SP |
| 1616 | .BI "KEYMGMT " which "-keyring " file " line " line " " message |
| 1617 | The contents of the keyring file are invalid. There may well be a bug |
| 1618 | in the |
| 1619 | .BR key (1) |
| 1620 | program. |
| 1621 | .SS "KX warnings" |
| 1622 | These indicate problems during key-exchange. Many indicate either a bug |
| 1623 | in the server (either yours or the remote one), or some kind of attack |
| 1624 | in progress. All name a |
| 1625 | .I peer |
| 1626 | as the second token: this is the peer the packet is apparently from, |
| 1627 | though it may have been sent by an attacker instead. |
| 1628 | .PP |
| 1629 | In the descriptions below, |
| 1630 | .I msgtoken |
| 1631 | is one of the tokens |
| 1632 | .BR pre-challenge , |
| 1633 | .BR cookie , |
| 1634 | .BR challenge , |
| 1635 | .BR reply , |
| 1636 | .BR switch-rq , |
| 1637 | .BR switch-ok . |
| 1638 | .BR token-rq , |
| 1639 | .BR token , |
| 1640 | or |
| 1641 | .BR knock . |
| 1642 | .SP |
| 1643 | .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag |
| 1644 | The algorithms specified in the peer's public key |
| 1645 | .I pubtag |
| 1646 | don't match the ones described in the private key |
| 1647 | .IR privtag . |
| 1648 | .SP |
| 1649 | .BI "KX " peer " bad-expected-reply-log" |
| 1650 | The challenges |
| 1651 | .B tripe |
| 1652 | uses in its protocol contain a check value which proves that the |
| 1653 | challenge is honest. This message indicates that the check value |
| 1654 | supplied is wrong: someone is attempting to use bogus challenges to |
| 1655 | persuade your |
| 1656 | .B tripe |
| 1657 | server to leak private key information. No chance! |
| 1658 | .SP |
| 1659 | .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok" |
| 1660 | A symmetrically-encrypted portion of a key-exchange message failed to |
| 1661 | decrypt. |
| 1662 | .SP |
| 1663 | .BI "KX " peer " invalid " msgtoken |
| 1664 | A key-exchange message was malformed. This almost certainly indicates a |
| 1665 | bug somewhere. |
| 1666 | .SP |
| 1667 | .BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok" |
| 1668 | A message didn't contain the right magic data. This may be a replay of |
| 1669 | some old exchange, or random packets being sent in an attempt to waste |
| 1670 | CPU. |
| 1671 | .SP |
| 1672 | .BI "KX " peer " " which "-key-expired" |
| 1673 | The local private key or the peer's public key (distinguished by |
| 1674 | .IR which ) |
| 1675 | has expired. Either you or the peer's maintainer should have arranged |
| 1676 | for a replacement before now. |
| 1677 | .SP |
| 1678 | .BI "KX " peer " sending-cookie" |
| 1679 | We've received too many bogus pre-challenge messages. Someone is trying |
| 1680 | to flood us with key-exchange messages and make us waste CPU on doing |
| 1681 | hard asymmetric crypto sums. |
| 1682 | .SP |
| 1683 | .BI "KX " peer " unexpected " msgtoken |
| 1684 | The message received wasn't appropriate for this stage of the key |
| 1685 | exchange process. This may mean that one of our previous packets got |
| 1686 | lost. For |
| 1687 | .BR pre-challenge , |
| 1688 | it may simply mean that the peer has recently restarted. |
| 1689 | .SP |
| 1690 | .BI "KX " peer " unknown-challenge" |
| 1691 | The peer is asking for an answer to a challenge which we don't know |
| 1692 | about. This may mean that we've been inundated with challenges from |
| 1693 | some malicious source |
| 1694 | .I who can read our messages |
| 1695 | and discarded the valid one. |
| 1696 | .SP |
| 1697 | .BI "KX " peer " unknown-message 0x" nn |
| 1698 | An unknown key-exchange message arrived. |
| 1699 | .SS "PEER warnings" |
| 1700 | These are largely concerned with management of peers and the low-level |
| 1701 | details of the network protocol. The second token is usually the name of |
| 1702 | a peer, or |
| 1703 | .RB ` \- ' |
| 1704 | if none is relevant. |
| 1705 | .SP |
| 1706 | .BI "PEER " peer " bad-packet no-type" |
| 1707 | An empty packet arrived. This is very strange. |
| 1708 | .SP |
| 1709 | .BI "PEER " peer " bad-packet unknown-category 0x" nn |
| 1710 | The message category |
| 1711 | .I nn |
| 1712 | (in hex) isn't understood. Probably a strange random packet from |
| 1713 | somewhere; could be an unlikely bug. |
| 1714 | .SP |
| 1715 | .BI "PEER " peer " bad-packet unknown-type 0x" nn |
| 1716 | The message type |
| 1717 | .I nn |
| 1718 | (in hex) isn't understood. Probably a strange random packet from |
| 1719 | somewhere; could be an unlikely bug. |
| 1720 | .SP |
| 1721 | .BI "PEER " peer " corrupt-encrypted-ping" |
| 1722 | The peer sent a ping response which matches an outstanding ping, but its |
| 1723 | payload is wrong. There's definitely a bug somewhere. |
| 1724 | .SP |
| 1725 | .BI "PEER " peer " corrupt-transport-ping" |
| 1726 | The peer (apparently) sent a ping response which matches an outstanding |
| 1727 | ping, but its payload is wrong. Either there's a bug, or the bad guys |
| 1728 | are playing tricks on you. |
| 1729 | .SP |
| 1730 | .BI "PEER " peer " decrypt-failed" |
| 1731 | An encrypted IP packet failed to decrypt. It may have been mangled in |
| 1732 | transit, or may be a very old packet from an expired previous session |
| 1733 | key. There is usually a considerable overlap in the validity periods of |
| 1734 | successive session keys, so this shouldn't occur unless the key exchange |
| 1735 | takes ages or fails. |
| 1736 | .SP |
| 1737 | .BI "PEER " peer " malformed-encrypted-ping" |
| 1738 | The peer sent a ping response which is hopelessly invalid. There's |
| 1739 | definitely a bug somewhere. |
| 1740 | .SP |
| 1741 | .BI "PEER " peer " malformed-transport-ping" |
| 1742 | The peer (apparently) sent a ping response which is hopelessly invalid. |
| 1743 | Either there's a bug, or the bad guys are playing tricks on you. |
| 1744 | .SP |
| 1745 | .BI "PEER " peer " packet-build-failed" |
| 1746 | There wasn't enough space in our buffer to put the packet we wanted to |
| 1747 | send. Shouldn't happen. |
| 1748 | .SP |
| 1749 | .BI "PEER \- socket-read-error " ecode " " message |
| 1750 | An error occurred trying to read an incoming packet. |
| 1751 | .SP |
| 1752 | .BI "PEER " peer " socket-write-error " ecode " " message |
| 1753 | An error occurred attempting to send a network packet. We lost that |
| 1754 | one. |
| 1755 | .SP |
| 1756 | .BI "PEER " address\fR... " disabled-address-family" |
| 1757 | An attempt was made to send a packet to an address for which support was |
| 1758 | switched off by command-line options. |
| 1759 | .SP |
| 1760 | .BI "PEER " address\fR... " socket-write-error " ecode " " message |
| 1761 | An error occurred attempting to send a network packet. We lost that |
| 1762 | one. |
| 1763 | .SP |
| 1764 | .BI "PEER \- udp-socket " address-family " bind-failed " ecode " " message |
| 1765 | The server failed to associate a UDP socket with a local address. |
| 1766 | .SP |
| 1767 | .BI "PEER \- udp-socket " address-family " create-failed " ecode " " message |
| 1768 | The server failed to create a UDP socket for the |
| 1769 | .IR address-family . |
| 1770 | .SP |
| 1771 | .BI "PEER \- udp-socket " address-family " read-local-address-failed " ecode " " message |
| 1772 | The server failed to discover the local address for one of its own UDP |
| 1773 | sockets. |
| 1774 | .SP |
| 1775 | .BI "PEER \- udp-socket " address-family " set-buffers-failed " ecode " " message |
| 1776 | The server failed to configure appropriate buffer sizes on a UDP socket. |
| 1777 | .SP |
| 1778 | .BI "PEER \- udp-socket INET6 set-v6only-failed " ecode " " message |
| 1779 | The server failed to configure an IPv6 socket not to try to collect IPv4 |
| 1780 | traffic too. |
| 1781 | .SP |
| 1782 | .BI "PEER " peer " unexpected-encrypted-ping 0x" id |
| 1783 | The peer sent an encrypted ping response whose id doesn't match any |
| 1784 | outstanding ping. Maybe it was delayed for longer than the server was |
| 1785 | willing to wait, or maybe the peer has gone mad. |
| 1786 | .SP |
| 1787 | .BI "PEER \- unexpected-source " address\fR... |
| 1788 | A packet arrived from |
| 1789 | .I address |
| 1790 | (a network address \(en see above), but no peer is known at that |
| 1791 | address. This may indicate a misconfiguration, or simply be a result of |
| 1792 | one end of a connection being set up before the other. |
| 1793 | .SP |
| 1794 | .BI "PEER " peer " unexpected-transport-ping 0x" id |
| 1795 | The peer (apparently) sent a transport ping response whose id doesn't |
| 1796 | match any outstanding ping. Maybe it was delayed for longer than the |
| 1797 | server was willing to wait, or maybe the peer has gone mad; or maybe |
| 1798 | there are bad people trying to confuse you. |
| 1799 | .SS "PRIVSEP warnings" |
| 1800 | These indicate problems with the privilege-separation helper process. |
| 1801 | (The server tries to drop its privileges when it starts up, leaving a |
| 1802 | privileged helper process behind which will create and hand over tunnel |
| 1803 | descriptors on request, but hopefully not do anything else especially |
| 1804 | dangerous. Tunnel descriptors are not completely safe, but this is |
| 1805 | probably better than nothing.) |
| 1806 | .SP |
| 1807 | .BI "PRIVSEP child-exited " rc |
| 1808 | The helper process exited normally with status |
| 1809 | .IR rc . |
| 1810 | Status 0 means that it thought the server didn't want it any more; 1 |
| 1811 | means that it was invoked incorrectly; 127 means that some system call |
| 1812 | failed. |
| 1813 | .SP |
| 1814 | .BI "PRIVSEP child-killed " sig |
| 1815 | The helper process was killed by signal number |
| 1816 | .IR sig . |
| 1817 | .SP |
| 1818 | .BI "PRIVSEP child-died " status |
| 1819 | The helper process died in some unexpected way; |
| 1820 | .I status is the raw status code returned by |
| 1821 | .BR waitpid (2), |
| 1822 | because the server didn't understand how to decode it. |
| 1823 | .SP |
| 1824 | .BI "PRIVSEP helper-died" |
| 1825 | A tunnel driver requires a tunnel descriptor from the helper, but the |
| 1826 | helper isn't running so this won't work. |
| 1827 | .SP |
| 1828 | .BI "PRIVSEP helper-read-error " ecode " " message |
| 1829 | The server failed to read a response from the helper process. |
| 1830 | .SP |
| 1831 | .BI "PRIVSEP helper-short-read" |
| 1832 | The helper process didn't send back enough data, and has likely crashed. |
| 1833 | .SP |
| 1834 | .BI "PRIVSEP helper-write-error " ecode " " message |
| 1835 | The server failed to send a message to the helper process. |
| 1836 | .SP |
| 1837 | .BI "PRIVSEP no-fd-from-helper" |
| 1838 | The helper process sent back a positive response, but didn't include the |
| 1839 | requested tunnel descriptor. |
| 1840 | .SP |
| 1841 | .BI "PRIVSEP socketpair-create-failed " ecode " " message |
| 1842 | The server couldn't create the socketpair it's supposed to use to |
| 1843 | communicate with the helper process. |
| 1844 | .SP |
| 1845 | .BI "PRIVSEP unknown-response-code" |
| 1846 | The helper process sent back an incomprehensible reply. It's probably |
| 1847 | very confused and may crash. |
| 1848 | .SS "SERVER warnings" |
| 1849 | These indicate problems concerning the server process as a whole. |
| 1850 | .SP |
| 1851 | .BI "SERVER ignore signal " name |
| 1852 | A signal arrived, but the server ignored it. Currently this happens for |
| 1853 | .B SIGHUP |
| 1854 | because that's a popular way of telling daemons to re-read their |
| 1855 | configuration files. Since |
| 1856 | .B tripe |
| 1857 | re-reads its keyrings automatically and has no other configuration |
| 1858 | files, it's not relevant, but it seemed better to ignore the signal than |
| 1859 | let the server die. |
| 1860 | .SP |
| 1861 | .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR] |
| 1862 | A signal arrived and |
| 1863 | .B tripe |
| 1864 | is going to quit. |
| 1865 | .SP |
| 1866 | .BI "SERVER quit admin-request" |
| 1867 | A client of the administration interface issued a |
| 1868 | .B QUIT |
| 1869 | command. |
| 1870 | .SP |
| 1871 | .BI "SERVER daemon-error " ecode " " message |
| 1872 | The server failed to become a daemon during initialization. |
| 1873 | .SP |
| 1874 | .BI "SERVER quit foreground-eof" |
| 1875 | The server is running in foreground mode (the |
| 1876 | .B \-F |
| 1877 | option), and encountered end-of-file on standard input. |
| 1878 | .SP |
| 1879 | .BI "SERVER select-error " ecode " " message |
| 1880 | An error occurred in the server's main event loop. This is bad: if it |
| 1881 | happens too many times, the server will abort. |
| 1882 | .SP |
| 1883 | .BI "SERVER waitpid-error " ecode " " message |
| 1884 | The server was informed that one of its child processes had exited, but |
| 1885 | couldn't retrieve the child's status. |
| 1886 | .SS "SYMM warnings" |
| 1887 | These are concerned with the symmetric encryption and decryption |
| 1888 | process. |
| 1889 | .SP |
| 1890 | .BI "SYMM replay old-sequence" |
| 1891 | A packet was received with an old sequence number. It may just have |
| 1892 | been delayed or duplicated, or it may have been an attempt at a replay |
| 1893 | attack. |
| 1894 | .SP |
| 1895 | .BI "SYMM replay duplicated-sequence" |
| 1896 | A packet was received with a sequence number we've definitely seen |
| 1897 | before. It may be an accidental duplication because the 'net is like |
| 1898 | that, or a deliberate attempt at a replay. |
| 1899 | .SS "TUN warnings" |
| 1900 | These concern the workings of the system-specific tunnel driver. The |
| 1901 | second token is the name of the tunnel interface in question, or |
| 1902 | .RB ` \- ' |
| 1903 | if none. |
| 1904 | .SP |
| 1905 | .BI "TUN \- bsd no-tunnel-devices" |
| 1906 | The driver couldn't find an available tunnel device. Maybe if you |
| 1907 | create some more |
| 1908 | .BI /dev/tun nn |
| 1909 | files, it will work. |
| 1910 | .SP |
| 1911 | .BI "TUN \- " tun-name " open-error " device " " ecode " " message |
| 1912 | An attempt to open the tunnel device file |
| 1913 | .I device |
| 1914 | failed. |
| 1915 | .SP |
| 1916 | .BI "TUN \- linux config-error " ecode " " message |
| 1917 | Configuring the Linux TUN/TAP interface failed. |
| 1918 | .SP |
| 1919 | .BI "TUN " ifname " " tun-name " read-error " ecode " " message |
| 1920 | Reading from the tunnel device failed. |
| 1921 | .SP |
| 1922 | .BI "TUN " ifname " " tun-name " write-error " ecode " " message |
| 1923 | Writing from the tunnel device failed. |
| 1924 | .SP |
| 1925 | .BI "TUN " ifname " slip bad-escape" |
| 1926 | The SLIP driver encountered a escaped byte it wasn't expecting to see. |
| 1927 | The erroneous packet will be ignored. |
| 1928 | .SP |
| 1929 | .BI "TUN \- slip bad-interface-list" |
| 1930 | The interface list, in the |
| 1931 | .B TRIPE_SLIPIF |
| 1932 | environment variable, is malformed. |
| 1933 | .SP |
| 1934 | .BI "TUN " ifname " slip eof" |
| 1935 | The SLIP driver encountered end-of-file on its input descriptor. |
| 1936 | Pending data is discarded, and no attempt is made to read any more data |
| 1937 | from that interface ever. |
| 1938 | .SP |
| 1939 | .BI "TUN " ifname " slip escape-end" |
| 1940 | The SLIP driver encountered an escaped `end' marker. This probably |
| 1941 | means that someone's been sending it junk. The erroneous packet is |
| 1942 | discarded, and we hope that we've rediscovered synchronization. |
| 1943 | .SP |
| 1944 | .BI "TUN \- slip fork-error " ecode " " message |
| 1945 | The SLIP driver encountered an error forking a child process while |
| 1946 | allocating a new dynamic interface. |
| 1947 | .SP |
| 1948 | .BI "TUN \- slip no-slip-interfaces" |
| 1949 | The driver ran out of static SLIP interfaces. Either preallocate more, |
| 1950 | or use dynamic SLIP interface allocation. |
| 1951 | .SP |
| 1952 | .BI "TUN " ifname " slip overflow" |
| 1953 | The SLIP driver gave up reading a packet because it got too large. |
| 1954 | .SP |
| 1955 | .BI "TUN \- slip pipe-error " ecode " " message |
| 1956 | The SLIP driver encountered an error creating pipes while allocating a |
| 1957 | new dynamic interface. |
| 1958 | .SP |
| 1959 | .BI "TUN \- slip read-ifname-failed " ecode " " message |
| 1960 | The SLIP driver encountered an error reading the name of a dynamically |
| 1961 | allocated interface. Maybe the allocation script is broken. |
| 1962 | .SP |
| 1963 | .BI "TUN \- unet config-error " ecode " " message |
| 1964 | Configuring the Linux Unet interface failed. Unet is obsolete and |
| 1965 | shouldn't be used any more. |
| 1966 | .SP |
| 1967 | .BI "TUN \- unet getinfo-error " ecode " " message |
| 1968 | Reading information about the Unet interface failed. Unet is obsolete |
| 1969 | and shouldn't be used any more. |
| 1970 | .SS "USER warnings" |
| 1971 | These are issued by administration clients using the |
| 1972 | .B WARN |
| 1973 | command. |
| 1974 | .SP |
| 1975 | .BI "USER " tokens\fR... |
| 1976 | An administration client issued a warning. |
| 1977 | .\"-sep |
| 1978 | . |
| 1979 | .\"-------------------------------------------------------------------------- |
| 1980 | .SH "SUMMARY" |
| 1981 | . |
| 1982 | .SS "Command responses" |
| 1983 | .nf |
| 1984 | .BI "BGDETACH " tag |
| 1985 | .BI "BGFAIL " tag " " tokens \fR... |
| 1986 | .BI "BGINFO " tag " " tokens \fR... |
| 1987 | .BI "BGOK " tag |
| 1988 | .BI "FAIL " tokens \fR... |
| 1989 | .BI "INFO " tokens \fR... |
| 1990 | .B OK |
| 1991 | .fi |
| 1992 | .\"= summary |
| 1993 | . |
| 1994 | .\"-------------------------------------------------------------------------- |
| 1995 | .SH "SEE ALSO" |
| 1996 | . |
| 1997 | .BR tripectl (1), |
| 1998 | .BR tripe (8). |
| 1999 | .PP |
| 2000 | .IR "The Trivial IP Encryption Protocol" . |
| 2001 | . |
| 2002 | .\"-------------------------------------------------------------------------- |
| 2003 | .SH "AUTHOR" |
| 2004 | . |
| 2005 | Mark Wooding, <mdw@distorted.org.uk> |
| 2006 | . |
| 2007 | .\"----- That's all, folks -------------------------------------------------- |