.\" 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"
.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
.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
.RB [ \-priv
.IR tag ]
.RB [ \-mobile ]
+.RB [ \-ephemeral ]
.RB [ \-tunnel
.IR driver ]
.I address
.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
.\"-opts
.RE
.SP
+.BI "sabotage " peer
+Sabotage the
+.I peer
+so that
+.B connect
+thinks that it can't respond to pings. This will usually provoke a
+reconnection attempt. Use
+.B kick
+instead unless you're trying to test
+.BR connect .
+.SP
.BI "userpeer " user
Output a single
.B INFO
.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
.B connect
service will take further action.
.SP
-.B "USER connect reconnecting " peer
+.BI "USER connect reconnecting " peer
The dynamically connected
.I peer
seems to be unresponsive. The