X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/11ad66c29764521f87f0dd399a1e592147c7af36..acd781a81901f9785125ea2c4c99d5d0952eecdd:/server/tripe-admin.5.in diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in index df87b709..698e2a69 100644 --- a/server/tripe-admin.5.in +++ b/server/tripe-admin.5.in @@ -251,21 +251,50 @@ the meanings of the subsequent tokens depend on the address family. Address family tokens are not case-sensitive on input; on output, they are always in upper-case. .PP -At present, only one address family is understood. +The following address families are recognized. +.TP +.BI "ANY " address " \fR[" port \fR] +An address and port number for any supported address family. On output, +.B tripe +never uses this form. On input, the +.I address +is examined: if it is a numeric address for some recognized address +family, then it is interpreted as such; otherwise it is looked up using +the DNS (in the background). The background resolver's address-sorting +rules apply, and +.B tripe +simply takes the first address in the returned list which is of a +supported address family. Symbolic port numbers are permitted; if +omitted, the default port 4070 is used. .TP .BI "INET " address " \fR[" port \fR] An Internet socket, naming an IPv4 address and UDP port. On output, the -address is always in numeric dotted-quad form, and the port is given as -a plain number. On input, DNS hostnames and symbolic port names are -permitted; if omitted, the default port 4070 is used. Name resolution -does not block the main server, but will block the requesting client, -unless the command is run in the background. +.I address +is always in numeric dotted-quad form, and the +.I port +is given as a plain decimal number. On input, DNS hostnames and +symbolic port names are permitted; if omitted, the default port 4070 is +used. +.TP +.BI "INET6 " address " \fR[" port \fR] +An Internet socket, naming an IPv6 address and UDP port. On output, the +.I address +is always in numeric hex-and-colons form, and the +.I port +is given as a plain decimal number. On input, DNS hostnames and +symbolic port names may be permitted, depending on how +.B tripe +was compiled; if omitted, the default port 4070 is used. .PP If, on input, no recognized address family token is found, the following tokens are assumed to represent an -.B INET +.B ANY address. Addresses output by the server always have an address family -token. +token, and do not use +.BR ANY . +.PP +Name resolution never blocks the main server, but will block the +requesting client, unless the command is run in the background. .SS "Key-value output" Some commands (e.g., .B STATS @@ -332,6 +361,21 @@ Run the command in the background, using the given Don't send an immediate challenge to the peer; instead, wait until it sends us something before responding. .TP +.B "\-ephemeral" +The association with the peer is not intended to persist indefinitely. +If a peer marked as ephemeral is killed, or the +.BR tripe (8) +daemon is shut down, send a +.B bye +packet to the peer so that it forgets about us; if a peer marked as +ephemeral sends us a +.B bye +packet then it is killed (but in this case no further +.B bye +packet is sent). Peers not marked as ephemeral exhibit neither of these +behaviours; each peer must have the other marked as ephemeral for the +association to be fully torn down if either end kills the other. +.TP .BI "\-keepalive " time Send a no-op packet if we've not sent a packet to the peer in the last .I time @@ -353,6 +397,26 @@ Use the public key to authenticate the peer. The default is to use the key tagged .IR peer . .TP +.BI "\-knock \fR[" prefix .\fR] tag +Send the string +.RI [ prefix\fB. ] tag +in +.B token-rq +and +.B knock +messages to the peer during key-exchange. The string as a whole should +name the local machine to the peer, and +.I tag +should name its public key. When such messages are received from a +currently unknown peer, +.BR tripe (8) +emits a +.B KNOCK +notification stating the peer's (claimed) name and address. The server +will already have verified that the sender is using the peer's private +key by this point. This option implies +.BR \-ephemeral . +.TP .B "\-mobile" The peer is a mobile device, and is likely to change address rapidly. If a packet arrives from an unknown address, the server's usual response @@ -361,7 +425,8 @@ peers, however, it will attempt to decrypt the packet using their keys, and if one succeeds, the server will update its idea of the peer's address and emit an .B NEWADDR -notification. +notification. This option implies +.BR \-ephemeral . .TP .BI "\-priv " tag Use the private key @@ -471,12 +536,16 @@ tunnel interface. If is the MTU of the path to the peer, then the tunnel MTU should be .IP .I MTU -\- 29 \- +\- +.I header-length +\- 9 \- .I bulk-overhead .PP -allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type -octet, and the bulk-crypto transform overhead (which includes the -sequence number). +allowing +.I header-length += 20 (IPv4) or 40 (IPv6) bytes of IP header, 8 bytes of UDP header, a +packet type octet, and the bulk-crypto transform overhead (which +includes the sequence number). .RE .SP .BI "BGCANCEL " tag @@ -572,6 +641,16 @@ The tunnel driver used for this peer. The keepalive interval, in seconds, or zero if no keepalives are to be sent. .TP +.B knock +If present, the string sent to the peer to set up the association; see +the +.B \-knock +option to +.BR ADD , +and the +.B KNOCK +notification. +.TP .B key The (short) key tag being used for the peer, as passed to the .B ADD @@ -594,6 +673,30 @@ since there is no fixed tag used under these circumstances. .B current-private-key The full key tag of the private key currently being used for this association. This may change during the life of the association. +.TP +.B corked +Either +.B t +or +.B nil +depending on whether or not (respectively) key-exchange is waiting for +the peer to initiate. +.TP +.B mobile +Either +.B t +or +.B nil +depending on whether or not (respectively) the peer is expected to +change its address unpredictably. +.TP +.B ephemeral +Either +.B t +or +.B nil +depending on whether the association with the peer is expected to be +temporary or persistent (respectively). .RE .SP .BI "PING \fR[" options "\fR] " peer @@ -647,12 +750,18 @@ given, seconds are assumed. .RE .SP .B "PORT" +.RI [ family ] Emits an .B INFO line containing just the number of the UDP port used by the .B tripe -server. If you've allowed your server to allocate a port dynamically, -this is how to find out which one it chose. +server, for the given address +.I family +(or one chosen arbitrarily if omitted -- though +.B tripe +tries to use the same port number consistently so this is not a likely +problem in practice). If you've allowed your server to allocate a port +dynamically, this is how to find out which one it chose. .SP .B "RELOAD" Instructs the server to recheck its keyring files. The server checks @@ -694,6 +803,13 @@ This is useful if firewalling decisions are made based on interface names: a setup script for a particular peer can change the name, and then update the server's records so that they're accurate. .SP +.BI "STATS " peer +Emits a number of +.B INFO +lines, each containing one or more statistics in the form +.IB name = value \fR. +The statistics-gathering is experimental and subject to change. +.SP .BI "SVCCLAIM " service " " version Attempts to claim the named .IR service , @@ -796,13 +912,6 @@ of the service is available before submitting the job. .RE .\"-opts .SP -.BI "STATS " peer -Emits a number of -.B INFO -lines, each containing one or more statistics in the form -.IB name = value \fR. -The statistics-gathering is experimental and subject to change. -.SP .BR "TRACE " [\fIoptions\fP] Selects trace outputs: see .B "Trace lists" @@ -942,6 +1051,10 @@ server is already running as a daemon. (For commands accepting socket addresses.) The address couldn't be understood. .SP +.BI "bad-base64 " message +(For commands accepting Base64-encoded input.) The Base64-encoded +string was invalid. +.SP .BI "bad-syntax " cmd " " message (For any command.) The command couldn't be understood: e.g., the number of arguments was wrong. @@ -974,6 +1087,15 @@ An unknown watch option was requested. An error occurred during the attempt to become a daemon, as reported by .IR message . .SP +.BI "disabled-address-family " afam +(For +.B ADD +and +.BR PORT .) +The address family +.I afam +is supported, but was disabled using command-line arguments. +.SP .BI "invalid-port " number (For .BR ADD .) @@ -1010,6 +1132,17 @@ There is already a peer named The attempt to send a ping packet failed, probably due to lack of encryption keys. .SP +.B "provider-failed" +(For +.BR SVCSUBMIT .) +The service provider disconnected without sending back a final reply to +the job. +.SP +.B "provider-overloaded" +(For +.BR SVCSUBMIT .) +The service provider has too many jobs queued up for it already. +.SP .BI "resolve-error " hostname (For .BR ADD .) @@ -1048,6 +1181,13 @@ is available, which does not meet the stated requirements. .I tag is already the tag of an outstanding job. .SP +.BI "unknown-address-family " afam +(For +.BR PORT .) +The address family +.I afam +is unrecognized. +.SP .BI "unknown-command " token The command .I token @@ -1082,7 +1222,7 @@ The port name .I port couldn't be found in .BR /etc/services . -.TP +.SP .BI "unknown-service " service (For .BR SVCENSURE , @@ -1093,7 +1233,7 @@ and The token .I service is not recognized as the name of a client-provided service. -.TP +.SP .BI "unknown-tag " tag (For .BR BGCANCEL .) @@ -1101,6 +1241,13 @@ The given .I tag is not the tag for any outstanding background job. It may have just finished. +.SP +.BI "unknown-tunnel " tun +(For +.BR ADD .) +The given +.I tun +is not the name of any known tunnel driver. . .\"-------------------------------------------------------------------------- .SH "NOTIFICATIONS" @@ -1130,6 +1277,12 @@ The peer .I peer has been killed. .SP +.BI "KNOCK " peer " " address +The currently unknown +.I peer +is attempting to connect from +.IR address . +.SP .BI "KXDONE " peer Key exchange with .I peer @@ -1346,6 +1499,11 @@ A key named .I tag couldn't be found in the keyring. .SP +.BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid +A key with the given +.I keyid +(in hex) was requested but not found. +.SP .BI "KEYMGMT " which "-keyring " file " line " line " " message The contents of the keyring file are invalid. There may well be a bug in the @@ -1367,8 +1525,11 @@ is one of the tokens .BR challenge , .BR reply , .BR switch-rq , -or .BR switch-ok . +.BR token-rq , +.BR token , +or +.BR knock . .SP .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag The algorithms specified in the peer's public key @@ -1483,6 +1644,14 @@ An error occurred trying to read an incoming packet. An error occurred attempting to send a network packet. We lost that one. .SP +.BI "PEER " address\fR... " disabled-address-family" +An attempt was made to send a packet to an address for which support was +switched off by command-line options. +.SP +.BI "PEER " address\fR... " socket-write-error " ecode " " message +An error occurred attempting to send a network packet. We lost that +one. +.SP .BI "PEER " peer " unexpected-encrypted-ping 0x" id The peer sent an encrypted ping response whose id doesn't match any outstanding ping. Maybe it was delayed for longer than the server was @@ -1500,6 +1669,51 @@ The peer (apparently) sent a transport ping response whose id doesn't match any outstanding ping. Maybe it was delayed for longer than the server was willing to wait, or maybe the peer has gone mad; or maybe there are bad people trying to confuse you. +.SS "PRIVSEP warnings" +These indicate problems with the privilege-separation helper process. +(The server tries to drop its privileges when it starts up, leaving a +privileged helper process behind which will create and hand over tunnel +descriptors on request, but hopefully not do anything else especially +dangerous. Tunnel descriptors are not completely safe, but this is +probably better than nothing.) +.SP +.BI "PRIVSEP child-exited " rc +The helper process exited normally with status +.IR rc . +Status 0 means that it thought the server didn't want it any more; 1 +means that it was invoked incorrectly; 127 means that some system call +failed. +.SP +.BI "PRIVSEP child-killed " sig +The helper process was killed by signal number +.IR sig . +.SP +.BI "PRIVSEP child-died " status +The helper process died in some unexpected way; +.I status is the raw status code returned by +.BR waitpid (2), +because the server didn't understand how to decode it. +.SP +.BI "PRIVSEP helper-died" +A tunnel driver requires a tunnel descriptor from the helper, but the +helper isn't running so this won't work. +.SP +.BI "PRIVSEP helper-read-error " ecode " " message +The server failed to read a response from the helper process. +.SP +.BI "PRIVSEP helper-short-read" +The helper process didn't send back enough data, and has likely crashed. +.SP +.BI "PRIVSEP helper-write-error " ecode " " message +The server failed to send a message to the helper process. +.SP +.BI "PRIVSEP no-fd-from-helper" +The helper process sent back a positive response, but didn't include the +requested tunnel descriptor. +.SP +.BI "PRIVSEP unknown-response-code" +The helper process sent back an incomprehensible reply. It's probably +very confused and may crash. .SS "SERVER warnings" These indicate problems concerning the server process as a whole. .SP @@ -1531,6 +1745,10 @@ option), and encountered end-of-file on standard input. .BI "SERVER select-error " ecode " " message An error occurred in the server's main event loop. This is bad: if it happens too many times, the server will abort. +.SP +.BI "SERVER waitpid-error " ecode " " message +The server was informed that one of its child processes had exited, but +couldn't retrieve the child's status. .SS "SYMM warnings" These are concerned with the symmetric encryption and decryption process.