3 .\" Manual for the watch service
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
12 .\" TrIPE is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \"@@@PRE@@@
29 .\"--------------------------------------------------------------------------
30 .TH watch 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 watch \- tripe service handle addition and removal of peers
37 .\"--------------------------------------------------------------------------
53 .\"--------------------------------------------------------------------------
58 service tracks associations with peers and performs various actions at
59 appropriate stages in the assocations' lifecycles.
63 When a peer is added, it arranges to configure the corresponding network
64 interface correctly, and (if necessary) to initiate a dynamic
67 When a peer is removed, it arranges to bring down the network interface.
69 While the peer is known, it
71 it at regular intervals. If the peer fails to respond, it can be
72 removed or reconnected.
74 In addition to the standard options described in
75 .BR tripe-service (7),
76 the following command-line options are recognized.
78 .BI "\-p, \-\-peerdb=" file
81 as the (CDB format) peer database. In the absence of this option, the
84 environment variable is used; if that's not set either, then the default
87 in the current working directory is used instead.
89 .\"--------------------------------------------------------------------------
95 service maintains a list of peers which it has adopted. A peer is
96 .I eligible for adoption
97 if it has a record in the peer database
101 key is assigned the value
109 The service pings adopted peers periodically in order to ensure that
110 they are alive, and takes appropriate action if no replies are received.
114 when it is added to this list, and
117 .SS "Configuring interfaces"
120 service configures network interfaces by invoking an
122 script. The script is invoked as
130 where the elements are as described below.
132 .IR script " and " args
133 The peer's database record is retrieved; the value assigned to the
135 key is split into words (quoting is allowed; see
137 for details). The first word is the
139 subsequent words are gathered to form the
143 The name of the peer.
146 The name of the network interface associated with the peer, as returned
149 administration command (see
150 .BR tripe-admin (5)).
153 The network address of the peer's TrIPE server, in the form output by
156 administration command (see
157 .BR tripe-admin (5)).
160 is therefore a network address family, e.g.,
165 service deconfigures interfaces by invoking an
167 script, in a similar manner. The script is invoked as
173 where the elements are as above, except that
177 are formed by splitting the value associated with the peer record's
181 In both of the above cases, if the relevant key (either
185 is absent, no action is taken.
187 The key/value pairs in the peer's database record and the server's
190 administration command (see
196 scripts as environment variables. The environment variable name
197 corresponding to a key is determined as follows:
199 Convert all letters to upper-case.
200 .hP \*o Convert all sequences of one or more non-alphanumeric characters
203 .hP \*o Prefix the resulting name by
207 depending on whether it came from the peer's database record or the
219 .SS "Dynamic connection"
220 If a peer's database record assigns a value to the
224 service will attempt to establish a connection dynamically with the
225 peer. The value of the
227 key is invoked as a Bourne shell command, i.e.,
232 is executed. The command is expected to contact the remote server and
233 report, on standard output, a challenge string. The
235 service reads this challenge, and submits the command
243 command will issue a command such as
245 .B SVCSUBMIT connect passive
250 is the remote peer's name for this host.
254 requests a list of current peers from the
256 server, and adopts any eligible peers. If the
258 flag was passed on the command line,
259 the newly adopted peers have their interfaces configured and connection
262 Adopted peers are pinged at regular intervals (using the
264 administrative command; see
265 .BR tripe-admin (5)).
266 This process can be configured by assigning values to keys in the peer's
267 database record. Some of these parameters are time intervals,
268 expressed as a nonnegative integer followed optionally by
274 for days, hours, minutes, or seconds, respectively; if no suffix is
275 given, seconds are assumed.
277 The parameters are as follows.
280 A time interval: how often to ping the peer to ensure that it's still
281 alive. The default is 2 minutes.
284 A time interval: how long to wait for a reply before retrying or giving
285 up. The default is 10 seconds.
288 An integer: how many failed attempts to make before deciding that the
289 peer is unreachable and taking action. The default is 5 attempts.
291 The algorithm is as follows. Send up to
293 pings; if a reply is received before the
295 then the peer is alive; wait
297 and check again. If no reply is received within the
301 times. If no attempt succeeds, the peer is declared unreachable. If
304 command (i.e., it connects dynamically) then another connection attempt
305 is made. Otherwise the peer is killed.
307 .\"--------------------------------------------------------------------------
308 .SH "SERVICE COMMAND REFERENCE"
310 .\"* 10 Service commands
311 The commands provided by the service are as follows.
314 For each peer being tracked by the
316 service, write a line
319 (Compatibility note: it's possible that further information will be
320 provided about each peer, in the form of subsequent tokens. Clients
321 should be prepared to ignore such tokens.)
326 is currently added, and its record in the peer database contains a
330 then force a reconnection attempt. See
331 .BR "Dynamic connection" .
333 .\"--------------------------------------------------------------------------
336 .\"* 30 Notification broadcasts (NOTE codes)
337 All notifications issued by
339 begin with the tokens
342 .B "USER watch peerdb-update"
343 The peer database has changed. Other interested clients should reopen
346 .BI "USER watch ping-failed " peer " " error\fR...
351 failed; the server replied
355 .BI "USER watch " process\fR... " stdout " line
360 service unexpectedly wrote
362 to its standard output.
364 .\"--------------------------------------------------------------------------
367 .\"* 40 Warning broadcasts (WARN codes)
368 All warnings issued by
370 begin with the tokens
373 .BI "USER watch ping-ok " peer
374 A reply was received to a
378 though earlier attempts had failed.
380 .BI "USER watch ping-timeout " peer " attempt " i " of " n
381 No reply was received to a
388 have been sent; if a total of
390 consecutive attempts time out, the
392 service will take further action.
394 .B "USER watch reconnecting " peer
395 The dynamically connected
397 seems to be unresponsive. The
399 service will attempt to reconnect.
401 .BI "USER watch " process\fR... " stderr " line
408 to its standard error.
410 .BI "USER watch " process\fR... " exit-nonzero " code
415 service exited with the nonzero status
418 .BI "USER watch " process\fR... " exit-signal S" code
423 service was killed by signal
427 is the numeric value of the fatal signal.
429 .BI "USER watch " process\fR... " exit-unknown " status
434 service exited with an unknown
438 is the raw exit status, as returned by
442 .\"--------------------------------------------------------------------------
443 .SH "CHILD PROCESS IDENTIFIERS"
445 .\"* 50 Child process identifiers
446 Some of the warnings and notifications refer to processes spawned by
448 under various circumstances. The process identifiers are as follows.
451 A child spawned in order to establish a dynamic connection with
455 A child spawned to deconfigure the network interface for
459 A child spawned to configure the network interface for
462 .\"--------------------------------------------------------------------------
467 .\"--------------------------------------------------------------------------
470 .BR tripe-service (7),
475 .\"--------------------------------------------------------------------------
478 Mark Wooding, <mdw@distorted.org.uk>
480 .\"----- That's all, folks --------------------------------------------------