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 it under
13 .\" the terms of the GNU General Public License as published by the Free
14 .\" Software Foundation; either version 3 of the License, or (at your
15 .\" option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \"@@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 connect \- tripe service to handle addition and removal of peers
36 .\"--------------------------------------------------------------------------
52 .\"--------------------------------------------------------------------------
57 service tracks associations with peers and performs various actions at
58 appropriate stages in the assocations' lifecycles. It also registers
65 When a peer is added, it arranges to configure the corresponding network
66 interface correctly, and (if necessary) to initiate a dynamic
69 When a peer is removed, it arranges to bring down the network interface.
71 While the peer is known, it
73 it at regular intervals. If the peer fails to respond, it can be
74 removed or reconnected.
76 A peer may participate
80 in a connection. A peer participating actively (an
82 must already know its peer's connection details \(en its server's IP
83 address and port. Active connection is suitable when the peer is a
84 well-known server with stable details.
86 A server participating passively (a
88 waits to be contacted by its peer, and discovers the peer's IP address
89 and port as a result of a simple protocol described below. Passive
90 connection is suitable when the peer's IP address or port can vary over
91 time \(en e.g., if its IP address is assigned dynamically by DHCP or
92 PPP, or if it is hidden behind a NAT firewall.
94 If both peers are active, we say that they establish an
95 .IR "static connection" ;
96 if one is passive, we say that they establish a
97 .IR "dynamic connection" .
98 At least one of the peers must be active; it is not possible to
99 establish a connection if both peers are passive.
101 In addition to the standard options described in
102 .BR tripe-service (7),
103 the following command-line options are recognized.
105 .BI "\-p, \-\-peerdb=" file
108 as the (CDB format) peer database. In the absence of this option, the
111 environment variable is used; if that's not set either, then the default
114 in the current working directory is used instead.
116 .\"--------------------------------------------------------------------------
122 service maintains a list of peers which it has adopted. A peer is
123 .I eligible for adoption
124 if it has a record in the peer database
128 key is assigned the value
136 The service pings adopted peers periodically in order to ensure that
137 they are alive, and takes appropriate action if no replies are received.
141 when it is added to this list, and
145 .SS "Configuring interfaces"
148 service configures network interfaces by invoking an
150 script. The script is invoked as
158 where the elements are as described below.
160 .IR script " and " args
161 The peer's database record is retrieved; the value assigned to the
163 key is split into words (quoting is allowed; see
165 for details). The first word is the
167 subsequent words are gathered to form the
171 The name of the peer.
174 The name of the network interface associated with the peer, as returned
177 administration command (see
178 .BR tripe-admin (5)).
181 The network address of the peer's TrIPE server, in the form output by
184 administration command (see
185 .BR tripe-admin (5)).
188 is therefore a network address family, e.g.,
193 service deconfigures interfaces by invoking an
195 script, in a similar manner. The script is invoked as
201 where the elements are as above, except that
205 are formed by splitting the value associated with the peer record's
209 In both of the above cases, if the relevant key (either
213 is absent, no action is taken.
215 The key/value pairs in the peer's database record and the server's
218 administration command (see
224 scripts as environment variables. The environment variable name
225 corresponding to a key is determined as follows:
227 Convert all letters to upper-case.
228 .hP \*o Convert all sequences of one or more non-alphanumeric characters
231 .hP \*o Prefix the resulting name by
235 depending on whether it came from the peer's database record or the
248 .SS "Dynamic connection"
249 If a peer's database record assigns a value to the
253 service will attempt to establish a connection dynamically with the
254 peer. The value of the
256 key is invoked as a Bourne shell command, i.e.,
261 is executed. The command is expected to contact the remote server and
262 report, on standard output, a challenge string, typically by issuing
265 command to the instance of the
267 service running on the peer. The
269 service reads this challenge, and submits the command
277 command will issue a command such as
279 .B SVCSUBMIT connect passive
284 is the remote peer's name for this host.
286 Similarly, if the database record has a
290 will use this to give the peer explicit notification that its services
291 are no longer needed. The value of the
293 key is invoked as a Bourne shell command. This ought to result in a
295 command being issued to the peer's server.
297 In detail, the protocol for passive connection works as follows.
301 its partner, typically using the
303 option to suppress the key-exchange message which the server usually
304 sends immediately, since otherwise the passive peer will warn about it.
306 The active peer issues the command
309 .B SVCSUBMIT connect passive
312 to the passive peer's server. (Here,
314 is a name identifying the active peer; see below.) Doing this is the
315 responsibility of the
322 service on the passive peer responds with a
324 \(en a short Base64-encoded string. Somehow this challenge is sent back
325 to the passive peer without being intercepted.
327 The active peer sends a
329 containing the challenge to its passive partner. The passive server
330 announces the arrival of this message, and the originating address and
335 service running on the passive host receives the notification, matches
338 from the initial connection request, and
340 the appropriate peer, with the address from the
346 requests a list of current peers from the
348 server, and adopts any eligible peers. If the
350 flag was passed on the command line, the newly adopted peers have their
351 interfaces configured and connection attempts are made.
353 Adopted peers are pinged at regular intervals (using the
355 administrative command; see
356 .BR tripe-admin (5)).
357 This process can be configured by assigning values to keys in the peer's
358 database record. Some of these parameters are time intervals,
359 expressed as a nonnegative integer followed optionally by
365 for days, hours, minutes, or seconds, respectively; if no suffix is
366 given, seconds are assumed.
368 The parameters are as follows.
371 A time interval: how often to ping the peer to ensure that it's still
372 alive. The default is 30 seconds for active dynamic peers, and 5
373 minutes for passive peers.
375 The period for dynamic peers should be no longer than
379 \- 1). Consider an idle mobile peer which has its IP address changed
380 just before its passive peer begins pinging. The static peer's pings
381 will go to the old address until it receives a ping back from the mobile
382 peer. Therefore, the static peer has to keep pinging until it would
383 definitely have received an unsolicited ping from the mobile peer, and
384 therefore be informed of the change of address. And it's no use
385 learning about the change of address just after sending the last ping to
386 the old address, so the last retry doesn't count for the purposes of
389 Besides, the consequences of failed pinging differ between dynamic and
390 passive peers. In the former case, a failure provokes a reconnection
391 attempt, after which (hopefully) things will work again: it's probably a
392 good thing to check frequently and fail fast. In the latter case, the
393 dynamic peer will certainly have to notice that it's been abandoned and
394 arrange to retry, causing a communication failure where maybe there
395 wasn't really one before.
398 A time interval: how long to wait for a reply before retrying or giving
399 up. The default is 10 seconds.
402 An integer: how many failed attempts to make before deciding that the
403 peer is unreachable and taking action. The default is 5 attempts.
405 The algorithm is as follows. Send up to
407 pings; if a reply is received before the
409 then the peer is alive; wait
411 and check again. If no reply is received within the
415 times. If no attempt succeeds, the peer is declared unreachable. If
418 command (i.e., it connects dynamically) then another connection attempt
419 is made. Otherwise the peer is killed.
421 .\"--------------------------------------------------------------------------
422 .SH "SERVICE COMMAND REFERENCE"
424 .\"* 10 Service commands
425 The commands provided by the service are as follows.
428 Make an active connection to the named
430 The service will submit the command
450 is provided if the peer's database record assigns the
452 key one of the values
463 is provided if the database record assigns a value
472 is provided if the database record assigns a value
481 is provided if the database record assigns a value
489 is provided if the peer's database record assigns the
491 key one of the values
502 is provided if the database record assigns a value
510 is the value assigned to the
512 key in the database record.
516 For each peer being tracked by the
518 service, write a line
521 (Compatibility note: it's possible that further information will be
522 provided about each peer, in the form of subsequent tokens. Clients
523 should be prepared to ignore such tokens.)
526 Lists the database record and additional information about the named
528 For each key/value pair, a line
534 is output. The key/value pairs are output in an arbitrary order.
536 In addition to the fields of the peer's database record, the following
537 additional keys are defined.
540 The number of failed pings in the current or most recent batch, in
544 The round-trip time of the most recent ping in milliseconds, in the form
548 if the most recent ping timed out,
551 if no pings have yet completed.
554 The maximum successful ping time so far in milliseconds, in the form
558 if no pings have yet succeeded.
561 The average successful ping time so far in milliseconds, in the form
565 if no pings have yet succeeded.
568 The minimum successful ping time so far in milliseconds, in the form
572 if no pings have yet succeeded.
575 The number of pings which have been declared timed out so far, in
579 The number of successful pings so far, in decimal.
582 The standard deviation of ping times so far in milliseconds, in the form
586 if no pings have yet succeeded.
591 if the peer has responded to a ping recently, and we are waiting for the
593 delay before we try again; or
595 if we are currently waiting for a ping to return.
601 is currently added, and its record in the peer database contains a
605 then force a reconnection attempt. See
606 .BR "Dynamic connection" .
609 Output a list of peers in the database. For each peer name
620 .BI "passive \fR[" options "\fR]\fP " user
621 If the database contains a user record mapping
627 line is written containing a freshly chosen challenge string. If the
630 message quoting this challenge within 30 seconds, the
632 service will issue an
634 request for the peer, as for the
636 command, except that the origin of the
638 packet is used as the peer's address.
642 The following option is recognized.
644 .BI "\-timeout " time
647 instead of 30 seconds. The
649 is expressed as a non-negative integer followed by
655 for days, hours, minutes or seconds respectively; if no suffix is given,
665 thinks that it can't respond to pings. This will usually provoke a
666 reconnection attempt. Use
668 instead unless you're trying to test
674 line identifying the peer corresponding to the
678 .\"--------------------------------------------------------------------------
681 .\"* 30 Notification broadcasts (NOTE codes)
682 All notifications issued by
684 begin with the tokens
687 .B "USER connect peerdb-update"
688 The peer database has changed. Other interested clients should reopen
691 .BI "USER connect ping-failed " peer " " error\fR...
696 failed; the server replied
700 .BI "USER connect " process\fR... " stdout " line
705 service unexpectedly wrote
707 to its standard output.
709 .\"--------------------------------------------------------------------------
712 .\"* 40 Warning broadcasts (WARN codes)
713 All warnings issued by
715 begin with the tokens
718 .BI "USER connect auto-add-failed " name " " error\fR...
719 The attempt to add the peer
721 automatically failed: the
727 .BI "USER connect ping-ok " peer
728 A reply was received to a
732 though earlier attempts had failed.
734 .BI "USER connect ping-timeout " peer " attempt " i " of " n
735 No reply was received to a
742 have been sent; if a total of
744 consecutive attempts time out, the
746 service will take further action.
748 .B "USER connect reconnecting " peer
749 The dynamically connected
751 seems to be unresponsive. The
753 service will attempt to reconnect.
755 .BI "USER connect " process\fR... " stderr " line
762 to its standard error.
764 .BI "USER connect " process\fR... " exit-nonzero " code
769 service exited with the nonzero status
772 .BI "USER connect " process\fR... " exit-signal S" code
777 service was killed by signal
781 is the numeric value of the fatal signal.
783 .BI "USER connect " process\fR... " exit-unknown " status
788 service exited with an unknown
792 is the raw exit status, as returned by
796 .\"--------------------------------------------------------------------------
797 .SH "CHILD PROCESS IDENTIFIERS"
799 .\"* 50 Child process identifiers
800 Some of the warnings and notifications refer to processes spawned by
802 under various circumstances. The process identifiers are as follows.
805 A child spawned in order to establish a dynamic connection with
808 .BI "disconnect " peer
809 A child spawned in order to shut down a dynamic connection with
813 A child spawned to deconfigure the network interface for
817 A child spawned to configure the network interface for
820 .\"--------------------------------------------------------------------------
825 .\"--------------------------------------------------------------------------
828 .BR tripe-service (7),
832 .\"--------------------------------------------------------------------------
835 Mark Wooding, <mdw@distorted.org.uk>
837 .\"----- That's all, folks --------------------------------------------------