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"
251 service supports two kinds of dynamic connection.
253 The new kind of dynamic association uses the built-in
255 protocol. If the peer's database record assigns a value to the
257 key, then the new connection protocol is used: this value is sent to the
258 peer during key-exchange, which should (if the peer is properly
259 configured) automatically establish the other end of the connection.
260 The string should have the form
261 .RI [ prefix\fB. ] tag ,
262 where the whole string names this host as it is known by the remote
265 names this host's public key. The passive server receives this string,
266 verifies that the sender has access to the claimed private key, and
271 notices, causing it to establish the passive peer. While the internals
272 are somewhat complex, configuration is pretty easy.
274 The older kind of dynamic association is rather more complicated to set
275 up, and involves running shell commands, and probably configuring SSH.
276 If a peer's database record assigns a value to the
280 service will attempt to establish a connection dynamically with the
281 peer. The value of the
283 key is invoked as a Bourne shell command, i.e.,
288 is executed. The command is expected to contact the remote server and
289 report, on standard output, a challenge string, typically by issuing
292 command to the instance of the
294 service running on the peer. The
296 service reads this challenge, and submits the command
304 command will issue a command such as
306 .B SVCSUBMIT connect passive
311 is the remote peer's name for this host.
313 Similarly, if the database record has a
317 will use this to give the peer explicit notification that its services
318 are no longer needed. The value of the
320 key is invoked as a Bourne shell command. This ought to result in a
322 command being issued to the peer's server.
324 In detail, the protocol for old-style dynamic connection works as
329 its partner, typically using the
331 option to suppress the key-exchange message which the server usually
332 sends immediately, since otherwise the passive peer will warn about it.
334 The active peer issues the command
337 .B SVCSUBMIT connect passive
340 to the passive peer's server. (Here,
342 is a name identifying the active peer; see below.) Doing this is the
343 responsibility of the
350 service on the passive peer responds with a
352 \(en a short Base64-encoded string. Somehow this challenge is sent back
353 to the passive peer without being intercepted.
355 The active peer sends a
357 containing the challenge to its passive partner. The passive server
358 announces the arrival of this message, and the originating address and
363 service running on the passive host receives the notification, matches
366 from the initial connection request, and
368 the appropriate peer, with the address from the
374 requests a list of current peers from the
376 server, and adopts any eligible peers. If the
378 flag was passed on the command line, the newly adopted peers have their
379 interfaces configured and connection attempts are made.
381 Adopted peers are pinged at regular intervals (using the
383 administrative command; see
384 .BR tripe-admin (5)).
385 This process can be configured by assigning values to keys in the peer's
386 database record. Some of these parameters are time intervals,
387 expressed as a nonnegative integer followed optionally by
393 for days, hours, minutes, or seconds, respectively; if no suffix is
394 given, seconds are assumed.
396 The parameters are as follows.
399 A time interval: how often to ping the peer to ensure that it's still
400 alive. The default is 30 seconds for active dynamic peers, and 5
401 minutes for passive peers.
403 The period for dynamic peers should be no longer than
407 \- 1). Consider an idle mobile peer which has its IP address changed
408 just before its passive peer begins pinging. The static peer's pings
409 will go to the old address until it receives a ping back from the mobile
410 peer. Therefore, the static peer has to keep pinging until it would
411 definitely have received an unsolicited ping from the mobile peer, and
412 therefore be informed of the change of address. And it's no use
413 learning about the change of address just after sending the last ping to
414 the old address, so the last retry doesn't count for the purposes of
417 Besides, the consequences of failed pinging differ between dynamic and
418 passive peers. In the former case, a failure provokes a reconnection
419 attempt, after which (hopefully) things will work again: it's probably a
420 good thing to check frequently and fail fast. In the latter case, the
421 dynamic peer will certainly have to notice that it's been abandoned and
422 arrange to retry, causing a communication failure where maybe there
423 wasn't really one before.
426 A time interval: how long to wait for a reply before retrying or giving
427 up. The default is 10 seconds.
430 An integer: how many failed attempts to make before deciding that the
431 peer is unreachable and taking action. The default is 5 attempts.
433 The algorithm is as follows. Send up to
435 pings; if a reply is received before the
437 then the peer is alive; wait
439 and check again. If no reply is received within the
443 times. If no attempt succeeds, the peer is declared unreachable. If
446 command (i.e., it connects dynamically) then another connection attempt
447 is made. Otherwise the peer is killed.
449 .\"--------------------------------------------------------------------------
450 .SH "SERVICE COMMAND REFERENCE"
452 .\"* 10 Service commands
453 The commands provided by the service are as follows.
456 Make an active connection to the named
458 The service will submit the command
479 is provided if the peer's database record assigns the
481 key one of the values
492 is provided if the database record assigns a value
501 is provided if the database record assigns a value
510 is provided if the database record assigns a value
518 is provided if the peer's database record assigns the
520 key one of the values
531 is provided if the database record assigns a value
539 is provided if the peer's database record assigns the
541 key one of the values
552 is the value assigned to the
554 key in the database record.
558 For each peer being tracked by the
560 service, write a line
563 (Compatibility note: it's possible that further information will be
564 provided about each peer, in the form of subsequent tokens. Clients
565 should be prepared to ignore such tokens.)
568 Lists the database record and additional information about the named
570 For each key/value pair, a line
576 is output. The key/value pairs are output in an arbitrary order.
578 In addition to the fields of the peer's database record, the following
579 additional keys are defined.
582 The number of failed pings in the current or most recent batch, in
586 The round-trip time of the most recent ping in milliseconds, in the form
590 if the most recent ping timed out,
593 if no pings have yet completed.
596 The maximum successful ping time so far in milliseconds, in the form
600 if no pings have yet succeeded.
603 The average successful ping time so far in milliseconds, in the form
607 if no pings have yet succeeded.
610 The minimum successful ping time so far in milliseconds, in the form
614 if no pings have yet succeeded.
617 The number of pings which have been declared timed out so far, in
621 The number of successful pings so far, in decimal.
624 The standard deviation of ping times so far in milliseconds, in the form
628 if no pings have yet succeeded.
633 if the peer has responded to a ping recently, and we are waiting for the
635 delay before we try again; or
637 if we are currently waiting for a ping to return.
643 is currently added, and its record in the peer database contains a
647 then force a reconnection attempt. See
648 .BR "Dynamic connection" .
651 Output a list of peers in the database. For each peer name
662 .BI "passive \fR[" options "\fR]\fP " user
663 If the database contains a user record mapping
669 line is written containing a freshly chosen challenge string. If the
672 message quoting this challenge within 30 seconds, the
674 service will issue an
676 request for the peer, as for the
678 command, except that the origin of the
680 packet is used as the peer's address.
684 The following option is recognized.
686 .BI "\-timeout " time
689 instead of 30 seconds. The
691 is expressed as a non-negative integer followed by
697 for days, hours, minutes or seconds respectively; if no suffix is given,
707 thinks that it can't respond to pings. This will usually provoke a
708 reconnection attempt. Use
710 instead unless you're trying to test
716 line identifying the peer corresponding to the
720 .\"--------------------------------------------------------------------------
723 .\"* 30 Notification broadcasts (NOTE codes)
724 All notifications issued by
726 begin with the tokens
729 .B "USER connect peerdb-update"
730 The peer database has changed. Other interested clients should reopen
733 .BI "USER connect ping-failed " peer " " error\fR...
738 failed; the server replied
742 .BI "USER connect " process\fR... " stdout " line
747 service unexpectedly wrote
749 to its standard output.
751 .\"--------------------------------------------------------------------------
754 .\"* 40 Warning broadcasts (WARN codes)
755 All warnings issued by
757 begin with the tokens
760 .BI "USER connect auto-add-failed " name " " error\fR...
761 The attempt to add the peer
763 automatically failed: the
769 .BI "USER connect knock-active-peer " name
770 The server reported a valid
772 message from a peer calling itself
774 but this is not a passive peer.
776 .BI "USER connect knock-unknown-peer " name
777 The server reported a valid
779 message from a peer calling itself
781 but no such peer is defined in the database.
783 .BI "USER connect knock-tag-mismatch peer " name " public-key-tag " tag
784 The server reported a valid
786 message from a peer calling itself
788 but this name doesn't match that peer's recorded public-key tag, which
792 .BI "USER connect ping-ok " peer
793 A reply was received to a
797 though earlier attempts had failed.
799 .BI "USER connect ping-timeout " peer " attempt " i " of " n
800 No reply was received to a
807 have been sent; if a total of
809 consecutive attempts time out, the
811 service will take further action.
813 .B "USER connect reconnecting " peer
814 The dynamically connected
816 seems to be unresponsive. The
818 service will attempt to reconnect.
820 .BI "USER connect " process\fR... " stderr " line
827 to its standard error.
829 .BI "USER connect " process\fR... " exit-nonzero " code
834 service exited with the nonzero status
837 .BI "USER connect " process\fR... " exit-signal S" code
842 service was killed by signal
846 is the numeric value of the fatal signal.
848 .BI "USER connect " process\fR... " exit-unknown " status
853 service exited with an unknown
857 is the raw exit status, as returned by
861 .\"--------------------------------------------------------------------------
862 .SH "CHILD PROCESS IDENTIFIERS"
864 .\"* 50 Child process identifiers
865 Some of the warnings and notifications refer to processes spawned by
867 under various circumstances. The process identifiers are as follows.
870 A child spawned in order to establish a dynamic connection with
873 .BI "disconnect " peer
874 A child spawned in order to shut down a dynamic connection with
878 A child spawned to deconfigure the network interface for
882 A child spawned to configure the network interface for
885 .\"--------------------------------------------------------------------------
890 .\"--------------------------------------------------------------------------
893 .BR tripe-service (7),
897 .\"--------------------------------------------------------------------------
900 Mark Wooding, <mdw@distorted.org.uk>
902 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob