Explicit close-down notifications.

[tripe] / svc / watch.8.in

.\" -*-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 --------------------------------------------------