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 f066ae6..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


@@ -1359,6 +1398,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.
 .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
 .SS "ADMIN warnings"
 These indicate a problem with the administration socket interface.
 .SP


@@ -1369,6 +1418,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.
 .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
 .SS "CHAL warnings"
 These indicate errors in challenges, either in the
 .B CHECKCHAL


@@ -1376,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


@@ -1405,9 +1507,6 @@ and the second token is the filename of the keyring.  Frequently a key
 tag may be given next, preceded by the token
 .BR key .
 .SP
 tag may be given next, preceded by the token
 .BR key .
 .SP

-.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
-The private key doesn't record the correct corresponding public key.
-.SP

 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
 A peer's public key doesn't request the same algorithms as our private
 key.
 .BI "KEYMGMT public-keyring " file " key " tag " algorithm-mismatch"
 A peer's public key doesn't request the same algorithms as our private
 key.


@@ -1423,19 +1522,28 @@ The key attributes contain
 .I str
 where a MAC tag length was expected.  The key was generated wrongly.
 .SP
 .I str
 where a MAC tag length was expected.  The key was generated wrongly.
 .SP

+.BI "KEYMGMT private-keyring " file " key " tag " incorrect-public-key"
+The private key doesn't record the correct corresponding public key.
+.SP
+.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
+A system error occurred while opening or reading the keyring file.
+.SP

 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
 The private keyring has been changed, but the new private key can't be
 used because it uses a different group for Diffie\(enHellman key
 exchange.
 .SP
 .BI "KEYMGMT private-keyring " file " key " tag " changed-group"
 The private keyring has been changed, but the new private key can't be
 used because it uses a different group for Diffie\(enHellman key
 exchange.
 .SP

-.BI "KEYMGMT " which "-keyring " file " io-error " ecode " " message
-A system error occurred while opening or reading the keyring file.
+.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
+No message authentication code was given explicitly, and there's no
+implementation of HMAC for the selected hash function
+.IR hash .

 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " unknown-bulk-transform " bulk
 The key specifies the use of an unknown bulk-crypto transform
 .IR bulk .
 .SP
 .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


@@ -1472,12 +1580,54 @@ 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
 .SP

-.BI "KEYMGMT " which "-keyring " file " key " tag " no-hmac-for-hash " hash
-No message authentication code was given explicitly, and there's no
-implementation of HMAC for the selected hash function
-.IR hash .
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "no-aad"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which does not support the processing of additional authenticated data.
+The most prominent examples of such schemes are the
+.IB cipher -naclbox
+collection, where
+.I cipher
+is
+.BR salsa20 ,
+.BR salsa20/12 ,
+.BR salsa20/8 ,
+.BR chacha20 ,
+.BR chacha12 ,
+or
+.BR chacha8 ;
+use the
+.B naclbox
+bulk transform rather than
+.B aead
+for these, or switch to one of the IETF
+.IB cipher -poly1305
+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
+.I cipher
+which doesn't even allow a 5-byte (40-bit) nonce.  Catacomb doesn't
+implement any such limited AE schemes: you must be doing something
+strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonce-too-large"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which doesn't support any nonce size smaller than 64 bytes (512 bits).
+Catacomb doesn't implement any such extravagant AE schemes: you must be
+doing something strange.
+.SP
+.BI "KEYMGMT " which "-keyring " file " key " tag " unsuitable-aead-cipher " cipher "nonempty-ciphertext-for-empty-message"
+The key specifies the use of an authenticated encryption scheme
+.I cipher
+which produces ciphertext output even when given a completely empty
+message.  Catacomb doesn't implement any such unhelpful AE schemes: you
+must be doing something strange.

 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
 The
 .SP
 .BI "KEYMGMT " which "-keyring " file " key " tag " " alg " " name " no-key-size " hashsz
 The


@@ -1644,10 +1794,32 @@ An error occurred trying to read an incoming packet.
 An error occurred attempting to send a network packet.  We lost that
 one.
 .SP
 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 " 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
 .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


@@ -1707,6 +1879,10 @@ The server failed to send a message to the helper process.
 The helper process sent back a positive response, but didn't include the
 requested tunnel descriptor.
 .SP
 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.
 .BI "PRIVSEP unknown-response-code"
 The helper process sent back an incomprehensible reply.  It's probably
 very confused and may crash.


@@ -1733,6 +1909,9 @@ A client of the administration interface issued a
 .B QUIT
 command.
 .SP
 .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
 .BI "SERVER quit foreground-eof"
 The server is running in foreground mode (the
 .B \-F


@@ -1788,6 +1967,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
 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
 .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