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. | |
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 -------------------------------------------------- |