server/keymgmt.c (kh_reopen): Promote the happy path.

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

diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in
index 44af6a5..698e2a6 100644 (file)
--- a/server/tripe-admin.5.in
+++ b/server/tripe-admin.5.in
@@ -275,6 +275,16 @@ is always in numeric dotted-quad form, and the
 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.
 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.

+.TP
+.BI "INET6 " address " \fR[" port \fR]
+An Internet socket, naming an IPv6 address and UDP port.  On output, the
+.I address
+is always in numeric hex-and-colons form, and the
+.I port
+is given as a plain decimal number.  On input, DNS hostnames and
+symbolic port names may be permitted, depending on how
+.B tripe
+was compiled; 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
 .PP
 If, on input, no recognized address family token is found, the following
 tokens are assumed to represent an


@@ -351,6 +361,21 @@ Run the command in the background, using the given
 Don't send an immediate challenge to the peer; instead, wait until it
 sends us something before responding.
 .TP
 Don't send an immediate challenge to the peer; instead, wait until it
 sends us something before responding.
 .TP

+.B "\-ephemeral"
+The association with the peer is not intended to persist indefinitely.
+If a peer marked as ephemeral is killed, or the
+.BR tripe (8)
+daemon is shut down, send a
+.B bye
+packet to the peer so that it forgets about us; if a peer marked as
+ephemeral sends us a
+.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.
+.TP

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


@@ -372,6 +397,26 @@ Use the public key
 to authenticate the peer.  The default is to use the key tagged
 .IR peer .
 .TP
 to authenticate the peer.  The default is to use the key tagged
 .IR peer .
 .TP

+.BI "\-knock \fR[" prefix .\fR] tag
+Send the string
+.RI [ prefix\fB. ] tag
+in
+.B token-rq
+and
+.B knock
+messages to the peer during key-exchange.  The string as a whole should
+name the local machine to the peer, and
+.I tag
+should name its public key.  When such messages are received from a
+currently unknown peer,
+.BR tripe (8)
+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
+key by this point.  This option implies
+.BR \-ephemeral .
+.TP

 .B "\-mobile"
 The peer is a mobile device, and is likely to change address rapidly.
 If a packet arrives from an unknown address, the server's usual response
 .B "\-mobile"
 The peer is a mobile device, and is likely to change address rapidly.
 If a packet arrives from an unknown address, the server's usual response


@@ -380,7 +425,8 @@ 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.
+notification.  This option implies
+.BR \-ephemeral .

 .TP
 .BI "\-priv " tag
 Use the private key
 .TP
 .BI "\-priv " tag
 Use the private key


@@ -490,12 +536,16 @@ tunnel interface.  If
 is the MTU of the path to the peer, then the tunnel MTU should be
 .IP
 .I MTU
 is the MTU of the path to the peer, then the tunnel MTU should be
 .IP
 .I MTU

-\- 29 \-
+\-
+.I header-length
+\- 9 \-

 .I bulk-overhead
 .PP
 .I bulk-overhead
 .PP

-allowing 20 bytes of IP header, 8 bytes of UDP header, a packet type
-octet, and the bulk-crypto transform overhead (which includes the
-sequence number).
+allowing
+.I header-length
+= 20 (IPv4) or 40 (IPv6) bytes of IP header, 8 bytes of UDP header, a
+packet type octet, and the bulk-crypto transform overhead (which
+includes the sequence number).

 .RE
 .SP
 .BI "BGCANCEL " tag
 .RE
 .SP
 .BI "BGCANCEL " tag


@@ -591,6 +641,16 @@ The tunnel driver used for this peer.
 The keepalive interval, in seconds, or zero if no keepalives are to be
 sent.
 .TP
 The keepalive interval, in seconds, or zero if no keepalives are to be
 sent.
 .TP

+.B knock
+If present, the string sent to the peer to set up the association; see
+the
+.B \-knock
+option to
+.BR ADD ,
+and the
+.B KNOCK
+notification.
+.TP

 .B key
 The (short) key tag being used for the peer, as passed to the
 .B ADD
 .B key
 The (short) key tag being used for the peer, as passed to the
 .B ADD


@@ -629,6 +689,14 @@ or
 .B nil
 depending on whether or not (respectively) the peer is expected to
 change its address unpredictably.
 .B nil
 depending on whether or not (respectively) the peer is expected to
 change its address unpredictably.

+.TP
+.B ephemeral
+Either
+.B t
+or
+.B nil
+depending on whether the association with the peer is expected to be
+temporary or persistent (respectively).

 .RE
 .SP
 .BI "PING \fR[" options "\fR] " peer
 .RE
 .SP
 .BI "PING \fR[" options "\fR] " peer


@@ -1019,6 +1087,15 @@ An unknown watch option was requested.
 An error occurred during the attempt to become a daemon, as reported by
 .IR message .
 .SP
 An error occurred during the attempt to become a daemon, as reported by
 .IR message .
 .SP

+.BI "disabled-address-family " afam
+(For
+.B ADD
+and
+.BR PORT .)
+The address family
+.I afam
+is supported, but was disabled using command-line arguments.
+.SP

 .BI "invalid-port " number
 (For
 .BR ADD .)
 .BI "invalid-port " number
 (For
 .BR ADD .)


@@ -1200,6 +1277,12 @@ The peer
 .I peer
 has been killed.
 .SP
 .I peer
 has been killed.
 .SP

+.BI "KNOCK " peer " " address
+The currently unknown
+.I peer
+is attempting to connect from
+.IR address .
+.SP

 .BI "KXDONE " peer
 Key exchange with
 .I peer
 .BI "KXDONE " peer
 Key exchange with
 .I peer


@@ -1416,6 +1499,11 @@ A key named
 .I tag
 couldn't be found in the keyring.
 .SP
 .I tag
 couldn't be found in the keyring.
 .SP

+.BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid
+A key with the given
+.I keyid
+(in hex) was requested but not found.
+.SP

 .BI "KEYMGMT " which "-keyring " file " line " line " " message
 The contents of the keyring file are invalid.  There may well be a bug
 in the
 .BI "KEYMGMT " which "-keyring " file " line " line " " message
 The contents of the keyring file are invalid.  There may well be a bug
 in the


@@ -1437,8 +1525,11 @@ is one of the tokens
 .BR challenge ,
 .BR reply ,
 .BR switch-rq ,
 .BR challenge ,
 .BR reply ,
 .BR switch-rq ,

-or

 .BR switch-ok .
 .BR switch-ok .

+.BR token-rq ,
+.BR token ,
+or
+.BR knock .

 .SP
 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
 The algorithms specified in the peer's public key
 .SP
 .BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
 The algorithms specified in the peer's public key


@@ -1553,6 +1644,14 @@ 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 " 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