3 .\" Manual for the connect 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 connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 connect \- tripe service to 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. It also registers
66 When a peer is added, it arranges to configure the corresponding network
67 interface correctly, and (if necessary) to initiate a dynamic
70 When a peer is removed, it arranges to bring down the network interface.
72 While the peer is known, it
74 it at regular intervals. If the peer fails to respond, it can be
75 removed or reconnected.
77 A peer may participate
81 in a connection. A peer participating actively (an
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.
87 A server participating passively (a
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.
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.
102 In addition to the standard options described in
103 .BR tripe-service (7),
104 the following command-line options are recognized.
106 .BI "\-p, \-\-peerdb=" file
109 as the (CDB format) peer database. In the absence of this option, the
112 environment variable is used; if that's not set either, then the default
115 in the current working directory is used instead.
117 .\"--------------------------------------------------------------------------
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
129 key is assigned the value
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.
142 when it is added to this list, and
146 .SS "Configuring interfaces"
149 service configures network interfaces by invoking an
151 script. The script is invoked as
159 where the elements are as described below.
161 .IR script " and " args
162 The peer's database record is retrieved; the value assigned to the
164 key is split into words (quoting is allowed; see
166 for details). The first word is the
168 subsequent words are gathered to form the
172 The name of the peer.
175 The name of the network interface associated with the peer, as returned
178 administration command (see
179 .BR tripe-admin (5)).
182 The network address of the peer's TrIPE server, in the form output by
185 administration command (see
186 .BR tripe-admin (5)).
189 is therefore a network address family, e.g.,
194 service deconfigures interfaces by invoking an
196 script, in a similar manner. The script is invoked as
202 where the elements are as above, except that
206 are formed by splitting the value associated with the peer record's
210 In both of the above cases, if the relevant key (either
214 is absent, no action is taken.
216 The key/value pairs in the peer's database record and the server's
219 administration command (see
225 scripts as environment variables. The environment variable name
226 corresponding to a key is determined as follows:
228 Convert all letters to upper-case.
229 .hP \*o Convert all sequences of one or more non-alphanumeric characters
232 .hP \*o Prefix the resulting name by
236 depending on whether it came from the peer's database record or the
249 .SS "Dynamic connection"
250 If a peer's database record assigns a value to the
254 service will attempt to establish a connection dynamically with the
255 peer. The value of the
257 key is invoked as a Bourne shell command, i.e.,
262 is executed. The command is expected to contact the remote server and
263 report, on standard output, a challenge string, typically by issuing
266 command to the instance of the
268 service running on the peer. The
270 service reads this challenge, and submits the command
278 command will issue a command such as
280 .B SVCSUBMIT connect passive
285 is the remote peer's name for this host.
287 Similarly, if the database record has a
291 will use this to give the peer explicit notification that its services
292 are no longer needed. The value of the
294 key is invoked as a Bourne shell command. This ought to result in a
296 command being issued to the peer's server.
298 In detail, the protocol for passive connection works as follows.
302 its partner, typically using the
304 option to suppress the key-exchange message which the server usually
305 sends immediately, since otherwise the passive peer will warn about it.
307 The active peer issues the command
310 .B SVCSUBMIT connect passive
313 to the passive peer's server. (Here,
315 is a name identifying the active peer; see below.) Doing this is the
316 responsibility of the
323 service on the passive peer responds with a
325 \(en a short Base64-encoded string. Somehow this challenge is sent back
326 to the passive peer without being intercepted.
328 The active peer sends a
330 containing the challenge to its passive partner. The passive server
331 announces the arrival of this message, and the originating address and
336 service running on the passive host receives the notification, matches
339 from the initial connection request, and
341 the appropriate peer, with the address from the
347 requests a list of current peers from the
349 server, and adopts any eligible peers. If the
351 flag was passed on the command line, the newly adopted peers have their
352 interfaces configured and connection attempts are made.
354 Adopted peers are pinged at regular intervals (using the
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
366 for days, hours, minutes, or seconds, respectively; if no suffix is
367 given, seconds are assumed.
369 The parameters are as follows.
372 A time interval: how often to ping the peer to ensure that it's still
373 alive. The default is 30 seconds for active dynamic peers, and 5
374 minutes for passive peers.
376 The period for dynamic peers should be no longer than
380 \- 1). Consider an idle mobile peer which has its IP address changed
381 just before its passive peer begins pinging. The static peer's pings
382 will go to the old address until it receives a ping back from the mobile
383 peer. Therefore, the static peer has to keep pinging until it would
384 definitely have received an unsolicited ping from the mobile peer, and
385 therefore be informed of the change of address. And it's no use
386 learning about the change of address just after sending the last ping to
387 the old address, so the last retry doesn't count for the purposes of
390 Besides, the consequences of failed pinging differ between dynamic and
391 passive peers. In the former case, a failure provokes a reconnection
392 attempt, after which (hopefully) things will work again: it's probably a
393 good thing to check frequently and fail fast. In the latter case, the
394 dynamic peer will certainly have to notice that it's been abandoned and
395 arrange to retry, causing a communication failure where maybe there
396 wasn't really one before.
399 A time interval: how long to wait for a reply before retrying or giving
400 up. The default is 10 seconds.
403 An integer: how many failed attempts to make before deciding that the
404 peer is unreachable and taking action. The default is 5 attempts.
406 The algorithm is as follows. Send up to
408 pings; if a reply is received before the
410 then the peer is alive; wait
412 and check again. If no reply is received within the
416 times. If no attempt succeeds, the peer is declared unreachable. If
419 command (i.e., it connects dynamically) then another connection attempt
420 is made. Otherwise the peer is killed.
422 .\"--------------------------------------------------------------------------
423 .SH "SERVICE COMMAND REFERENCE"
425 .\"* 10 Service commands
426 The commands provided by the service are as follows.
429 Make an active connection to the named
431 The service will submit the command
451 is provided if the peer's database record assigns the
453 key one of the values
464 is provided if the database record assigns a value
473 is provided if the database record assigns a value
482 is provided if the database record assigns a value
490 is provided if the peer's database record assigns the
492 key one of the values
503 is provided if the database record assigns a value
511 is the value assigned to the
513 key in the database record.
517 For each peer being tracked by the
519 service, write a line
522 (Compatibility note: it's possible that further information will be
523 provided about each peer, in the form of subsequent tokens. Clients
524 should be prepared to ignore such tokens.)
527 Lists the database record for the named
529 For each key/value pair, a line
535 is output. The key/value pairs are output in an arbitrary order.
541 is currently added, and its record in the peer database contains a
545 then force a reconnection attempt. See
546 .BR "Dynamic connection" .
549 Output a list of peers in the database. For each peer name
560 .BI "passive \fR[" options "\fR]\fP " user
561 If the database contains a user record mapping
567 line is written containing a freshly chosen challenge string. If the
570 message quoting this challenge within 30 seconds, the
572 service will issue an
574 request for the peer, as for the
576 command, except that the origin of the
578 packet is used as the peer's address.
582 The following option is recognized.
584 .BI "\-timeout " time
587 instead of 30 seconds. The
589 is expressed as a non-negative integer followed by
595 for days, hours, minutes or seconds respectively; if no suffix is given,
603 line identifying the peer corresponding to the
607 .\"--------------------------------------------------------------------------
610 .\"* 30 Notification broadcasts (NOTE codes)
611 All notifications issued by
613 begin with the tokens
616 .B "USER connect peerdb-update"
617 The peer database has changed. Other interested clients should reopen
620 .BI "USER connect ping-failed " peer " " error\fR...
625 failed; the server replied
629 .BI "USER connect " process\fR... " stdout " line
634 service unexpectedly wrote
636 to its standard output.
638 .\"--------------------------------------------------------------------------
641 .\"* 40 Warning broadcasts (WARN codes)
642 All warnings issued by
644 begin with the tokens
647 .BI "USER connect auto-add-failed " name " " error\fR...
648 The attempt to add the peer
650 automatically failed: the
656 .BI "USER connect ping-ok " peer
657 A reply was received to a
661 though earlier attempts had failed.
663 .BI "USER connect ping-timeout " peer " attempt " i " of " n
664 No reply was received to a
671 have been sent; if a total of
673 consecutive attempts time out, the
675 service will take further action.
677 .B "USER connect reconnecting " peer
678 The dynamically connected
680 seems to be unresponsive. The
682 service will attempt to reconnect.
684 .BI "USER connect " process\fR... " stderr " line
691 to its standard error.
693 .BI "USER connect " process\fR... " exit-nonzero " code
698 service exited with the nonzero status
701 .BI "USER connect " process\fR... " exit-signal S" code
706 service was killed by signal
710 is the numeric value of the fatal signal.
712 .BI "USER connect " process\fR... " exit-unknown " status
717 service exited with an unknown
721 is the raw exit status, as returned by
725 .\"--------------------------------------------------------------------------
726 .SH "CHILD PROCESS IDENTIFIERS"
728 .\"* 50 Child process identifiers
729 Some of the warnings and notifications refer to processes spawned by
731 under various circumstances. The process identifiers are as follows.
734 A child spawned in order to establish a dynamic connection with
737 .BI "disconnect " peer
738 A child spawned in order to shut down a dynamic connection with
742 A child spawned to deconfigure the network interface for
746 A child spawned to configure the network interface for
749 .\"--------------------------------------------------------------------------
754 .\"--------------------------------------------------------------------------
757 .BR tripe-service (7),
761 .\"--------------------------------------------------------------------------
764 Mark Wooding, <mdw@distorted.org.uk>
766 .\"----- That's all, folks --------------------------------------------------