X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/405fc4dacbe6be6ae706217bf8489d0a872a88cd..9d966eb7af70d029a9b4862efb67b0c90d32688e:/server/tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index af6c97a5..bd0635e5 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
@@ -610,6 +689,14 @@ 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
@@ -663,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
@@ -994,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 .)
@@ -1030,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 .)
@@ -1068,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
@@ -1102,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 ,
@@ -1113,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 .)
@@ -1121,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"
@@ -1150,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
@@ -1226,6 +1359,16 @@ core in its configuration directory.
 .BI "ABORT repeated-select-errors"
 The main event loop is repeatedly failing.  If the server doesn't quit,
 it will probably waste all available CPU doing nothing.
+.SP
+.BI "ABORT hash-size-too-large hash " name " size " sz " limit " max
+An internal inconsistency: the hash function
+.I name
+produces a
+.IR sz -byte
+hash, but the server has been compiled to assume that no hash function
+returns more than
+.I max
+bytes.
 .SS "ADMIN warnings"
 These indicate a problem with the administration socket interface.
 .SP
@@ -1236,6 +1379,59 @@ client.
 .BI "ADMIN client-write-error " ecode " " message
 There was an error sending data to a client.  The connection to the
 client has been closed.
+.SP
+.BI "ADMIN admin-socket " path " already-in-use"
+The server failed to create the Unix-domain socket object in the
+filesystem, because there's already a socket there, and some other
+process is actively listening for incoming connections.
+.SP
+.BI "ADMIN admin-socket " path " bind-failed " ecode " " message
+The server failed to create the Unix-domain socket object in the
+filesystem for an unusual reason.  (The usual reason is
+.BR EADDRINUSE ,
+but this is handled specially.)
+.SP
+.BI "ADMIN admin-socket " path " chmod-failed " ecode " " message
+The server failed to set the correct permissions of the Unix-domain
+socket object.
+.SP
+.BI "ADMIN admin-socket " path " chown-failed " ecode " " message
+The server failed to set the correct ownership of the Unix-domain socket
+object.
+.SP
+.BI "ADMIN admin-socket " path " create-failed " ecode " " message
+The server failed to create its administration socket.  This is usually
+because some system resource is unavailable.
+.SP
+.BI "ADMIN admin-socket " path " listen-failed " ecode " " message
+The server failed to arrange to receive incoming connections on its
+Unix-domain socket.
+.SP
+.BI "ADMIN admin-socket " path " name-too-long"
+The server can't create its administration socket, because the chosen
+pathname
+.I path
+is too long.  There is, for historical reasons, a rather tight limit on
+the length of name permitted for Unix-domain sockets, usually around 108
+bytes.
+.SP
+.BI "ADMIN admin-socket " path " stat-failed " ecode " " message
+The server failed to create the Unix-domain socket object in the
+filesystem, because there's already something there, but the server
+couldn't discover what.
+.SP
+.BI "ADMIN admin-socket " path " too-many-retries"
+The server failed to create the Unix-domain socket object in the
+filesystem.  This error indicates that another process is also
+repeatedly trying to create a Unix-domain socket at the same
+.IR path ,
+and then failing to actually listen for connections on it, but the
+server always loses the applicable race for some reason.  This situation
+merits investigation.
+.SP
+.BI "ADMIN adns-init-failed " ecode " " message
+The server failed to initialize the ADNS asynchronous DNS-resolution
+library.
 .SS "CHAL warnings"
 These indicate errors in challenges, either in the
 .B CHECKCHAL
@@ -1366,6 +1562,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
@@ -1387,8 +1588,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
@@ -1503,6 +1707,32 @@ 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 \- udp-socket " address-family " bind-failed " ecode " " message
+The server failed to associate a UDP socket with a local address.
+.SP
+.BI "PEER \- udp-socket " address-family " create-failed " ecode " " message
+The server failed to create a UDP socket for the
+.IR address-family .
+.SP
+.BI "PEER \- udp-socket " address-family " read-local-address-failed " ecode " " message
+The server failed to discover the local address for one of its own UDP
+sockets.
+.SP
+.BI "PEER \- udp-socket " address-family " set-buffers-failed " ecode " " message
+The server failed to configure appropriate buffer sizes on a UDP socket.
+.SP
+.BI "PEER \- udp-socket INET6 set-v6only-failed " ecode " " message
+The server failed to configure an IPv6 socket not to try to collect IPv4
+traffic too.
+.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
@@ -1520,6 +1750,55 @@ 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 socketpair-create-failed " ecode " " message
+The server couldn't create the socketpair it's supposed to use to
+communicate with the helper process.
+.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
@@ -1543,6 +1822,9 @@ A client of the administration interface issued a
 .B QUIT
 command.
 .SP
+.BI "SERVER daemon-error " ecode " " message
+The server failed to become a daemon during initialization.
+.SP
 .BI "SERVER quit foreground-eof"
 The server is running in foreground mode (the
 .B \-F
@@ -1551,6 +1833,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.
@@ -1594,6 +1880,11 @@ Writing from the tunnel device failed.
 The SLIP driver encountered a escaped byte it wasn't expecting to see.
 The erroneous packet will be ignored.
 .SP
+.BI "TUN \- slip bad-interface-list"
+The interface list, in the
+.B TRIPE_SLIPIF
+environment variable, is malformed.
+.SP
 .BI "TUN " ifname " slip eof"
 The SLIP driver encountered end-of-file on its input descriptor.
 Pending data is discarded, and no attempt is made to read any more data