X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/d3731285e1e3638e7f4877c78ed9e27e1fd72233..1ff5474edcbc2286e28c018739a8df02db14a1a5:/svc/connect.8.in

diff --git a/svc/connect.8.in b/svc/connect.8.in
index 2cc3c5ce..7021c6b6 100644
--- a/svc/connect.8.in
+++ b/svc/connect.8.in
@@ -27,12 +27,12 @@
 .so ../defs.man.in \"@@@PRE@@@
 .
 .\"--------------------------------------------------------------------------
-.TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.TH connect 8 "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 +55,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 +113,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
-The protocol for passive connection works as follows.
+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
+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 +304,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 +312,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 +340,61 @@ 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 2 minutes.
+.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 +414,8 @@ The service will submit the command
 .IR time ]
 .RB [ \-key
 .IR tag ]
+.RB [ \-priv
+.IR tag ]
 .RB [ \-mobile ]
 .RB [ \-tunnel
 .IR driver ]
@@ -212,6 +454,15 @@ 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
@@ -239,6 +490,16 @@ 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
 .IR peer .
@@ -250,8 +511,18 @@ For each key/value pair, a line
 .PP
 is output.  The key/value pairs are output in an arbitrary order.
 .RE
-.TP
-.B "list"
+.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
@@ -311,49 +582,35 @@ line identifying the peer corresponding to the
 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
-.B passive
-and
-.BR userinfo .)
-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"
@@ -372,6 +629,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"
@@ -383,7 +733,6 @@ command reported
 .
 .BR tripe-service (7),
 .BR peers.in (5),
-.BR watch (8),
 .BR tripe (8).
 .
 .\"--------------------------------------------------------------------------