X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/bd322830c81423f475cfd70ebef88bfebb16cef0..f8950c27dbaa98501a64cc3bdb98657c64641c4e:/server/tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index 5d01226a..44af6a58 100644
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -251,21 +251,40 @@ 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.
 .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
@@ -663,12 +682,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
@@ -710,6 +735,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 ,
@@ -812,13 +844,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"
@@ -1030,6 +1055,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 +1104,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 +1145,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 +1156,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 +1164,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"
@@ -1520,6 +1570,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
@@ -1551,6 +1646,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.