Commit | Line | Data |
---|---|---|
a62f8e8a MW |
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. | |
d3731285 MW |
251 | .PP |
252 | Similarly, if the database record has a | |
253 | .B disconnect | |
254 | entry, then | |
255 | .B watch | |
256 | will use this to give the peer explicit notification that its services | |
257 | are no longer needed. The value f the | |
258 | .B disconnect | |
259 | key is invoked as a Bourne shell command. This ought to result in a | |
260 | .B KILL | |
261 | command being issued to the peer's server. | |
a62f8e8a MW |
262 | .SS "Operation" |
263 | On startup, | |
264 | .B watch | |
265 | requests a list of current peers from the | |
266 | .BR tripe (8) | |
267 | server, and adopts any eligible peers. If the | |
268 | .B \-\-startup | |
269 | flag was passed on the command line, | |
270 | the newly adopted peers have their interfaces configured and connection | |
271 | attempts are made. | |
272 | .PP | |
273 | Adopted peers are pinged at regular intervals (using the | |
274 | .B PING | |
275 | administrative command; see | |
276 | .BR tripe-admin (5)). | |
277 | This process can be configured by assigning values to keys in the peer's | |
278 | database record. Some of these parameters are time intervals, | |
279 | expressed as a nonnegative integer followed optionally by | |
280 | .BR d , | |
281 | .BR h , | |
282 | .BR m , | |
283 | or | |
284 | .B s | |
285 | for days, hours, minutes, or seconds, respectively; if no suffix is | |
286 | given, seconds are assumed. | |
287 | .PP | |
288 | The parameters are as follows. | |
289 | .TP | |
290 | .B every | |
291 | A time interval: how often to ping the peer to ensure that it's still | |
292 | alive. The default is 2 minutes. | |
293 | .TP | |
294 | .B timeout | |
295 | A time interval: how long to wait for a reply before retrying or giving | |
296 | up. The default is 10 seconds. | |
297 | .TP | |
298 | .B retries | |
299 | An integer: how many failed attempts to make before deciding that the | |
300 | peer is unreachable and taking action. The default is 5 attempts. | |
301 | .PP | |
302 | The algorithm is as follows. Send up to | |
303 | .I retries | |
304 | pings; if a reply is received before the | |
305 | .I timeout | |
306 | then the peer is alive; wait | |
307 | .I every | |
308 | and check again. If no reply is received within the | |
309 | .IR timeout , | |
310 | then try again up to | |
311 | .I retries | |
312 | times. If no attempt succeeds, the peer is declared unreachable. If | |
313 | the peer has a | |
314 | .B connect | |
315 | command (i.e., it connects dynamically) then another connection attempt | |
316 | is made. Otherwise the peer is killed. | |
317 | . | |
318 | .\"-------------------------------------------------------------------------- | |
319 | .SH "SERVICE COMMAND REFERENCE" | |
320 | . | |
321 | .\"* 10 Service commands | |
322 | The commands provided by the service are as follows. | |
323 | .SP | |
324 | .B adopted | |
325 | For each peer being tracked by the | |
326 | .B watch | |
327 | service, write a line | |
328 | .B INFO | |
329 | .IR name . | |
330 | (Compatibility note: it's possible that further information will be | |
331 | provided about each peer, in the form of subsequent tokens. Clients | |
332 | should be prepared to ignore such tokens.) | |
333 | .SP | |
334 | .BI "kick " peer | |
335 | If | |
336 | .I peer | |
337 | is currently added, and its record in the peer database contains a | |
338 | .B connect | |
339 | key (see | |
340 | .BR peers.in ) | |
341 | then force a reconnection attempt. See | |
342 | .BR "Dynamic connection" . | |
343 | . | |
344 | .\"-------------------------------------------------------------------------- | |
345 | .SH "NOTIFICATIONS" | |
346 | . | |
347 | .\"* 30 Notification broadcasts (NOTE codes) | |
348 | All notifications issued by | |
349 | .B watch | |
350 | begin with the tokens | |
351 | .BR "USER watch" . | |
352 | .SP | |
353 | .B "USER watch peerdb-update" | |
354 | The peer database has changed. Other interested clients should reopen | |
355 | the database. | |
356 | .SP | |
357 | .BI "USER watch ping-failed " peer " " error\fR... | |
358 | An attempt to | |
359 | .B PING | |
360 | the named | |
361 | .I peer | |
362 | failed; the server replied | |
363 | .B FAIL | |
364 | .IR error ... | |
365 | .SP | |
366 | .BI "USER watch " process\fR... " stdout " line | |
367 | The | |
368 | .I process | |
369 | spawned by the | |
370 | .B watch | |
371 | service unexpectedly wrote | |
372 | .I line | |
373 | to its standard output. | |
374 | . | |
375 | .\"-------------------------------------------------------------------------- | |
376 | .SH "WARNINGS" | |
377 | . | |
378 | .\"* 40 Warning broadcasts (WARN codes) | |
379 | All warnings issued by | |
380 | .B watch | |
381 | begin with the tokens | |
382 | .BR "USER watch" . | |
383 | .SP | |
384 | .BI "USER watch ping-ok " peer | |
385 | A reply was received to a | |
386 | .B PING | |
387 | sent to the | |
388 | .IR peer , | |
389 | though earlier attempts had failed. | |
390 | .SP | |
391 | .BI "USER watch ping-timeout " peer " attempt " i " of " n | |
392 | No reply was received to a | |
393 | .B PING | |
394 | sent to the | |
395 | .IR peer . | |
396 | So far, | |
397 | .I i | |
398 | .BR PING s | |
399 | have been sent; if a total of | |
400 | .I n | |
401 | consecutive attempts time out, the | |
402 | .B watch | |
403 | service will take further action. | |
404 | .SP | |
405 | .B "USER watch reconnecting " peer | |
406 | The dynamically connected | |
407 | .I peer | |
408 | seems to be unresponsive. The | |
409 | .B watch | |
410 | service will attempt to reconnect. | |
411 | .SP | |
412 | .BI "USER watch " process\fR... " stderr " line | |
413 | The | |
414 | .I process | |
415 | spawned by the | |
416 | .B watch | |
417 | service wrote | |
418 | .I line | |
419 | to its standard error. | |
420 | .SP | |
421 | .BI "USER watch " process\fR... " exit-nonzero " code | |
422 | The | |
423 | .I process | |
424 | spawned by the | |
425 | .B watch | |
426 | service exited with the nonzero status | |
427 | .IR code . | |
428 | .SP | |
429 | .BI "USER watch " process\fR... " exit-signal S" code | |
430 | The | |
431 | .I process | |
432 | spawned by the | |
433 | .B watch | |
434 | service was killed by signal | |
435 | .IR code . | |
436 | Here, | |
437 | .I code | |
438 | is the numeric value of the fatal signal. | |
439 | .SP | |
440 | .BI "USER watch " process\fR... " exit-unknown " status | |
441 | The | |
442 | .I process | |
443 | spawned by the | |
444 | .B watch | |
445 | service exited with an unknown | |
446 | .IR status . | |
447 | Here, | |
448 | .I status | |
449 | is the raw exit status, as returned by | |
450 | .BR waitpid (2), | |
451 | in hexadecimal. | |
452 | . | |
453 | .\"-------------------------------------------------------------------------- | |
454 | .SH "CHILD PROCESS IDENTIFIERS" | |
455 | . | |
456 | .\"* 50 Child process identifiers | |
457 | Some of the warnings and notifications refer to processes spawned by | |
458 | .B watch | |
459 | under various circumstances. The process identifiers are as follows. | |
460 | .SP | |
461 | .BI "connect " peer | |
462 | A child spawned in order to establish a dynamic connection with | |
463 | .IR peer . | |
464 | .SP | |
d3731285 MW |
465 | .BI "disconnect " peer |
466 | A child spawned in order to shut down a dynamic connection with | |
467 | .IR peer . | |
468 | .SP | |
a62f8e8a MW |
469 | .BI "ifdown " peer |
470 | A child spawned to deconfigure the network interface for | |
471 | .IR peer . | |
472 | .SP | |
473 | .BI "ifup " peer | |
474 | A child spawned to configure the network interface for | |
475 | .IR peer . | |
476 | . | |
477 | .\"-------------------------------------------------------------------------- | |
478 | .SH "SUMMARY" | |
479 | . | |
480 | .\"= summary | |
481 | . | |
482 | .\"-------------------------------------------------------------------------- | |
483 | .SH "SEE ALSO" | |
484 | . | |
485 | .BR tripe-service (7), | |
486 | .BR peers.in (5), | |
487 | .BR connect (8), | |
488 | .BR tripe (8). | |
489 | . | |
490 | .\"-------------------------------------------------------------------------- | |
491 | .SH "AUTHOR" | |
492 | . | |
493 | Mark Wooding, <mdw@distorted.org.uk> | |
494 | . | |
495 | .\"----- That's all, folks -------------------------------------------------- |