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 8 "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 2 minutes.
376 A time interval: how long to wait for a reply before retrying or giving
377 up. The default is 10 seconds.
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.
383 The algorithm is as follows. Send up to
385 pings; if a reply is received before the
387 then the peer is alive; wait
389 and check again. If no reply is received within the
393 times. If no attempt succeeds, the peer is declared unreachable. If
396 command (i.e., it connects dynamically) then another connection attempt
397 is made. Otherwise the peer is killed.
399 .\"--------------------------------------------------------------------------
400 .SH "SERVICE COMMAND REFERENCE"
402 .\"* 10 Service commands
403 The commands provided by the service are as follows.
406 Make an active connection to the named
408 The service will submit the command
428 is provided if the peer's database record assigns the
430 key one of the values
441 is provided if the database record assigns a value
450 is provided if the database record assigns a value
459 is provided if the database record assigns a value
467 is provided if the peer's database record assigns the
469 key one of the values
480 is provided if the database record assigns a value
488 is the value assigned to the
490 key in the database record.
494 For each peer being tracked by the
496 service, write a line
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.)
504 Lists the database record for the named
506 For each key/value pair, a line
512 is output. The key/value pairs are output in an arbitrary order.
518 is currently added, and its record in the peer database contains a
522 then force a reconnection attempt. See
523 .BR "Dynamic connection" .
526 Output a list of peers in the database. For each peer name
537 .BI "passive \fR[" options "\fR]\fP " user
538 If the database contains a user record mapping
544 line is written containing a freshly chosen challenge string. If the
547 message quoting this challenge within 30 seconds, the
549 service will issue an
551 request for the peer, as for the
553 command, except that the origin of the
555 packet is used as the peer's address.
559 The following option is recognized.
561 .BI "\-timeout " time
564 instead of 30 seconds. The
566 is expressed as a non-negative integer followed by
572 for days, hours, minutes or seconds respectively; if no suffix is given,
580 line identifying the peer corresponding to the
584 .\"--------------------------------------------------------------------------
587 .\"* 30 Notification broadcasts (NOTE codes)
588 All notifications issued by
590 begin with the tokens
593 .B "USER connect peerdb-update"
594 The peer database has changed. Other interested clients should reopen
597 .BI "USER connect ping-failed " peer " " error\fR...
602 failed; the server replied
606 .BI "USER connect " process\fR... " stdout " line
611 service unexpectedly wrote
613 to its standard output.
615 .\"--------------------------------------------------------------------------
618 .\"* 40 Warning broadcasts (WARN codes)
619 All warnings issued by
621 begin with the tokens
624 .BI "USER connect auto-add-failed " name " " error\fR...
625 The attempt to add the peer
627 automatically failed: the
633 .BI "USER connect ping-ok " peer
634 A reply was received to a
638 though earlier attempts had failed.
640 .BI "USER connect ping-timeout " peer " attempt " i " of " n
641 No reply was received to a
648 have been sent; if a total of
650 consecutive attempts time out, the
652 service will take further action.
654 .B "USER connect reconnecting " peer
655 The dynamically connected
657 seems to be unresponsive. The
659 service will attempt to reconnect.
661 .BI "USER connect " process\fR... " stderr " line
668 to its standard error.
670 .BI "USER connect " process\fR... " exit-nonzero " code
675 service exited with the nonzero status
678 .BI "USER connect " process\fR... " exit-signal S" code
683 service was killed by signal
687 is the numeric value of the fatal signal.
689 .BI "USER connect " process\fR... " exit-unknown " status
694 service exited with an unknown
698 is the raw exit status, as returned by
702 .\"--------------------------------------------------------------------------
703 .SH "CHILD PROCESS IDENTIFIERS"
705 .\"* 50 Child process identifiers
706 Some of the warnings and notifications refer to processes spawned by
708 under various circumstances. The process identifiers are as follows.
711 A child spawned in order to establish a dynamic connection with
714 .BI "disconnect " peer
715 A child spawned in order to shut down a dynamic connection with
719 A child spawned to deconfigure the network interface for
723 A child spawned to configure the network interface for
726 .\"--------------------------------------------------------------------------
731 .\"--------------------------------------------------------------------------
734 .BR tripe-service (7),
738 .\"--------------------------------------------------------------------------
741 Mark Wooding, <mdw@distorted.org.uk>
743 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob