server/tests.at: Abstract out the wait-for-knock machinery.

[tripe] / server / tripe-admin.5.in

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index bd2cce8..3e7bd8e 100644 (file)
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -363,18 +363,18 @@ sends us something before responding.
 .TP
 .B "\-ephemeral"
 The association with the peer is not intended to persist indefinitely.
 .TP
 .B "\-ephemeral"
 The association with the peer is not intended to persist indefinitely.

-If a peer marked as ephemeral is killed, or the
+When a peer is killed, or the

 .BR tripe (8)
 .BR tripe (8)

-daemon is shut down, send a
+daemon is shut down, a

 .B bye
 .B bye

-packet to the peer so that it forgets about us; if a peer marked as
-ephemeral sends us a
+packet is to the peer(s).  If a peer marked as ephemeral sends us a

 .B bye
 packet then it is killed (but in this case no further
 .B bye
 .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.
+packet is sent).  A
+.B bye
+packet from a peer which isn't marked as ephemeral leaves the peer alone
+in the hope that the connection can be reestablished.

 .TP
 .BI "\-keepalive " time
 Send a no-op packet if we've not sent a packet to the peer in the last
 .TP
 .BI "\-keepalive " time
 Send a no-op packet if we've not sent a packet to the peer in the last


@@ -414,7 +414,7 @@ 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
 .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
+key by this point.  Prior to version 1.6.0, this option used to imply

 .BR \-ephemeral .
 .TP
 .B "\-mobile"
 .BR \-ephemeral .
 .TP
 .B "\-mobile"


@@ -425,7 +425,7 @@ 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
 and if one succeeds, the server will update its idea of the peer's
 address and emit an
 .B NEWADDR

-notification.  This option implies
+notification.  Prior to version 1.6.0, this option used to imply

 .BR \-ephemeral .
 .TP
 .BI "\-priv " tag
 .BR \-ephemeral .
 .TP
 .BI "\-priv " tag


@@ -571,10 +571,24 @@ responses are the same as for the
 .B PING
 command.
 .SP
 .B PING
 command.
 .SP

-.BI "FORCEKX " peer
+.BI "FORCEKX \fR[" options "\fR] " peer

 Requests the server to begin a new key exchange with
 .I peer
 Requests the server to begin a new key exchange with
 .I peer

-immediately.
+immediately.  The following options are recognized.
+.RS
+.\"+opts
+.TP
+.B "\-quiet"
+Don't actually start a new key exchange; just quietly mark any previous
+key exchange as stale so that a fresh attempt from the peer will
+succeed.  This is was introduced for use during testing, but it's also
+useful when a remote peer has forgotten about us: it would be
+annoying if, once it's learns about us and tries to reinitiate a key
+exchange, we ignore it because we think we've already done one recently;
+on the other hand, forcing a key exchange before the remote peer has
+been reinformed about us is a waste of packets.
+.\"-opts
+.RE

 .SP
 .B "GETCHAL"
 Requests a challenge.  The challenge is returned in an
 .SP
 .B "GETCHAL"
 Requests a challenge.  The challenge is returned in an


@@ -614,9 +628,24 @@ line giving the tag for each outstanding background job.
 .BI "KILL " peer
 Causes the server to forget all about
 .IR peer .
 .BI "KILL " peer
 Causes the server to forget all about
 .IR peer .

-All keys are destroyed, and no more packets are sent.  No notification
-is sent to the peer: if it's important that the peer be notified, you
-must think of a way to do that yourself.
+All keys are destroyed, and no more packets are sent.  A
+.B bye
+message is sent to the peer if it's marked as
+.B "\-ephemeral"
+\(en see the
+.B "ADD"
+command.  The following options are
+recognized.
+.RS
+.\"+opts
+.TP
+.B "\-quiet"
+Suppress any
+.B bye
+message to an ephemeral peer: just quietly forget about it.  This is
+used during testing, and is not expected to be generally useful.
+.\"-opts
+.RE

 .SP
 .B "LIST"
 For each currently-known peer, an
 .SP
 .B "LIST"
 For each currently-known peer, an


@@ -1060,7 +1089,9 @@ string was invalid.
 of arguments was wrong.
 .SP
 .BI "bad-time-spec " token
 of arguments was wrong.
 .SP
 .BI "bad-time-spec " token

-The
+(For commands accepting a
+.I time
+argument.)  The

 .I token
 is not a valid time interval specification.  Acceptable time
 specifications are nonnegative integers followed optionally by
 .I token
 is not a valid time interval specification.  Acceptable time
 specifications are nonnegative integers followed optionally by


@@ -1086,6 +1117,12 @@ An unknown watch option was requested.
 .BR DAEMON .)
 An error occurred during the attempt to become a daemon, as reported by
 .IR message .
 .BR DAEMON .)
 An error occurred during the attempt to become a daemon, as reported by
 .IR message .

+See
+.B WARNINGS
+below for the meanings of
+.I ecode
+and
+.IR message .

 .SP
 .BI "disabled-address-family " afam
 (For
 .SP
 .BI "disabled-address-family " afam
 (For


@@ -1129,6 +1166,8 @@ There is already a peer named
 .IR peer .
 .SP
 .B "ping-send-failed"
 .IR peer .
 .SP
 .B "ping-send-failed"

+(For
+.BR EPING .)

 The attempt to send a ping packet failed, probably due to lack of
 encryption keys.
 .SP
 The attempt to send a ping packet failed, probably due to lack of
 encryption keys.
 .SP


@@ -1439,7 +1478,7 @@ command or in greeting packets.
 .SP
 .B "CHAL impossible-challenge"
 The server hasn't issued any challenges yet.  Quite how anyone else
 .SP
 .B "CHAL impossible-challenge"
 The server hasn't issued any challenges yet.  Quite how anyone else

-thought he could make one up is hard to imagine.
+thought they could make one up is hard to imagine.

 .SP
 .B "CHAL incorrect-tag"
 Challenge received contained the wrong authentication data.  It might be
 .SP
 .B "CHAL incorrect-tag"
 Challenge received contained the wrong authentication data.  It might be


@@ -1502,8 +1541,9 @@ implementation of HMAC for the selected hash function
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
 The key specifies the use of an unknown bulk-crypto transform
 .IR bulk .
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
 The key specifies the use of an unknown bulk-crypto transform
 .IR bulk .

-Maybe the key was generated wrongly, or maybe the version of Catacomb
-installed is too old.
+Maybe the key was generated wrongly, or maybe the version of
+.BR tripe (8)
+is too old.

 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
 The key specifies the use of an unknown symmetric encryption algorithm
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-cipher " cipher
 The key specifies the use of an unknown symmetric encryption algorithm


@@ -1540,7 +1580,9 @@ version of Catacomb installed is too old.
 The key specifies the use of an unknown serialization format
 .I ser
 for hashing group elements.  Maybe the key was generated wrongly, or
 The key specifies the use of an unknown serialization format
 .I ser
 for hashing group elements.  Maybe the key was generated wrongly, or

-maybe the version of Catacomb installed is too old.
+maybe the version of
+.BR tripe (8)
+is too old.

 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
 The key specifies the use of an authenticated encryption scheme
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
 The key specifies the use of an authenticated encryption scheme


@@ -1562,10 +1604,9 @@ use the
 .B naclbox
 bulk transform rather than
 .B aead
 .B naclbox
 bulk transform rather than
 .B aead

-for these
-(or switch to the IETF
+for these, or switch to one of the IETF

 .IB cipher -poly1305
 .IB cipher -poly1305

-schemes instead).
+schemes instead.

 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small"
 The key specifies the use of an authenticated encryption scheme
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-small"
 The key specifies the use of an authenticated encryption scheme