chiark / gitweb /
Merge branch 'mdw/backoff'
[tripe] / svc / watch.8.in
1 .\" -*-nroff-*-
2 .\".
3 .\" Manual for the watch service
4 .\"
5 .\" (c) 2008 Straylight/Edgeware
6 .\"
7 .
8 .\"----- Licensing notice ---------------------------------------------------
9 .\"
10 .\" This file is part of Trivial IP Encryption (TrIPE).
11 .\"
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.
16 .\"
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.
21 .\"
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.
25 .
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \"@@@PRE@@@
28 .
29 .\"--------------------------------------------------------------------------
30 .TH watch 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 watch \- tripe service handle addition and removal of peers
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "SYNOPSIS"
39 .
40 .B watch
41 .RB [ \-a
42 .IR socket ]
43 .RB [ \-d
44 .IR dir ]
45 .RB [ \-p
46 .IR file ]
47 .br
48 \&      \c
49 .RB [ \-\-daemon ]
50 .RB [ \-\-debug ]
51 .RB [ \-\-startup ]
52 .
53 .\"--------------------------------------------------------------------------
54 .SH "DESCRIPTION"
55 .
56 The
57 .B watch
58 service tracks associations with peers and performs various actions at
59 appropriate stages in the assocations' lifecycles.
60 .PP
61 For example:
62 .hP \*o
63 When a peer is added, it arranges to configure the corresponding network
64 interface correctly, and (if necessary) to initiate a dynamic
65 connection.
66 .hP \*o
67 When a peer is removed, it arranges to bring down the network interface.
68 .hP \*o
69 While the peer is known, it
70 .BR PING s
71 it at regular intervals.  If the peer fails to respond, it can be
72 removed or reconnected.
73 .SS "Command line"
74 In addition to the standard options described in
75 .BR tripe-service (7),
76 the following command-line options are recognized.
77 .TP
78 .BI "\-p, \-\-peerdb=" file
79 Use
80 .I file
81 as the (CDB format) peer database.  In the absence of this option, the
82 file named by the
83 .B TRIPEPEERDB
84 environment variable is used; if that's not set either, then the default
85 default of
86 .B peers.cdb
87 in the current working directory is used instead.
88 .
89 .\"--------------------------------------------------------------------------
90 .SH "BEHAVIOUR"
91 .
92 .SS "Adoption"
93 The
94 .B watch
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
98 .BR peers.cdb (5)
99 in which the
100 .B watch
101 key is assigned the value
102 .BR t ,
103 .BR true ,
104 .BR y ,
105 .BR yes ,
106 or
107 .BR on .
108 .PP
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.
111 .PP
112 A peer is said to be
113 .I adopted
114 when it is added to this list, and
115 .I disowned
116 when it removed.
117 .SS "Configuring interfaces"
118 The
119 .B watch
120 service configures network interfaces by invoking an
121 .B ifup
122 script.  The script is invoked as
123 .IP
124 .I script
125 .IR args ...
126 .I peer
127 .I ifname
128 .IR addr ...
129 .PP
130 where the elements are as described below.
131 .TP
132 .IR script " and " args
133 The peer's database record is retrieved; the value assigned to the
134 .B ifup
135 key is split into words (quoting is allowed; see
136 .BR tripe-admin (5)
137 for details).  The first word is the
138 .IR script ;
139 subsequent words are gathered to form the
140 .IR args .
141 .TP
142 .I peer
143 The name of the peer.
144 .TP
145 .I ifname
146 The name of the network interface associated with the peer, as returned
147 by the
148 .B IFNAME
149 administration command (see
150 .BR tripe-admin (5)).
151 .TP
152 .I addr
153 The network address of the peer's TrIPE server, in the form output by
154 the
155 .B ADDR
156 administration command (see
157 .BR tripe-admin (5)).
158 The first word of
159 .I addr
160 is therefore a network address family, e.g.,
161 .BR INET .
162 .PP
163 The
164 .B watch
165 service deconfigures interfaces by invoking an
166 .B ifdown
167 script, in a similar manner.  The script is invoked as
168 .IP
169 .I script
170 .IR args ...
171 .I peer
172 .PP
173 where the elements are as above, except that
174 .I script
175 and
176 .I args
177 are formed by splitting the value associated with the peer record's
178 .B ifdown
179 key.
180 .PP
181 In both of the above cases, if the relevant key (either
182 .B ifup
183 or
184 .BR ifdown )
185 is absent, no action is taken.
186 .PP
187 The key/value pairs in the peer's database record and the server's
188 response to the
189 .B ALGS
190 administration command (see
191 .BR tripe-admin (5))
192 are passed to the
193 .B ifup
194 and
195 .B ifdown
196 scripts as environment variables.  The environment variable name
197 corresponding to a key is determined as follows:
198 .hP \*o
199 Convert all letters to upper-case.
200 .hP \*o Convert all sequences of one or more non-alphanumeric characters
201 to an underscore
202 .RB ` _ '.
203 .hP \*o Prefix the resulting name by
204 .RB ` P_ '
205 or
206 .RB ` A_ '
207 depending on whether it came from the peer's database record or the
208 .B ALGS
209 output respectively.
210 .PP
211 For example,
212 .B ifname
213 becomes
214 .BR P_IFNAME ;
215 and
216 .B cipher-blksz
217 becomes
218 .BR A_CIPHER_BLKSZ .
219 .SS "Dynamic connection"
220 If a peer's database record assigns a value to the
221 .B connect
222 key, then the
223 .B watch
224 service will attempt to establish a connection dynamically with the
225 peer.  The value of the
226 .B connect
227 key is invoked as a Bourne shell command, i.e.,
228 .IP
229 .B /bin/sh \-c
230 .I connect
231 .PP
232 is executed.  The command is expected to contact the remote server and
233 report, on standard output, a challenge string.  The
234 .B watch
235 service reads this challenge, and submits the command
236 .IP
237 .B GREET
238 .I peer
239 .I challenge
240 .PP
241 Typically, the
242 .B connect
243 command will issue a command such as
244 .IP
245 .B SVCSUBMIT connect passive
246 .I our-name
247 .PP
248 where
249 .I our-name
250 is the remote peer's name for this host.
251 .SS "Operation"
252 On startup,
253 .B watch
254 requests a list of current peers from the
255 .BR tripe (8)
256 server, and adopts any eligible peers.  If the
257 .B \-\-startup
258 flag was passed on the command line, 
259 the newly adopted peers have their interfaces configured and connection
260 attempts are made.
261 .PP
262 Adopted peers are pinged at regular intervals (using the
263 .B PING
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
269 .BR d ,
270 .BR h ,
271 .BR m ,
272 or
273 .B s
274 for days, hours, minutes, or seconds, respectively; if no suffix is
275 given, seconds are assumed.
276 .PP
277 The parameters are as follows.
278 .TP
279 .B every
280 A time interval: how often to ping the peer to ensure that it's still
281 alive.  The default is 2 minutes.
282 .TP
283 .B timeout
284 A time interval: how long to wait for a reply before retrying or giving
285 up.  The default is 10 seconds.
286 .TP
287 .B retries
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.
290 .PP
291 The algorithm is as follows.  Send up to
292 .I retries
293 pings; if a reply is received before the
294 .I timeout
295 then the peer is alive; wait
296 .I every
297 and check again.  If no reply is received within the
298 .IR timeout ,
299 then try again up to
300 .I retries
301 times.  If no attempt succeeds, the peer is declared unreachable.  If
302 the peer has a
303 .B connect
304 command (i.e., it connects dynamically) then another connection attempt
305 is made.  Otherwise the peer is killed.
306 .
307 .\"--------------------------------------------------------------------------
308 .SH "SERVICE COMMAND REFERENCE"
309 .
310 .\"* 10 Service commands
311 The commands provided by the service are as follows.
312 .SP
313 .B adopted
314 For each peer being tracked by the
315 .B watch
316 service, write a line
317 .B INFO
318 .IR name .
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.)
322 .SP
323 .BI "kick " peer
324 If
325 .I peer
326 is currently added, and its record in the peer database contains a
327 .B connect
328 key (see
329 .BR peers.in )
330 then force a reconnection attempt.  See
331 .BR "Dynamic connection" .
332 .
333 .\"--------------------------------------------------------------------------
334 .SH "NOTIFICATIONS"
335 .
336 .\"* 30 Notification broadcasts (NOTE codes)
337 All notifications issued by
338 .B watch
339 begin with the tokens
340 .BR "USER watch" .
341 .SP
342 .B "USER watch peerdb-update"
343 The peer database has changed.  Other interested clients should reopen
344 the database.
345 .SP
346 .BI "USER watch ping-failed " peer " " error\fR...
347 An attempt to
348 .B PING
349 the named
350 .I peer
351 failed; the server replied
352 .B FAIL
353 .IR error ...
354 .SP
355 .BI "USER watch " process\fR... " stdout " line
356 The
357 .I process
358 spawned by the
359 .B watch
360 service unexpectedly wrote
361 .I line
362 to its standard output.
363 .
364 .\"--------------------------------------------------------------------------
365 .SH "WARNINGS"
366 .
367 .\"* 40 Warning broadcasts (WARN codes)
368 All warnings issued by
369 .B watch
370 begin with the tokens
371 .BR "USER watch" .
372 .SP
373 .BI "USER watch ping-ok " peer
374 A reply was received to a
375 .B PING
376 sent to the
377 .IR peer ,
378 though earlier attempts had failed.
379 .SP
380 .BI "USER watch ping-timeout " peer " attempt " i " of " n
381 No reply was received to a
382 .B PING
383 sent to the
384 .IR peer .
385 So far,
386 .I i
387 .BR PING s
388 have been sent; if a total of
389 .I n
390 consecutive attempts time out, the
391 .B watch
392 service will take further action.
393 .SP
394 .B "USER watch reconnecting " peer
395 The dynamically connected
396 .I peer
397 seems to be unresponsive.  The
398 .B watch
399 service will attempt to reconnect.
400 .SP
401 .BI "USER watch " process\fR... " stderr " line
402 The
403 .I process
404 spawned by the
405 .B watch
406 service wrote
407 .I line
408 to its standard error.
409 .SP
410 .BI "USER watch " process\fR... " exit-nonzero " code
411 The
412 .I process
413 spawned by the
414 .B watch
415 service exited with the nonzero status
416 .IR code .
417 .SP
418 .BI "USER watch " process\fR... " exit-signal S" code
419 The
420 .I process
421 spawned by the
422 .B watch
423 service was killed by signal
424 .IR code .
425 Here,
426 .I code
427 is the numeric value of the fatal signal.
428 .SP
429 .BI "USER watch " process\fR... " exit-unknown " status
430 The
431 .I process
432 spawned by the
433 .B watch
434 service exited with an unknown
435 .IR status .
436 Here,
437 .I status
438 is the raw exit status, as returned by
439 .BR waitpid (2),
440 in hexadecimal.
441 .
442 .\"--------------------------------------------------------------------------
443 .SH "CHILD PROCESS IDENTIFIERS"
444 .
445 .\"* 50 Child process identifiers
446 Some of the warnings and notifications refer to processes spawned by
447 .B watch
448 under various circumstances.  The process identifiers are as follows.
449 .SP
450 .BI "connect " peer
451 A child spawned in order to establish a dynamic connection with
452 .IR peer .
453 .SP
454 .BI "ifdown " peer
455 A child spawned to deconfigure the network interface for
456 .IR peer .
457 .SP
458 .BI "ifup " peer
459 A child spawned to configure the network interface for
460 .IR peer .
461 .
462 .\"--------------------------------------------------------------------------
463 .SH "SUMMARY"
464 .
465 .\"= summary
466 .
467 .\"--------------------------------------------------------------------------
468 .SH "SEE ALSO"
469 .
470 .BR tripe-service (7),
471 .BR peers.in (5),
472 .BR connect (8),
473 .BR tripe (8).
474 .
475 .\"--------------------------------------------------------------------------
476 .SH "AUTHOR"
477 .
478 Mark Wooding, <mdw@distorted.org.uk>
479 .
480 .\"----- That's all, folks --------------------------------------------------