X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/d64ce4ae05ad8250e08296af18d7d6ddcc5bbc9a..HEAD:/svc/connect.8.in diff --git a/svc/connect.8.in b/svc/connect.8.in index 7021c6b6..1e4e2d25 100644 --- a/svc/connect.8.in +++ b/svc/connect.8.in @@ -9,25 +9,24 @@ .\" .\" This file is part of Trivial IP Encryption (TrIPE). .\" -.\" TrIPE is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 2 of the License, or -.\" (at your option) any later version. +.\" TrIPE is free software: you can redistribute it and/or modify it under +.\" the terms of the GNU General Public License as published by the Free +.\" Software Foundation; either version 3 of the License, or (at your +.\" option) any later version. .\" -.\" TrIPE is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. +.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. .\" .\" You should have received a copy of the GNU General Public License -.\" along with TrIPE; if not, write to the Free Software Foundation, -.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.\" along with TrIPE. If not, see . . .\"-------------------------------------------------------------------------- -.so ../defs.man.in \"@@@PRE@@@ +.so ../common/defs.man \"@@@PRE@@@ . .\"-------------------------------------------------------------------------- -.TH connect 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +.TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" . .\"-------------------------------------------------------------------------- .SH "NAME" @@ -247,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 @@ -295,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 @@ -370,7 +397,30 @@ The parameters are as follows. .TP .B every A time interval: how often to ping the peer to ensure that it's still -alive. The default is 2 minutes. +alive. The default is 30 seconds for active dynamic peers, and 5 +minutes for passive peers. +.IP +The period for dynamic peers should be no longer than +.I timeout +\(mu +.RI ( retries +\- 1). Consider an idle mobile peer which has its IP address changed +just before its passive peer begins pinging. The static peer's pings +will go to the old address until it receives a ping back from the mobile +peer. Therefore, the static peer has to keep pinging until it would +definitely have received an unsolicited ping from the mobile peer, and +therefore be informed of the change of address. And it's no use +learning about the change of address just after sending the last ping to +the old address, so the last retry doesn't count for the purposes of +this calculation. +.IP +Besides, the consequences of failed pinging differ between dynamic and +passive peers. In the former case, a failure provokes a reconnection +attempt, after which (hopefully) things will work again: it's probably a +good thing to check frequently and fail fast. In the latter case, the +dynamic peer will certainly have to notice that it's been abandoned and +arrange to retry, causing a communication failure where maybe there +wasn't really one before. .TP .B timeout A time interval: how long to wait for a reply before retrying or giving @@ -417,6 +467,7 @@ The service will submit the command .RB [ \-priv .IR tag ] .RB [ \-mobile ] +.RB [ \-ephemeral ] .RB [ \-tunnel .IR driver ] .I address @@ -483,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 @@ -501,7 +565,7 @@ provided about each peer, in the form of subsequent tokens. Clients should be prepared to ignore such tokens.) .SP .BI "info " peer -Lists the database record for the named +Lists the database record and additional information about the named .IR peer . For each key/value pair, a line .RS @@ -510,6 +574,67 @@ For each key/value pair, a line .IB key = value .PP is output. The key/value pairs are output in an arbitrary order. +.PP +In addition to the fields of the peer's database record, the following +additional keys are defined. +.TP +.B failures +The number of failed pings in the current or most recent batch, in +decimal. +.TP +.B last-ping +The round-trip time of the most recent ping in milliseconds, in the form +.IB nn.n ms\fR, +or +.B timeout +if the most recent ping timed out, +or +.B \- +if no pings have yet completed. +.TP +.B max-ping +The maximum successful ping time so far in milliseconds, in the form +.IB nn.n ms\fR, +or +.B \- +if no pings have yet succeeded. +.TP +.B mean-ping +The average successful ping time so far in milliseconds, in the form +.IB nn.n ms\fR, +or +.B \- +if no pings have yet succeeded. +.TP +.B min-ping +The minimum successful ping time so far in milliseconds, in the form +.IB nn.n ms\fR, +or +.B \- +if no pings have yet succeeded. +.TP +.B n-lost +The number of pings which have been declared timed out so far, in +decimal. +.TP +.B n-ping +The number of successful pings so far, in decimal. +.TP +.B sd-ping +The standard deviation of ping times so far in milliseconds, in the form +.IB nn.n ms\fR, +or +.B \- +if no pings have yet succeeded. +.TP +.B state +One of the strings: +.B idle +if the peer has responded to a ping recently, and we are waiting for the +.B every +delay before we try again; or +.B check +if we are currently waiting for a ping to return. .RE .SP .BI "kick " peer @@ -574,6 +699,17 @@ seconds are assumed. .\"-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 @@ -630,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