X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/965eb987fc277cdbd200738e8d5c4e85568751d2..HEAD:/svc/connect.8.in

diff --git a/svc/connect.8.in b/svc/connect.8.in
index 91dfd631..1e4e2d25 100644
--- a/svc/connect.8.in
+++ b/svc/connect.8.in
@@ -23,7 +23,7 @@
 .\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
 .
 .\"--------------------------------------------------------------------------
-.so ../defs.man.in \"@@@PRE@@@
+.so ../common/defs.man \"@@@PRE@@@
 .
 .\"--------------------------------------------------------------------------
 .TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
@@ -246,6 +246,33 @@ becomes
 .BR A_CIPHER_BLKSZ .
 .
 .SS "Dynamic connection"
+The
+.B connect
+service supports two kinds of dynamic connection.
+.PP
+The new kind of dynamic association uses the built-in
+.B knock
+protocol.  If the peer's database record assigns a value to the
+.B knock
+key, then the new connection protocol is used: this value is sent to the
+peer during key-exchange, which should (if the peer is properly
+configured) automatically establish the other end of the connection.
+The string should have the form
+.RI [ prefix\fB. ] tag ,
+where the whole string names this host as it is known by the remote
+host, and the
+.I tag
+names this host's public key.  The passive server receives this string,
+verifies that the sender has access to the claimed private key, and
+emits a
+.B KNOCK
+notification which
+.B connect
+notices, causing it to establish the passive peer.  While the internals
+are somewhat complex, configuration is pretty easy.
+.PP
+The older kind of dynamic association is rather more complicated to set
+up, and involves running shell commands, and probably configuring SSH.
 If a peer's database record assigns a value to the
 .B connect
 key, then the
@@ -294,7 +321,8 @@ key is invoked as a Bourne shell command.  This ought to result in a
 .B KILL
 command being issued to the peer's server.
 .PP
-In detail, the protocol for passive connection works as follows.
+In detail, the protocol for old-style dynamic connection works as
+follows.
 .hP 1.
 The active peer
 .BR ADD s
@@ -439,6 +467,7 @@ The service will submit the command
 .RB [ \-priv
 .IR tag ]
 .RB [ \-mobile ]
+.RB [ \-ephemeral ]
 .RB [ \-tunnel
 .IR driver ]
 .I address
@@ -505,6 +534,19 @@ to the
 .B tunnel
 key.
 .hP \*o
+The option
+.B \-ephemeral
+is provided if the peer's database record assigns the
+.B ephemeral
+key one of the values
+.BR t ,
+.BR true ,
+.BR y ,
+.BR yes,
+or
+.BR on ;
+or if it is absent.
+.hP \*o
 The
 .I address
 is the value assigned to the
@@ -724,6 +766,29 @@ command reported
 .B FAIL
 .IR error ...
 .SP
+.BI "USER connect knock-active-peer " name
+The server reported a valid
+.B knock
+message from a peer calling itself
+.I name
+but this is not a passive peer.
+.SP
+.BI "USER connect knock-unknown-peer " name
+The server reported a valid
+.B knock
+message from a peer calling itself
+.I name
+but no such peer is defined in the database.
+.SP
+.BI "USER connect knock-tag-mismatch peer " name " public-key-tag " tag
+The server reported a valid
+.B knock
+message from a peer calling itself
+.I name
+but this name doesn't match that peer's recorded public-key tag, which
+is
+.IR tag .
+.SP
 .BI "USER connect ping-ok " peer
 A reply was received to a
 .B PING