+++ /dev/null
-.\" -*-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.
-.PP
-Similarly, if the database record has a
-.B disconnect
-entry, then
-.B watch
-will use this to give the peer explicit notification that its services
-are no longer needed. The value f 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.
-.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 "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"
-.
-.\"= summary
-.
-.\"--------------------------------------------------------------------------
-.SH "SEE ALSO"
-.
-.BR tripe-service (7),
-.BR peers.in (5),
-.BR connect (8),
-.BR tripe (8).
-.
-.\"--------------------------------------------------------------------------
-.SH "AUTHOR"
-.
-Mark Wooding, <mdw@distorted.org.uk>
-.
-.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blobdiff