.\" -*-nroff-*- .\". .\" Manual for the watch service .\" .\" (c) 2008 Straylight/Edgeware .\" . .\"----- Licensing notice --------------------------------------------------- .\" .\" 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 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. . .\"-------------------------------------------------------------------------- .so ../defs.man.in \"@@@PRE@@@ . .\"-------------------------------------------------------------------------- .TH watch 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" . .\"-------------------------------------------------------------------------- .SH "NAME" . watch \- tripe service handle addition and removal of peers . .\"-------------------------------------------------------------------------- .SH "SYNOPSIS" . .B watch .RB [ \-a .IR socket ] .RB [ \-d .IR dir ] .RB [ \-p .IR file ] .br \& \c .RB [ \-\-daemon ] .RB [ \-\-debug ] .RB [ \-\-startup ] . .\"-------------------------------------------------------------------------- .SH "DESCRIPTION" . The .B watch service tracks associations with peers and performs various actions at appropriate stages in the assocations' lifecycles. .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. .SS "Command line" In addition to the standard options described in .BR tripe-service (7), the following command-line options are recognized. .TP .BI "\-p, \-\-peerdb=" file Use .I file as the (CDB format) peer database. In the absence of this option, the file named by the .B TRIPEPEERDB 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. . .\"-------------------------------------------------------------------------- .SH "BEHAVIOUR" . .SS "Adoption" The .B watch 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 watch 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 watch 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 watch 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. The .B watch 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. .SS "Operation" On startup, .B watch 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 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" . .\"* 10 Service commands The commands provided by the service are as follows. .SP .B adopted For each peer being tracked by the .B watch 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 "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" . . .\"-------------------------------------------------------------------------- .SH "NOTIFICATIONS" . .\"* 30 Notification broadcasts (NOTE codes) All notifications issued by .B watch begin with the tokens .BR "USER watch" . .SP .B "USER watch peerdb-update" The peer database has changed. Other interested clients should reopen the database. .SP .BI "USER watch ping-failed " peer " " error\fR... An attempt to .B PING the named .I peer failed; the server replied .B FAIL .IR error ... .SP .BI "USER watch " process\fR... " stdout " line The .I process spawned by the .B watch service unexpectedly wrote .I line to its standard output. . .\"-------------------------------------------------------------------------- .SH "WARNINGS" . .\"* 40 Warning broadcasts (WARN codes) All warnings issued by .B watch begin with the tokens .BR "USER watch" . .SP .BI "USER watch ping-ok " peer A reply was received to a .B PING sent to the .IR peer , though earlier attempts had failed. .SP .BI "USER watch 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 watch service will take further action. .SP .B "USER watch reconnecting " peer The dynamically connected .I peer seems to be unresponsive. The .B watch service will attempt to reconnect. .SP .BI "USER watch " process\fR... " stderr " line The .I process spawned by the .B watch service wrote .I line to its standard error. .SP .BI "USER watch " process\fR... " exit-nonzero " code The .I process spawned by the .B watch service exited with the nonzero status .IR code . .SP .BI "USER watch " process\fR... " exit-signal S" code The .I process spawned by the .B watch service was killed by signal .IR code . Here, .I code is the numeric value of the fatal signal. .SP .BI "USER watch " process\fR... " exit-unknown " status The .I process spawned by the .B watch 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 watch 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 "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" . .\"= summary . .\"-------------------------------------------------------------------------- .SH "SEE ALSO" . .BR tripe-service (7), .BR peers.in (5), .BR connect (8), .BR tripe (8). . .\"-------------------------------------------------------------------------- .SH "AUTHOR" . Mark Wooding, . .\"----- That's all, folks --------------------------------------------------