chiark / gitweb /
debian/: Bump to Debhelper 10.
[tripe] / svc / connect.8.in
CommitLineData
a62f8e8a
MW
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.\"
11ad66c2
MW
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.
a62f8e8a 16.\"
11ad66c2
MW
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
20.\" for more details.
a62f8e8a
MW
21.\"
22.\" You should have received a copy of the GNU General Public License
11ad66c2 23.\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
a62f8e8a
MW
24.
25.\"--------------------------------------------------------------------------
cd450424 26.so ../common/defs.man \"@@@PRE@@@
a62f8e8a
MW
27.
28.\"--------------------------------------------------------------------------
0647ba7c 29.TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
a62f8e8a
MW
30.
31.\"--------------------------------------------------------------------------
32.SH "NAME"
33.
d64ce4ae 34connect \- tripe service to handle addition and removal of peers
a62f8e8a
MW
35.
36.\"--------------------------------------------------------------------------
37.SH "SYNOPSIS"
38.
39.B connect
40.RB [ \-a
41.IR socket ]
42.RB [ \-d
43.IR dir ]
44.RB [ \-p
45.IR file ]
46.br
47\& \c
48.RB [ \-\-daemon ]
49.RB [ \-\-debug ]
50.RB [ \-\-startup ]
51.
52.\"--------------------------------------------------------------------------
53.SH "DESCRIPTION"
54.
55The
56.B connect
d64ce4ae
MW
57service tracks associations with peers and performs various actions at
58appropriate stages in the assocations' lifecycles. It also registers
59new peers with the
a62f8e8a 60.BR tripe (8)
d64ce4ae
MW
61server on demand.
62.PP
63For example:
64.hP \*o
65When a peer is added, it arranges to configure the corresponding network
66interface correctly, and (if necessary) to initiate a dynamic
67connection.
68.hP \*o
69When a peer is removed, it arranges to bring down the network interface.
70.hP \*o
71While the peer is known, it
72.BR PING s
73it at regular intervals. If the peer fails to respond, it can be
74removed or reconnected.
a62f8e8a
MW
75.PP
76A peer may participate
77.I actively
78or
79.I passively
80in a connection. A peer participating actively (an
81.IR "active peer" )
82must already know its peer's connection details \(en its server's IP
83address and port. Active connection is suitable when the peer is a
84well-known server with stable details.
85.PP
86A server participating passively (a
87.IR "passive peer" )
88waits to be contacted by its peer, and discovers the peer's IP address
89and port as a result of a simple protocol described below. Passive
90connection is suitable when the peer's IP address or port can vary over
91time \(en e.g., if its IP address is assigned dynamically by DHCP or
92PPP, or if it is hidden behind a NAT firewall.
93.PP
94If both peers are active, we say that they establish an
95.IR "static connection" ;
96if one is passive, we say that they establish a
97.IR "dynamic connection" .
98At least one of the peers must be active; it is not possible to
99establish a connection if both peers are passive.
100.SS "Command line"
101In addition to the standard options described in
102.BR tripe-service (7),
103the following command-line options are recognized.
104.TP
105.BI "\-p, \-\-peerdb=" file
106Use
107.I file
108as the (CDB format) peer database. In the absence of this option, the
109file named by the
110.B TRIPEPEERDB
111environment variable is used; if that's not set either, then the default
112default of
113.B peers.cdb
114in the current working directory is used instead.
d64ce4ae
MW
115.
116.\"--------------------------------------------------------------------------
117.SH "BEHAVIOUR"
118.
119.SS "Adoption"
120The
121.B connect
122service maintains a list of peers which it has adopted. A peer is
123.I eligible for adoption
124if it has a record in the peer database
125.BR peers.cdb (5)
126in which the
127.B watch
128key is assigned the value
129.BR t ,
130.BR true ,
131.BR y ,
132.BR yes ,
133or
134.BR on .
135.PP
136The service pings adopted peers periodically in order to ensure that
137they are alive, and takes appropriate action if no replies are received.
a62f8e8a 138.PP
d64ce4ae
MW
139A peer is said to be
140.I adopted
141when it is added to this list, and
142.I disowned
143when it removed.
144.
145.SS "Configuring interfaces"
146The
147.B connect
148service configures network interfaces by invoking an
149.B ifup
150script. The script is invoked as
151.IP
152.I script
153.IR args ...
154.I peer
155.I ifname
156.IR addr ...
157.PP
158where the elements are as described below.
159.TP
160.IR script " and " args
161The peer's database record is retrieved; the value assigned to the
162.B ifup
163key is split into words (quoting is allowed; see
164.BR tripe-admin (5)
165for details). The first word is the
166.IR script ;
167subsequent words are gathered to form the
168.IR args .
169.TP
170.I peer
171The name of the peer.
172.TP
173.I ifname
174The name of the network interface associated with the peer, as returned
175by the
176.B IFNAME
177administration command (see
178.BR tripe-admin (5)).
179.TP
180.I addr
181The network address of the peer's TrIPE server, in the form output by
182the
183.B ADDR
184administration command (see
185.BR tripe-admin (5)).
186The first word of
187.I addr
188is therefore a network address family, e.g.,
189.BR INET .
190.PP
191The
192.B connect
193service deconfigures interfaces by invoking an
194.B ifdown
195script, in a similar manner. The script is invoked as
196.IP
197.I script
198.IR args ...
199.I peer
200.PP
201where the elements are as above, except that
202.I script
203and
204.I args
205are formed by splitting the value associated with the peer record's
206.B ifdown
207key.
208.PP
209In both of the above cases, if the relevant key (either
210.B ifup
211or
212.BR ifdown )
213is absent, no action is taken.
214.PP
215The key/value pairs in the peer's database record and the server's
216response to the
217.B ALGS
218administration command (see
219.BR tripe-admin (5))
220are passed to the
221.B ifup
222and
223.B ifdown
224scripts as environment variables. The environment variable name
225corresponding to a key is determined as follows:
226.hP \*o
227Convert all letters to upper-case.
228.hP \*o Convert all sequences of one or more non-alphanumeric characters
229to an underscore
230.RB ` _ '.
231.hP \*o Prefix the resulting name by
232.RB ` P_ '
233or
234.RB ` A_ '
235depending on whether it came from the peer's database record or the
236.B ALGS
237output respectively.
238.PP
239For example,
240.B ifname
241becomes
242.BR P_IFNAME ;
243and
244.B cipher-blksz
245becomes
246.BR A_CIPHER_BLKSZ .
247.
248.SS "Dynamic connection"
8362ac1c
MW
249The
250.B connect
251service supports two kinds of dynamic connection.
252.PP
253The new kind of dynamic association uses the built-in
254.B knock
255protocol. If the peer's database record assigns a value to the
256.B knock
257key, then the new connection protocol is used: this value is sent to the
258peer during key-exchange, which should (if the peer is properly
259configured) automatically establish the other end of the connection.
260The string should have the form
261.RI [ prefix\fB. ] tag ,
262where the whole string names this host as it is known by the remote
263host, and the
264.I tag
265names this host's public key. The passive server receives this string,
266verifies that the sender has access to the claimed private key, and
267emits a
268.B KNOCK
269notification which
270.B connect
271notices, causing it to establish the passive peer. While the internals
272are somewhat complex, configuration is pretty easy.
273.PP
274The older kind of dynamic association is rather more complicated to set
275up, and involves running shell commands, and probably configuring SSH.
d64ce4ae
MW
276If a peer's database record assigns a value to the
277.B connect
278key, then the
279.B connect
280service will attempt to establish a connection dynamically with the
281peer. The value of the
282.B connect
283key is invoked as a Bourne shell command, i.e.,
284.IP
285.B /bin/sh \-c
286.I connect
287.PP
288is executed. The command is expected to contact the remote server and
289report, on standard output, a challenge string, typically by issuing
290a
291.B passive
292command to the instance of the
293.B connect
294service running on the peer. The
295.B connect
296service reads this challenge, and submits the command
297.IP
298.B GREET
299.I peer
300.I challenge
301.PP
302Typically, the
303.B connect
304command will issue a command such as
305.IP
306.B SVCSUBMIT connect passive
307.I our-name
308.PP
309where
310.I our-name
311is the remote peer's name for this host.
312.PP
313Similarly, if the database record has a
314.B disconnect
315entry, then
316.B connect
317will use this to give the peer explicit notification that its services
318are no longer needed. The value of the
319.B disconnect
320key is invoked as a Bourne shell command. This ought to result in a
321.B KILL
322command being issued to the peer's server.
323.PP
8362ac1c
MW
324In detail, the protocol for old-style dynamic connection works as
325follows.
a62f8e8a
MW
326.hP 1.
327The active peer
328.BR ADD s
329its partner, typically using the
330.B \-cork
331option to suppress the key-exchange message which the server usually
332sends immediately, since otherwise the passive peer will warn about it.
333.hP 2.
d64ce4ae 334The active peer issues the command
a62f8e8a
MW
335.RS
336.IP
337.B SVCSUBMIT connect passive
338.I user
339.PP
340to the passive peer's server. (Here,
341.I user
d64ce4ae
MW
342is a name identifying the active peer; see below.) Doing this is the
343responsibility of the
344.B connect
345command.
a62f8e8a
MW
346.RE
347.hP 3.
348The
349.B connect
350service on the passive peer responds with a
351.I challenge
352\(en a short Base64-encoded string. Somehow this challenge is sent back
353to the passive peer without being intercepted.
354.hP 4.
355The active peer sends a
356.BR GREET ing
357containing the challenge to its passive partner. The passive server
358announces the arrival of this message, and the originating address and
359port.
360.hP 5.
361The
362.B connect
363service running on the passive host receives the notification, matches
364it up with the
365.I user
366from the initial connection request, and
367.BR ADD s
368the appropriate peer, with the address from the
369.BR GREET ing.
d64ce4ae
MW
370.
371.SS "Operation"
372On startup,
373.B connect
374requests a list of current peers from the
375.BR tripe (8)
376server, and adopts any eligible peers. If the
377.B \-\-startup
378flag was passed on the command line, the newly adopted peers have their
379interfaces configured and connection attempts are made.
a62f8e8a 380.PP
d64ce4ae
MW
381Adopted peers are pinged at regular intervals (using the
382.B PING
383administrative command; see
384.BR tripe-admin (5)).
385This process can be configured by assigning values to keys in the peer's
386database record. Some of these parameters are time intervals,
387expressed as a nonnegative integer followed optionally by
388.BR d ,
389.BR h ,
390.BR m ,
391or
392.B s
393for days, hours, minutes, or seconds, respectively; if no suffix is
394given, seconds are assumed.
395.PP
396The parameters are as follows.
397.TP
398.B every
399A time interval: how often to ping the peer to ensure that it's still
02c99524
MW
400alive. The default is 30 seconds for active dynamic peers, and 5
401minutes for passive peers.
402.IP
403The period for dynamic peers should be no longer than
404.I timeout
405\(mu
406.RI ( retries
407\- 1). Consider an idle mobile peer which has its IP address changed
408just before its passive peer begins pinging. The static peer's pings
409will go to the old address until it receives a ping back from the mobile
410peer. Therefore, the static peer has to keep pinging until it would
411definitely have received an unsolicited ping from the mobile peer, and
412therefore be informed of the change of address. And it's no use
413learning about the change of address just after sending the last ping to
414the old address, so the last retry doesn't count for the purposes of
415this calculation.
416.IP
417Besides, the consequences of failed pinging differ between dynamic and
418passive peers. In the former case, a failure provokes a reconnection
419attempt, after which (hopefully) things will work again: it's probably a
420good thing to check frequently and fail fast. In the latter case, the
421dynamic peer will certainly have to notice that it's been abandoned and
422arrange to retry, causing a communication failure where maybe there
423wasn't really one before.
d64ce4ae
MW
424.TP
425.B timeout
426A time interval: how long to wait for a reply before retrying or giving
427up. The default is 10 seconds.
428.TP
429.B retries
430An integer: how many failed attempts to make before deciding that the
431peer is unreachable and taking action. The default is 5 attempts.
432.PP
433The algorithm is as follows. Send up to
434.I retries
435pings; if a reply is received before the
436.I timeout
437then the peer is alive; wait
438.I every
439and check again. If no reply is received within the
440.IR timeout ,
441then try again up to
442.I retries
443times. If no attempt succeeds, the peer is declared unreachable. If
444the peer has a
445.B connect
446command (i.e., it connects dynamically) then another connection attempt
447is made. Otherwise the peer is killed.
a62f8e8a
MW
448.
449.\"--------------------------------------------------------------------------
450.SH "SERVICE COMMAND REFERENCE"
451.
452.\"* 10 Service commands
453The commands provided by the service are as follows.
454.SP
455.BI "active " peer
456Make an active connection to the named
457.IR peer .
458The service will submit the command
459.RS
460.IP
461.B ADD
462.RB [ \-cork ]
463.RB [ \-keepalive
464.IR time ]
48b84569
MW
465.RB [ \-key
466.IR tag ]
d64ce4ae
MW
467.RB [ \-priv
468.IR tag ]
6411163d 469.RB [ \-mobile ]
067aa5f0 470.RB [ \-ephemeral ]
a62f8e8a
MW
471.RB [ \-tunnel
472.IR driver ]
473.I address
474.PP
475Specifically:
476.hP \*o
477The option
478.B \-cork
479is provided if the peer's database record assigns the
480.B cork
481key one of the values
482.BR t ,
483.BR true ,
484.BR y ,
485.BR yes,
486or
487.BR on .
488.hP \*o
489The option
490.B \-keepalive
491.I time
492is provided if the database record assigns a value
493.I time
494to the
495.B keepalive
496key.
497.hP \*o
498The option
48b84569
MW
499.B \-key
500.I tag
501is provided if the database record assigns a value
502.I tag
503to the
504.B key
505key.
506.hP \*o
507The option
d64ce4ae
MW
508.B \-priv
509.I tag
510is provided if the database record assigns a value
511.I tag
512to the
513.B priv
514key.
515.hP \*o
516The option
6411163d
MW
517.B \-mobile
518is provided if the peer's database record assigns the
519.B mobile
520key one of the values
521.BR t ,
522.BR true ,
523.BR y ,
524.BR yes,
525or
526.BR on .
527.hP \*o
528The option
a62f8e8a
MW
529.B \-tunnel
530.I driver
531is provided if the database record assigns a value
532.I driver
533to the
534.B tunnel
535key.
536.hP \*o
067aa5f0
MW
537The option
538.B \-ephemeral
539is provided if the peer's database record assigns the
540.B ephemeral
541key one of the values
542.BR t ,
543.BR true ,
544.BR y ,
545.BR yes,
546or
547.BR on ;
548or if it is absent.
549.hP \*o
a62f8e8a
MW
550The
551.I address
552is the value assigned to the
553.B peer
554key in the database record.
555.RE
556.SP
d64ce4ae
MW
557.B adopted
558For each peer being tracked by the
559.B connect
560service, write a line
561.B INFO
562.IR name .
563(Compatibility note: it's possible that further information will be
564provided about each peer, in the form of subsequent tokens. Clients
565should be prepared to ignore such tokens.)
566.SP
a62f8e8a 567.BI "info " peer
b9dedfa6 568Lists the database record and additional information about the named
a62f8e8a
MW
569.IR peer .
570For each key/value pair, a line
571.RS
572.IP
573.B INFO
574.IB key = value
575.PP
576is output. The key/value pairs are output in an arbitrary order.
b9dedfa6
MW
577.PP
578In addition to the fields of the peer's database record, the following
579additional keys are defined.
580.TP
581.B failures
582The number of failed pings in the current or most recent batch, in
583decimal.
584.TP
585.B last-ping
586The round-trip time of the most recent ping in milliseconds, in the form
587.IB nn.n ms\fR,
588or
589.B timeout
590if the most recent ping timed out,
591or
592.B \-
593if no pings have yet completed.
594.TP
595.B max-ping
596The maximum successful ping time so far in milliseconds, in the form
597.IB nn.n ms\fR,
598or
599.B \-
600if no pings have yet succeeded.
601.TP
602.B mean-ping
603The average successful ping time so far in milliseconds, in the form
604.IB nn.n ms\fR,
605or
606.B \-
607if no pings have yet succeeded.
608.TP
609.B min-ping
610The minimum successful ping time so far in milliseconds, in the form
611.IB nn.n ms\fR,
612or
613.B \-
614if no pings have yet succeeded.
615.TP
616.B n-lost
617The number of pings which have been declared timed out so far, in
618decimal.
619.TP
620.B n-ping
621The number of successful pings so far, in decimal.
622.TP
623.B sd-ping
624The standard deviation of ping times so far in milliseconds, in the form
625.IB nn.n ms\fR,
626or
627.B \-
628if no pings have yet succeeded.
629.TP
630.B state
631One of the strings:
632.B idle
633if the peer has responded to a ping recently, and we are waiting for the
634.B every
635delay before we try again; or
636.B check
637if we are currently waiting for a ping to return.
a62f8e8a 638.RE
d64ce4ae
MW
639.SP
640.BI "kick " peer
641If
642.I peer
643is currently added, and its record in the peer database contains a
644.B connect
645key (see
646.BR peers.in )
647then force a reconnection attempt. See
648.BR "Dynamic connection" .
649.SP
650.B "list-active"
a62f8e8a
MW
651Output a list of peers in the database. For each peer name
652.IR peer ,
653a line
654.RS
655.IP
656.B INFO
657.I peer
658.PP
659is output.
660.RE
661.SP
662.BI "passive \fR[" options "\fR]\fP " user
663If the database contains a user record mapping
664.I user
665to some
666.I peer
667then an
668.B INFO
669line is written containing a freshly chosen challenge string. If the
670server receives a
671.BR GREET ing
672message quoting this challenge within 30 seconds, the
673.B connect
674service will issue an
675.B ADD
676request for the peer, as for the
677.B active
678command, except that the origin of the
679.BR GREET ing
680packet is used as the peer's address.
681.RS
682.\"+opts
683.PP
684The following option is recognized.
685.TP
686.BI "\-timeout " time
687Wait for
688.I time
689instead of 30 seconds. The
690.I time
691is expressed as a non-negative integer followed by
692.BR d ,
693.BR h ,
694.BR m ,
695or
696.B s
697for days, hours, minutes or seconds respectively; if no suffix is given,
698seconds are assumed.
699.\"-opts
700.RE
d3731285 701.SP
965eb987
MW
702.BI "sabotage " peer
703Sabotage the
704.I peer
705so that
706.B connect
707thinks that it can't respond to pings. This will usually provoke a
708reconnection attempt. Use
709.B kick
710instead unless you're trying to test
711.BR connect .
712.SP
d3731285
MW
713.BI "userpeer " user
714Output a single
715.B INFO
716line identifying the peer corresponding to the
717.I user
718name.
a62f8e8a
MW
719.
720.\"--------------------------------------------------------------------------
d64ce4ae 721.SH "NOTIFICATIONS"
a62f8e8a 722.
d64ce4ae
MW
723.\"* 30 Notification broadcasts (NOTE codes)
724All notifications issued by
725.B connect
726begin with the tokens
727.BR "USER connect" .
a62f8e8a 728.SP
d64ce4ae
MW
729.B "USER connect peerdb-update"
730The peer database has changed. Other interested clients should reopen
731the database.
a62f8e8a 732.SP
d64ce4ae
MW
733.BI "USER connect ping-failed " peer " " error\fR...
734An attempt to
735.B PING
736the named
a62f8e8a 737.I peer
d64ce4ae
MW
738failed; the server replied
739.B FAIL
740.IR error ...
a62f8e8a 741.SP
d64ce4ae 742.BI "USER connect " process\fR... " stdout " line
a62f8e8a 743The
d64ce4ae
MW
744.I process
745spawned by the
746.B connect
747service unexpectedly wrote
748.I line
749to its standard output.
a62f8e8a
MW
750.
751.\"--------------------------------------------------------------------------
752.SH "WARNINGS"
753.
754.\"* 40 Warning broadcasts (WARN codes)
755All warnings issued by
756.B connect
757begin with the tokens
758.BR "USER connect" .
759.SP
760.BI "USER connect auto-add-failed " name " " error\fR...
761The attempt to add the peer
762.I name
763automatically failed: the
764.B ADD
765command reported
766.B FAIL
767.IR error ...
d64ce4ae 768.SP
8362ac1c
MW
769.BI "USER connect knock-active-peer " name
770The server reported a valid
771.B knock
772message from a peer calling itself
773.I name
774but this is not a passive peer.
775.SP
776.BI "USER connect knock-unknown-peer " name
777The server reported a valid
778.B knock
779message from a peer calling itself
780.I name
781but no such peer is defined in the database.
782.SP
783.BI "USER connect knock-tag-mismatch peer " name " public-key-tag " tag
784The server reported a valid
785.B knock
786message from a peer calling itself
787.I name
788but this name doesn't match that peer's recorded public-key tag, which
789is
790.IR tag .
791.SP
d64ce4ae
MW
792.BI "USER connect ping-ok " peer
793A reply was received to a
794.B PING
795sent to the
796.IR peer ,
797though earlier attempts had failed.
798.SP
799.BI "USER connect ping-timeout " peer " attempt " i " of " n
800No reply was received to a
801.B PING
802sent to the
803.IR peer .
804So far,
805.I i
806.BR PING s
807have been sent; if a total of
808.I n
809consecutive attempts time out, the
810.B connect
811service will take further action.
812.SP
813.B "USER connect reconnecting " peer
814The dynamically connected
815.I peer
816seems to be unresponsive. The
817.B connect
818service will attempt to reconnect.
819.SP
820.BI "USER connect " process\fR... " stderr " line
821The
822.I process
823spawned by the
824.B connect
825service wrote
826.I line
827to its standard error.
828.SP
829.BI "USER connect " process\fR... " exit-nonzero " code
830The
831.I process
832spawned by the
833.B connect
834service exited with the nonzero status
835.IR code .
836.SP
837.BI "USER connect " process\fR... " exit-signal S" code
838The
839.I process
840spawned by the
841.B connect
842service was killed by signal
843.IR code .
844Here,
845.I code
846is the numeric value of the fatal signal.
847.SP
848.BI "USER connect " process\fR... " exit-unknown " status
849The
850.I process
851spawned by the
852.B connect
853service exited with an unknown
854.IR status .
855Here,
856.I status
857is the raw exit status, as returned by
858.BR waitpid (2),
859in hexadecimal.
860.
861.\"--------------------------------------------------------------------------
862.SH "CHILD PROCESS IDENTIFIERS"
863.
864.\"* 50 Child process identifiers
865Some of the warnings and notifications refer to processes spawned by
866.B connect
867under various circumstances. The process identifiers are as follows.
868.SP
869.BI "connect " peer
870A child spawned in order to establish a dynamic connection with
871.IR peer .
872.SP
873.BI "disconnect " peer
874A child spawned in order to shut down a dynamic connection with
875.IR peer .
876.SP
877.BI "ifdown " peer
878A child spawned to deconfigure the network interface for
879.IR peer .
880.SP
881.BI "ifup " peer
882A child spawned to configure the network interface for
883.IR peer .
a62f8e8a
MW
884.
885.\"--------------------------------------------------------------------------
886.SH "SUMMARY"
887.
888.\"= summary
889.
890.\"--------------------------------------------------------------------------
891.SH "SEE ALSO"
892.
893.BR tripe-service (7),
894.BR peers.in (5),
a62f8e8a
MW
895.BR tripe (8).
896.
897.\"--------------------------------------------------------------------------
898.SH "AUTHOR"
899.
900Mark Wooding, <mdw@distorted.org.uk>
901.
902.\"----- That's all, folks --------------------------------------------------