X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/48b845698dcf3ec4b9f8b9f1848a157f0245d7cc..965eb987fc277cdbd200738e8d5c4e85568751d2:/svc/connect.8.in?ds=sidebyside

diff --git a/svc/connect.8.in b/svc/connect.8.in
index ddd2636b..91dfd631 100644
--- a/svc/connect.8.in
+++ b/svc/connect.8.in
@@ -9,30 +9,29 @@
 .\"
 .\" 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 <https://www.gnu.org/licenses/>.
 .
 .\"--------------------------------------------------------------------------
 .so ../defs.man.in \"@@@PRE@@@
 .
 .\"--------------------------------------------------------------------------
-.TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
 .
 .\"--------------------------------------------------------------------------
 .SH "NAME"
 .
-connect \- tripe service to make connections to peers
+connect \- tripe service to handle addition and removal of peers
 .
 .\"--------------------------------------------------------------------------
 .SH "SYNOPSIS"
@@ -55,9 +54,24 @@ connect \- tripe service to make connections to peers
 .
 The
 .B connect
-service registers new peers with the
+service tracks associations with peers and performs various actions at
+appropriate stages in the assocations' lifecycles.  It also registers
+new peers with the
 .BR tripe (8)
-server.
+server on demand.
+.PP
+For example:
+.hP \*o
+When a peer is added, it arranges to configure the corresponding network
+interface correctly, and (if necessary) to initiate a dynamic
+connection.
+.hP \*o
+When a peer is removed, it arranges to bring down the network interface.
+.hP \*o
+While the peer is known, it
+.BR PING s
+it at regular intervals.  If the peer fails to respond, it can be
+removed or reconnected.
 .PP
 A peer may participate
 .I actively
@@ -98,11 +112,189 @@ environment variable is used; if that's not set either, then the default
 default of
 .B peers.cdb
 in the current working directory is used instead.
-.SS "Dynamic connection protocol"
-Dynamic connections are used when the peer's address or port are
-unknown, e.g., when it is hidden behind a NAT firewall.
+.
+.\"--------------------------------------------------------------------------
+.SH "BEHAVIOUR"
+.
+.SS "Adoption"
+The
+.B connect
+service maintains a list of peers which it has adopted.  A peer is
+.I eligible for adoption
+if it has a record in the peer database
+.BR peers.cdb (5)
+in which the
+.B watch
+key is assigned the value
+.BR t ,
+.BR true ,
+.BR y ,
+.BR yes ,
+or
+.BR on .
+.PP
+The service pings adopted peers periodically in order to ensure that
+they are alive, and takes appropriate action if no replies are received.
+.PP
+A peer is said to be
+.I adopted
+when it is added to this list, and
+.I disowned
+when it removed.
+.
+.SS "Configuring interfaces"
+The
+.B connect
+service configures network interfaces by invoking an
+.B ifup
+script.  The script is invoked as
+.IP
+.I script
+.IR args ...
+.I peer
+.I ifname
+.IR addr ...
+.PP
+where the elements are as described below.
+.TP
+.IR script " and " args
+The peer's database record is retrieved; the value assigned to the
+.B ifup
+key is split into words (quoting is allowed; see
+.BR tripe-admin (5)
+for details).  The first word is the
+.IR script ;
+subsequent words are gathered to form the
+.IR args .
+.TP
+.I peer
+The name of the peer.
+.TP
+.I ifname
+The name of the network interface associated with the peer, as returned
+by the
+.B IFNAME
+administration command (see
+.BR tripe-admin (5)).
+.TP
+.I addr
+The network address of the peer's TrIPE server, in the form output by
+the
+.B ADDR
+administration command (see
+.BR tripe-admin (5)).
+The first word of
+.I addr
+is therefore a network address family, e.g.,
+.BR INET .
+.PP
+The
+.B connect
+service deconfigures interfaces by invoking an
+.B ifdown
+script, in a similar manner.  The script is invoked as
+.IP
+.I script
+.IR args ...
+.I peer
 .PP
-The protocol for passive connection works as follows.
+where the elements are as above, except that
+.I script
+and
+.I args
+are formed by splitting the value associated with the peer record's
+.B ifdown
+key.
+.PP
+In both of the above cases, if the relevant key (either
+.B ifup
+or
+.BR ifdown )
+is absent, no action is taken.
+.PP
+The key/value pairs in the peer's database record and the server's
+response to the
+.B ALGS
+administration command (see
+.BR tripe-admin (5))
+are passed to the
+.B ifup
+and
+.B ifdown
+scripts as environment variables.  The environment variable name
+corresponding to a key is determined as follows:
+.hP \*o
+Convert all letters to upper-case.
+.hP \*o Convert all sequences of one or more non-alphanumeric characters
+to an underscore
+.RB ` _ '.
+.hP \*o Prefix the resulting name by
+.RB ` P_ '
+or
+.RB ` A_ '
+depending on whether it came from the peer's database record or the
+.B ALGS
+output respectively.
+.PP
+For example,
+.B ifname
+becomes
+.BR P_IFNAME ;
+and
+.B cipher-blksz
+becomes
+.BR A_CIPHER_BLKSZ .
+.
+.SS "Dynamic connection"
+If a peer's database record assigns a value to the
+.B connect
+key, then the
+.B connect
+service will attempt to establish a connection dynamically with the
+peer.  The value of the
+.B connect
+key is invoked as a Bourne shell command, i.e.,
+.IP
+.B /bin/sh \-c
+.I connect
+.PP
+is executed.  The command is expected to contact the remote server and
+report, on standard output, a challenge string, typically by issuing
+a
+.B passive
+command to the instance of the
+.B connect
+service running on the peer.  The
+.B connect
+service reads this challenge, and submits the command
+.IP
+.B GREET
+.I peer
+.I challenge
+.PP
+Typically, the
+.B connect
+command will issue a command such as
+.IP
+.B SVCSUBMIT connect passive
+.I our-name
+.PP
+where
+.I our-name
+is the remote peer's name for this host.
+.PP
+Similarly, if the database record has a
+.B disconnect
+entry, then
+.B connect
+will use this to give the peer explicit notification that its services
+are no longer needed.  The value of the
+.B disconnect
+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.
 .hP 1.
 The active peer
 .BR ADD s
@@ -111,7 +303,7 @@ its partner, typically using the
 option to suppress the key-exchange message which the server usually
 sends immediately, since otherwise the passive peer will warn about it.
 .hP 2.
-The active peer somehow issues the command
+The active peer issues the command
 .RS
 .IP
 .B SVCSUBMIT connect passive
@@ -119,10 +311,10 @@ The active peer somehow issues the command
 .PP
 to the passive peer's server.  (Here,
 .I user
-is a name identifying the active peer; see below.)  This may be handled
-by the
-.BR watch (8)
-service.
+is a name identifying the active peer; see below.)  Doing this is the
+responsibility of the
+.B connect
+command.
 .RE
 .hP 3.
 The
@@ -147,14 +339,84 @@ from the initial connection request, and
 .BR ADD s
 the appropriate peer, with the address from the
 .BR GREET ing.
+.
+.SS "Operation"
+On startup,
+.B connect
+requests a list of current peers from the
+.BR tripe (8)
+server, and adopts any eligible peers.  If the
+.B \-\-startup
+flag was passed on the command line, the newly adopted peers have their
+interfaces configured and connection attempts are made.
 .PP
-The
-.BR watch (8)
-service is capable of performing the active-peer part of this protocol,
-sending the correct
-.B GREET
-command once the challenge has been obtained.  The remaining difficulty
-is in collecting the challenge from the passive peer.
+Adopted peers are pinged at regular intervals (using the
+.B PING
+administrative command; see
+.BR tripe-admin (5)).
+This process can be configured by assigning values to keys in the peer's
+database record.  Some of these parameters are time intervals,
+expressed as a nonnegative integer followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.B s
+for days, hours, minutes, or seconds, respectively; if no suffix is
+given, seconds are assumed.
+.PP
+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 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
+up.  The default is 10 seconds.
+.TP
+.B retries
+An integer: how many failed attempts to make before deciding that the
+peer is unreachable and taking action.  The default is 5 attempts.
+.PP
+The algorithm is as follows.  Send up to
+.I retries
+pings; if a reply is received before the
+.I timeout
+then the peer is alive; wait
+.I every
+and check again.  If no reply is received within the
+.IR timeout ,
+then try again up to
+.I retries
+times.  If no attempt succeeds, the peer is declared unreachable.  If
+the peer has a
+.B connect
+command (i.e., it connects dynamically) then another connection attempt
+is made.  Otherwise the peer is killed.
 .
 .\"--------------------------------------------------------------------------
 .SH "SERVICE COMMAND REFERENCE"
@@ -174,6 +436,9 @@ The service will submit the command
 .IR time ]
 .RB [ \-key
 .IR tag ]
+.RB [ \-priv
+.IR tag ]
+.RB [ \-mobile ]
 .RB [ \-tunnel
 .IR driver ]
 .I address
@@ -211,6 +476,27 @@ to the
 key.
 .hP \*o
 The option
+.B \-priv
+.I tag
+is provided if the database record assigns a value
+.I tag
+to the
+.B priv
+key.
+.hP \*o
+The option
+.B \-mobile
+is provided if the peer's database record assigns the
+.B mobile
+key one of the values
+.BR t ,
+.BR true ,
+.BR y ,
+.BR yes,
+or
+.BR on .
+.hP \*o
+The option
 .B \-tunnel
 .I driver
 is provided if the database record assigns a value
@@ -226,8 +512,18 @@ is the value assigned to the
 key in the database record.
 .RE
 .SP
+.B adopted
+For each peer being tracked by the
+.B connect
+service, write a line
+.B INFO
+.IR name .
+(Compatibility note: it's possible that further information will be
+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
@@ -236,9 +532,80 @@ For each key/value pair, a line
 .IB key = value
 .PP
 is output.  The key/value pairs are output in an arbitrary order.
-.RE
+.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 "list"
+.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
+If
+.I peer
+is currently added, and its record in the peer database contains a
+.B connect
+key (see
+.BR peers.in )
+then force a reconnection attempt.  See
+.BR "Dynamic connection" .
+.SP
+.B "list-active"
 Output a list of peers in the database.  For each peer name
 .IR peer ,
 a line
@@ -289,49 +656,55 @@ for days, hours, minutes or seconds respectively; if no suffix is given,
 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
+line identifying the peer corresponding to the
+.I user
+name.
 .
 .\"--------------------------------------------------------------------------
-.SH "ERROR MESSAGES"
+.SH "NOTIFICATIONS"
 .
-.\"* 20 Error messages (FAIL codes)
-The following error codes may be reported.
-.SP
-.B "connect-timeout"
-(For
-.BR passive .)
-No
-.BR GREET ing
-was received within the timeout period (default 30 seconds).
+.\"* 30 Notification broadcasts (NOTE codes)
+All notifications issued by
+.B connect
+begin with the tokens
+.BR "USER connect" .
 .SP
-.BI "malformed-peer " peer " missing-key " key
-The database record for
-.I peer
-has no value for the
-.I key
-but one was expected.
+.B "USER connect peerdb-update"
+The peer database has changed.  Other interested clients should reopen
+the database.
 .SP
-.BI "passive-peer " peer
-(For
-.BR active .)
-An active connection to
+.BI "USER connect ping-failed " peer " " error\fR...
+An attempt to
+.B PING
+the named
 .I peer
-was requested, but the database record indicates that it is passive,
-i.e., its
-.B peer
-key has the value
-.BR PASSIVE .
+failed; the server replied
+.B FAIL
+.IR error ...
 .SP
-.BI "unknown-peer " peer
+.BI "USER connect " process\fR... " stdout " line
 The
-.I peer
-has no record in the database.
-.SP
-.BI "unknown-user " user
-(For
-.BR passive .)
-There is no record of
-.I user
-in the database.
+.I process
+spawned by the
+.B connect
+service unexpectedly wrote
+.I line
+to its standard output.
 .
 .\"--------------------------------------------------------------------------
 .SH "WARNINGS"
@@ -350,6 +723,99 @@ automatically failed: the
 command reported
 .B FAIL
 .IR error ...
+.SP
+.BI "USER connect ping-ok " peer
+A reply was received to a
+.B PING
+sent to the
+.IR peer ,
+though earlier attempts had failed.
+.SP
+.BI "USER connect ping-timeout " peer " attempt " i " of " n
+No reply was received to a
+.B PING
+sent to the
+.IR peer .
+So far,
+.I i
+.BR PING s
+have been sent; if a total of
+.I n
+consecutive attempts time out, the
+.B connect
+service will take further action.
+.SP
+.B "USER connect reconnecting " peer
+The dynamically connected
+.I peer
+seems to be unresponsive.  The
+.B connect
+service will attempt to reconnect.
+.SP
+.BI "USER connect " process\fR... " stderr " line
+The
+.I process
+spawned by the
+.B connect
+service wrote
+.I line
+to its standard error.
+.SP
+.BI "USER connect " process\fR... " exit-nonzero " code
+The
+.I process
+spawned by the
+.B connect
+service exited with the nonzero status
+.IR code .
+.SP
+.BI "USER connect " process\fR... " exit-signal S" code
+The
+.I process
+spawned by the
+.B connect
+service was killed by signal
+.IR code .
+Here,
+.I code
+is the numeric value of the fatal signal.
+.SP
+.BI "USER connect " process\fR... " exit-unknown " status
+The
+.I process
+spawned by the
+.B connect
+service exited with an unknown
+.IR status .
+Here,
+.I status
+is the raw exit status, as returned by
+.BR waitpid (2),
+in hexadecimal.
+.
+.\"--------------------------------------------------------------------------
+.SH "CHILD PROCESS IDENTIFIERS"
+.
+.\"* 50 Child process identifiers
+Some of the warnings and notifications refer to processes spawned by
+.B connect
+under various circumstances.  The process identifiers are as follows.
+.SP
+.BI "connect " peer
+A child spawned in order to establish a dynamic connection with
+.IR peer .
+.SP
+.BI "disconnect " peer
+A child spawned in order to shut down a dynamic connection with
+.IR peer .
+.SP
+.BI "ifdown " peer
+A child spawned to deconfigure the network interface for
+.IR peer .
+.SP
+.BI "ifup " peer
+A child spawned to configure the network interface for
+.IR peer .
 .
 .\"--------------------------------------------------------------------------
 .SH "SUMMARY"
@@ -361,7 +827,6 @@ command reported
 .
 .BR tripe-service (7),
 .BR peers.in (5),
-.BR watch (8),
 .BR tripe (8).
 .
 .\"--------------------------------------------------------------------------