Keepalives and pings.

[tripe] / doc / tripe-admin.5

diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5
index 79874e9..327d1b5 100644 (file)
--- 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
 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
 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
 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
 .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
 .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
 .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
 (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 .)
 .BI "bad-trace-option " char
 (For
 .BR TRACE .)


@@ -351,6 +424,10 @@ why.
 There is already a peer named
 .IR peer .
 .TP
 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 .)
 .BI "resolve-error " hostname
 (For
 .BR ADD .)


@@ -571,13 +648,6 @@ a peer, or
 .RB ` \- '
 if none is relevant.
 .TP
 .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
 .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
 (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
 .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
 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.
 .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.
 .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
 .SS "SERVER warnings"
 These indicate problems concerning the server process as a whole.
 .TP