X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/d3731285e1e3638e7f4877c78ed9e27e1fd72233..844abf94571ffdd3e113c518947073ff5375d748:/svc/connect.8.in diff --git a/svc/connect.8.in b/svc/connect.8.in index 2cc3c5ce..468a5c6d 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 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 +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 +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 -The protocol for passive connection works as follows. +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,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 +437,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 +477,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 +513,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 +534,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 +605,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 +652,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 +756,6 @@ command reported . .BR tripe-service (7), .BR peers.in (5), -.BR watch (8), .BR tripe (8). . .\"--------------------------------------------------------------------------