chiark / gitweb /
mon/tripemon.in: Support the new-style bindings for Gtk and friends.
[tripe] / svc / connect.8.in
1 .\" -*-nroff-*-
2 .\".
3 .\" Manual for the connect 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 connect 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 connect \- tripe service to handle addition and removal of peers
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "SYNOPSIS"
39 .
40 .B connect
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 connect
58 service tracks associations with peers and performs various actions at
59 appropriate stages in the assocations' lifecycles.  It also registers
60 new peers with the
61 .BR tripe (8)
62 server on demand.
63 .PP
64 For example:
65 .hP \*o
66 When a peer is added, it arranges to configure the corresponding network
67 interface correctly, and (if necessary) to initiate a dynamic
68 connection.
69 .hP \*o
70 When a peer is removed, it arranges to bring down the network interface.
71 .hP \*o
72 While the peer is known, it
73 .BR PING s
74 it at regular intervals.  If the peer fails to respond, it can be
75 removed or reconnected.
76 .PP
77 A peer may participate
78 .I actively
79 or
80 .I passively
81 in a connection.  A peer participating actively (an
82 .IR "active peer" )
83 must already know its peer's connection details \(en its server's IP
84 address and port.  Active connection is suitable when the peer is a
85 well-known server with stable details.
86 .PP
87 A server participating passively (a
88 .IR "passive peer" )
89 waits to be contacted by its peer, and discovers the peer's IP address
90 and port as a result of a simple protocol described below.  Passive
91 connection is suitable when the peer's IP address or port can vary over
92 time \(en e.g., if its IP address is assigned dynamically by DHCP or
93 PPP, or if it is hidden behind a NAT firewall.
94 .PP
95 If both peers are active, we say that they establish an
96 .IR "static connection" ;
97 if one is passive, we say that they establish a
98 .IR "dynamic connection" .
99 At least one of the peers must be active; it is not possible to
100 establish a connection if both peers are passive.
101 .SS "Command line"
102 In addition to the standard options described in
103 .BR tripe-service (7),
104 the following command-line options are recognized.
105 .TP
106 .BI "\-p, \-\-peerdb=" file
107 Use
108 .I file
109 as the (CDB format) peer database.  In the absence of this option, the
110 file named by the
111 .B TRIPEPEERDB
112 environment variable is used; if that's not set either, then the default
113 default of
114 .B peers.cdb
115 in the current working directory is used instead.
116 .
117 .\"--------------------------------------------------------------------------
118 .SH "BEHAVIOUR"
119 .
120 .SS "Adoption"
121 The
122 .B connect
123 service maintains a list of peers which it has adopted.  A peer is
124 .I eligible for adoption
125 if it has a record in the peer database
126 .BR peers.cdb (5)
127 in which the
128 .B watch
129 key is assigned the value
130 .BR t ,
131 .BR true ,
132 .BR y ,
133 .BR yes ,
134 or
135 .BR on .
136 .PP
137 The service pings adopted peers periodically in order to ensure that
138 they are alive, and takes appropriate action if no replies are received.
139 .PP
140 A peer is said to be
141 .I adopted
142 when it is added to this list, and
143 .I disowned
144 when it removed.
145 .
146 .SS "Configuring interfaces"
147 The
148 .B connect
149 service configures network interfaces by invoking an
150 .B ifup
151 script.  The script is invoked as
152 .IP
153 .I script
154 .IR args ...
155 .I peer
156 .I ifname
157 .IR addr ...
158 .PP
159 where the elements are as described below.
160 .TP
161 .IR script " and " args
162 The peer's database record is retrieved; the value assigned to the
163 .B ifup
164 key is split into words (quoting is allowed; see
165 .BR tripe-admin (5)
166 for details).  The first word is the
167 .IR script ;
168 subsequent words are gathered to form the
169 .IR args .
170 .TP
171 .I peer
172 The name of the peer.
173 .TP
174 .I ifname
175 The name of the network interface associated with the peer, as returned
176 by the
177 .B IFNAME
178 administration command (see
179 .BR tripe-admin (5)).
180 .TP
181 .I addr
182 The network address of the peer's TrIPE server, in the form output by
183 the
184 .B ADDR
185 administration command (see
186 .BR tripe-admin (5)).
187 The first word of
188 .I addr
189 is therefore a network address family, e.g.,
190 .BR INET .
191 .PP
192 The
193 .B connect
194 service deconfigures interfaces by invoking an
195 .B ifdown
196 script, in a similar manner.  The script is invoked as
197 .IP
198 .I script
199 .IR args ...
200 .I peer
201 .PP
202 where the elements are as above, except that
203 .I script
204 and
205 .I args
206 are formed by splitting the value associated with the peer record's
207 .B ifdown
208 key.
209 .PP
210 In both of the above cases, if the relevant key (either
211 .B ifup
212 or
213 .BR ifdown )
214 is absent, no action is taken.
215 .PP
216 The key/value pairs in the peer's database record and the server's
217 response to the
218 .B ALGS
219 administration command (see
220 .BR tripe-admin (5))
221 are passed to the
222 .B ifup
223 and
224 .B ifdown
225 scripts as environment variables.  The environment variable name
226 corresponding to a key is determined as follows:
227 .hP \*o
228 Convert all letters to upper-case.
229 .hP \*o Convert all sequences of one or more non-alphanumeric characters
230 to an underscore
231 .RB ` _ '.
232 .hP \*o Prefix the resulting name by
233 .RB ` P_ '
234 or
235 .RB ` A_ '
236 depending on whether it came from the peer's database record or the
237 .B ALGS
238 output respectively.
239 .PP
240 For example,
241 .B ifname
242 becomes
243 .BR P_IFNAME ;
244 and
245 .B cipher-blksz
246 becomes
247 .BR A_CIPHER_BLKSZ .
248 .
249 .SS "Dynamic connection"
250 If a peer's database record assigns a value to the
251 .B connect
252 key, then the
253 .B connect
254 service will attempt to establish a connection dynamically with the
255 peer.  The value of the
256 .B connect
257 key is invoked as a Bourne shell command, i.e.,
258 .IP
259 .B /bin/sh \-c
260 .I connect
261 .PP
262 is executed.  The command is expected to contact the remote server and
263 report, on standard output, a challenge string, typically by issuing
264 a
265 .B passive
266 command to the instance of the
267 .B connect
268 service running on the peer.  The
269 .B connect
270 service reads this challenge, and submits the command
271 .IP
272 .B GREET
273 .I peer
274 .I challenge
275 .PP
276 Typically, the
277 .B connect
278 command will issue a command such as
279 .IP
280 .B SVCSUBMIT connect passive
281 .I our-name
282 .PP
283 where
284 .I our-name
285 is the remote peer's name for this host.
286 .PP
287 Similarly, if the database record has a
288 .B disconnect
289 entry, then
290 .B connect
291 will use this to give the peer explicit notification that its services
292 are no longer needed.  The value of the
293 .B disconnect
294 key is invoked as a Bourne shell command.  This ought to result in a
295 .B KILL
296 command being issued to the peer's server.
297 .PP
298 In detail, the protocol for passive connection works as follows.
299 .hP 1.
300 The active peer
301 .BR ADD s
302 its partner, typically using the
303 .B \-cork
304 option to suppress the key-exchange message which the server usually
305 sends immediately, since otherwise the passive peer will warn about it.
306 .hP 2.
307 The active peer issues the command
308 .RS
309 .IP
310 .B SVCSUBMIT connect passive
311 .I user
312 .PP
313 to the passive peer's server.  (Here,
314 .I user
315 is a name identifying the active peer; see below.)  Doing this is the
316 responsibility of the
317 .B connect
318 command.
319 .RE
320 .hP 3.
321 The
322 .B connect
323 service on the passive peer responds with a
324 .I challenge
325 \(en a short Base64-encoded string.  Somehow this challenge is sent back
326 to the passive peer without being intercepted.
327 .hP 4.
328 The active peer sends a
329 .BR GREET ing
330 containing the challenge to its passive partner.  The passive server
331 announces the arrival of this message, and the originating address and
332 port.
333 .hP 5.
334 The
335 .B connect
336 service running on the passive host receives the notification, matches
337 it up with the
338 .I user
339 from the initial connection request, and
340 .BR ADD s
341 the appropriate peer, with the address from the
342 .BR GREET ing.
343 .
344 .SS "Operation"
345 On startup,
346 .B connect
347 requests a list of current peers from the
348 .BR tripe (8)
349 server, and adopts any eligible peers.  If the
350 .B \-\-startup
351 flag was passed on the command line, the newly adopted peers have their
352 interfaces configured and connection attempts are made.
353 .PP
354 Adopted peers are pinged at regular intervals (using the
355 .B PING
356 administrative command; see
357 .BR tripe-admin (5)).
358 This process can be configured by assigning values to keys in the peer's
359 database record.  Some of these parameters are time intervals,
360 expressed as a nonnegative integer followed optionally by
361 .BR d ,
362 .BR h ,
363 .BR m ,
364 or
365 .B s
366 for days, hours, minutes, or seconds, respectively; if no suffix is
367 given, seconds are assumed.
368 .PP
369 The parameters are as follows.
370 .TP
371 .B every
372 A time interval: how often to ping the peer to ensure that it's still
373 alive.  The default is 2 minutes.
374 .TP
375 .B timeout
376 A time interval: how long to wait for a reply before retrying or giving
377 up.  The default is 10 seconds.
378 .TP
379 .B retries
380 An integer: how many failed attempts to make before deciding that the
381 peer is unreachable and taking action.  The default is 5 attempts.
382 .PP
383 The algorithm is as follows.  Send up to
384 .I retries
385 pings; if a reply is received before the
386 .I timeout
387 then the peer is alive; wait
388 .I every
389 and check again.  If no reply is received within the
390 .IR timeout ,
391 then try again up to
392 .I retries
393 times.  If no attempt succeeds, the peer is declared unreachable.  If
394 the peer has a
395 .B connect
396 command (i.e., it connects dynamically) then another connection attempt
397 is made.  Otherwise the peer is killed.
398 .
399 .\"--------------------------------------------------------------------------
400 .SH "SERVICE COMMAND REFERENCE"
401 .
402 .\"* 10 Service commands
403 The commands provided by the service are as follows.
404 .SP
405 .BI "active " peer
406 Make an active connection to the named
407 .IR peer .
408 The service will submit the command
409 .RS
410 .IP
411 .B ADD
412 .RB [ \-cork ]
413 .RB [ \-keepalive
414 .IR time ]
415 .RB [ \-key
416 .IR tag ]
417 .RB [ \-priv
418 .IR tag ]
419 .RB [ \-mobile ]
420 .RB [ \-tunnel
421 .IR driver ]
422 .I address
423 .PP
424 Specifically:
425 .hP \*o
426 The option
427 .B \-cork
428 is provided if the peer's database record assigns the
429 .B cork
430 key one of the values
431 .BR t ,
432 .BR true ,
433 .BR y ,
434 .BR yes,
435 or
436 .BR on .
437 .hP \*o
438 The option
439 .B \-keepalive
440 .I time
441 is provided if the database record assigns a value
442 .I time
443 to the
444 .B keepalive
445 key.
446 .hP \*o
447 The option
448 .B \-key
449 .I tag
450 is provided if the database record assigns a value
451 .I tag
452 to the
453 .B key
454 key.
455 .hP \*o
456 The option
457 .B \-priv
458 .I tag
459 is provided if the database record assigns a value
460 .I tag
461 to the
462 .B priv
463 key.
464 .hP \*o
465 The option
466 .B \-mobile
467 is provided if the peer's database record assigns the
468 .B mobile
469 key one of the values
470 .BR t ,
471 .BR true ,
472 .BR y ,
473 .BR yes,
474 or
475 .BR on .
476 .hP \*o
477 The option
478 .B \-tunnel
479 .I driver
480 is provided if the database record assigns a value
481 .I driver
482 to the
483 .B tunnel
484 key.
485 .hP \*o
486 The
487 .I address
488 is the value assigned to the
489 .B peer
490 key in the database record.
491 .RE
492 .SP
493 .B adopted
494 For each peer being tracked by the
495 .B connect
496 service, write a line
497 .B INFO
498 .IR name .
499 (Compatibility note: it's possible that further information will be
500 provided about each peer, in the form of subsequent tokens.  Clients
501 should be prepared to ignore such tokens.)
502 .SP
503 .BI "info " peer
504 Lists the database record for the named
505 .IR peer .
506 For each key/value pair, a line
507 .RS
508 .IP
509 .B INFO
510 .IB key = value
511 .PP
512 is output.  The key/value pairs are output in an arbitrary order.
513 .RE
514 .SP
515 .BI "kick " peer
516 If
517 .I peer
518 is currently added, and its record in the peer database contains a
519 .B connect
520 key (see
521 .BR peers.in )
522 then force a reconnection attempt.  See
523 .BR "Dynamic connection" .
524 .SP
525 .B "list-active"
526 Output a list of peers in the database.  For each peer name
527 .IR peer ,
528 a line
529 .RS
530 .IP
531 .B INFO
532 .I peer
533 .PP
534 is output.
535 .RE
536 .SP
537 .BI "passive \fR[" options "\fR]\fP " user
538 If the database contains a user record mapping
539 .I user
540 to some
541 .I peer
542 then an
543 .B INFO
544 line is written containing a freshly chosen challenge string.  If the
545 server receives a
546 .BR GREET ing
547 message quoting this challenge within 30 seconds, the
548 .B connect
549 service will issue an
550 .B ADD
551 request for the peer, as for the
552 .B active
553 command, except that the origin of the
554 .BR GREET ing
555 packet is used as the peer's address.
556 .RS
557 .\"+opts
558 .PP
559 The following option is recognized.
560 .TP
561 .BI "\-timeout " time
562 Wait for
563 .I time
564 instead of 30 seconds.  The
565 .I time
566 is expressed as a non-negative integer followed by
567 .BR d ,
568 .BR h ,
569 .BR m ,
570 or
571 .B s
572 for days, hours, minutes or seconds respectively; if no suffix is given,
573 seconds are assumed.
574 .\"-opts
575 .RE
576 .SP
577 .BI "userpeer " user
578 Output a single
579 .B INFO
580 line identifying the peer corresponding to the
581 .I user
582 name.
583 .
584 .\"--------------------------------------------------------------------------
585 .SH "NOTIFICATIONS"
586 .
587 .\"* 30 Notification broadcasts (NOTE codes)
588 All notifications issued by
589 .B connect
590 begin with the tokens
591 .BR "USER connect" .
592 .SP
593 .B "USER connect peerdb-update"
594 The peer database has changed.  Other interested clients should reopen
595 the database.
596 .SP
597 .BI "USER connect ping-failed " peer " " error\fR...
598 An attempt to
599 .B PING
600 the named
601 .I peer
602 failed; the server replied
603 .B FAIL
604 .IR error ...
605 .SP
606 .BI "USER connect " process\fR... " stdout " line
607 The
608 .I process
609 spawned by the
610 .B connect
611 service unexpectedly wrote
612 .I line
613 to its standard output.
614 .
615 .\"--------------------------------------------------------------------------
616 .SH "WARNINGS"
617 .
618 .\"* 40 Warning broadcasts (WARN codes)
619 All warnings issued by
620 .B connect
621 begin with the tokens
622 .BR "USER connect" .
623 .SP
624 .BI "USER connect auto-add-failed " name " " error\fR...
625 The attempt to add the peer
626 .I name
627 automatically failed: the
628 .B ADD
629 command reported
630 .B FAIL
631 .IR error ...
632 .SP
633 .BI "USER connect ping-ok " peer
634 A reply was received to a
635 .B PING
636 sent to the
637 .IR peer ,
638 though earlier attempts had failed.
639 .SP
640 .BI "USER connect ping-timeout " peer " attempt " i " of " n
641 No reply was received to a
642 .B PING
643 sent to the
644 .IR peer .
645 So far,
646 .I i
647 .BR PING s
648 have been sent; if a total of
649 .I n
650 consecutive attempts time out, the
651 .B connect
652 service will take further action.
653 .SP
654 .B "USER connect reconnecting " peer
655 The dynamically connected
656 .I peer
657 seems to be unresponsive.  The
658 .B connect
659 service will attempt to reconnect.
660 .SP
661 .BI "USER connect " process\fR... " stderr " line
662 The
663 .I process
664 spawned by the
665 .B connect
666 service wrote
667 .I line
668 to its standard error.
669 .SP
670 .BI "USER connect " process\fR... " exit-nonzero " code
671 The
672 .I process
673 spawned by the
674 .B connect
675 service exited with the nonzero status
676 .IR code .
677 .SP
678 .BI "USER connect " process\fR... " exit-signal S" code
679 The
680 .I process
681 spawned by the
682 .B connect
683 service was killed by signal
684 .IR code .
685 Here,
686 .I code
687 is the numeric value of the fatal signal.
688 .SP
689 .BI "USER connect " process\fR... " exit-unknown " status
690 The
691 .I process
692 spawned by the
693 .B connect
694 service exited with an unknown
695 .IR status .
696 Here,
697 .I status
698 is the raw exit status, as returned by
699 .BR waitpid (2),
700 in hexadecimal.
701 .
702 .\"--------------------------------------------------------------------------
703 .SH "CHILD PROCESS IDENTIFIERS"
704 .
705 .\"* 50 Child process identifiers
706 Some of the warnings and notifications refer to processes spawned by
707 .B connect
708 under various circumstances.  The process identifiers are as follows.
709 .SP
710 .BI "connect " peer
711 A child spawned in order to establish a dynamic connection with
712 .IR peer .
713 .SP
714 .BI "disconnect " peer
715 A child spawned in order to shut down a dynamic connection with
716 .IR peer .
717 .SP
718 .BI "ifdown " peer
719 A child spawned to deconfigure the network interface for
720 .IR peer .
721 .SP
722 .BI "ifup " peer
723 A child spawned to configure the network interface for
724 .IR peer .
725 .
726 .\"--------------------------------------------------------------------------
727 .SH "SUMMARY"
728 .
729 .\"= summary
730 .
731 .\"--------------------------------------------------------------------------
732 .SH "SEE ALSO"
733 .
734 .BR tripe-service (7),
735 .BR peers.in (5),
736 .BR tripe (8).
737 .
738 .\"--------------------------------------------------------------------------
739 .SH "AUTHOR"
740 .
741 Mark Wooding, <mdw@distorted.org.uk>
742 .
743 .\"----- That's all, folks --------------------------------------------------