X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/7d6ec3708e83ad0f9fe52360512df995cda06007..0ba8de86535cf6025076f5034b76ab753e4dde08:/doc/tripe-admin.5

diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5
index 79874e91..327d1b56 100644
--- a/doc/tripe-admin.5
+++ b/doc/tripe-admin.5
@@ -109,7 +109,22 @@ is the network address (see above for the format) at which the peer can
 be contacted.  The following options are recognised.
 .RS
 .TP
-.BI "-tunnel " tunnel
+.BI "\-keepalive " time
+Send a no-op packet if we've not sent a packet to the peer in the last
+.I time
+interval.  This is useful for persuading port-translating firewalls to
+believe that the `connection' is still active.  The
+.I time
+is expressed as a nonnegative integer followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s
+for days, hours, minutes, or seconds respectively; if no suffix is
+given, seconds are assumed.
+.TP
+.BI "\-tunnel " tunnel
 Use the named tunnel driver, rather than the default.
 .RE
 .TP
@@ -123,6 +138,14 @@ line reporting the IP address and port number stored for
 Causes the server to disassociate itself from its terminal and become a
 background task.  This only works once.  A warning is issued.
 .TP
+.BI "EPING \fR[" options "\fR] " peer
+Sends an encrypted ping to the peer, and expects an encrypted response.
+This checks that the peer is running (and not being impersonated), and
+that it can encrypt and decrypt packets correctly.  Options and
+responses are the same as for the
+.B PING
+command.
+.TP
 .B "HELP"
 Causes the server to emit an
 .B INFO
@@ -157,6 +180,44 @@ Issues a
 .B USER
 notification to all interested administration clients.
 .TP
+.BI "PING \fR[" options "\fR] " peer
+Send a transport-level ping to the peer.  The ping and its response are
+not encrypted or authenticated.  This command, possibly in conjunction
+with tracing, is useful for ensuring that UDP packets are actually
+flowing in both directions.  See also the
+.B EPING
+command.
+.IP
+An
+.B INFO
+line is printed describing the outcome:
+.RS
+.TP
+.BI "ping-ok " millis
+A response was received 
+.I millis
+after the ping was sent.
+.TP
+.BI "ping-timeout"
+No response was received within the time allowed.
+.TP
+.BI "ping-peer-died"
+The peer was killed (probably by another admin connection) before a
+response was received.
+.RE
+.IP
+Options recognized for this command are:
+.RS
+.TP
+.BI "\-timeout " time
+Wait for
+.I time
+seconds before giving up on a response.  The default is 5 seconds.  (The
+time format is the same as for the
+.B "ADD \-keepalive"
+option.)
+.RE
+.TP
 .B "PORT"
 Emits an
 .B INFO
@@ -316,6 +377,18 @@ server is already running as a daemon.
 (For any command.)  The command couldn't be understood: e.g., the number
 of arguments was wrong.
 .TP
+.BI "bad-time-spec " word
+The
+.I word
+is not a valid time interval specification.  Acceptable time
+specifications are nonnegative integers followed optionally by 
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s ,
+for days, hours, minutes, or seconds, respectively.
+.TP
 .BI "bad-trace-option " char
 (For
 .BR TRACE .)
@@ -351,6 +424,10 @@ why.
 There is already a peer named
 .IR peer .
 .TP
+.B "ping-send-failed"
+The attempt to send a ping packet failed, probably due to lack of
+encryption keys.
+.TP
 .BI "resolve-error " hostname
 (For
 .BR ADD .)
@@ -571,13 +648,6 @@ a peer, or
 .RB ` \- '
 if none is relevant.
 .TP
-.BI "PEER \- unexpected-source " address\fR...
-A packet arrived from
-.I address
-(a network address \(en see above), but no peer is known at that
-address.  This may indicate a misconfiguration, or simply be a result of
-one end of a connection being set up before the other.
-.TP
 .BI "PEER " peer " bad-packet no-type"
 An empty packet arrived.  This is very strange.
 .TP
@@ -593,6 +663,15 @@ The message type
 (in hex) isn't understood.  Probably a strange random packet from
 somewhere; could be an unlikely bug.
 .TP
+.BI "PEER " peer " corrupt-encrypted-ping"
+The peer sent a ping response which matches an outstanding ping, but its
+payload is wrong.  There's definitely a bug somewhere.
+.TP
+.BI "PEER " peer " corrupt-transport-ping"
+The peer (apparently) sent a ping response which matches an outstanding
+ping, but its payload is wrong.  Either there's a bug, or the bad guys
+are playing tricks on you.
+.TP
 .BI "PEER " peer " decrypt-failed"
 An encrypted IP packet failed to decrypt.  It may have been mangled in
 transit, or may be a very old packet from an expired previous session
@@ -600,6 +679,14 @@ key.  There is usually a considerable overlap in the validity periods of
 successive session keys, so this shouldn't occur unless the key exchange
 takes ages or fails.
 .TP
+.BI "PEER " peer " malformed-encrypted-ping"
+The peer sent a ping response which is hopelessly invalid.  There's
+definitely a bug somewhere.
+.TP
+.BI "PEER " peer " malformed-transport-ping"
+The peer (apparently) sent a ping response which is hopelessly invalid.
+Either there's a bug, or the bad guys are playing tricks on you.
+.TP
 .BI "PEER " peer " packet-build-failed"
 There wasn't enough space in our buffer to put the packet we wanted to
 send.  Shouldn't happen.
@@ -610,6 +697,24 @@ An error occurred trying to read an incoming packet.
 .BI "PEER " peer " socket-write-error \-\- " message
 An error occurred attempting to send a network packet.  We lost that
 one.
+.TP
+.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
+willing to wait, or maybe the peer has gone mad.
+.TP
+.BI "PEER \- unexpected-source " address\fR...
+A packet arrived from
+.I address
+(a network address \(en see above), but no peer is known at that
+address.  This may indicate a misconfiguration, or simply be a result of
+one end of a connection being set up before the other.
+.TP
+.BI "PEER " peer " unexpected-transport-ping 0x" id
+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 "SERVER warnings"
 These indicate problems concerning the server process as a whole.
 .TP