Upgrade licence to GPLv3+.

[tripe] / svc / connect.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the connect service
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../defs.man.in \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH connect 8tripe "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
connect \- tripe service to handle addition and removal of peers
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B connect
.RB [ \-a
.IR socket ]
.RB [ \-d
.IR dir ]
.RB [ \-p
.IR file ]
.br
\&	\c
.RB [ \-\-daemon ]
.RB [ \-\-debug ]
.RB [ \-\-startup ]
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B connect
service tracks associations with peers and performs various actions at
appropriate stages in the assocations' lifecycles.  It also registers
new peers with the
.BR tripe (8)
server on demand.
.PP
For example:
.hP \*o
When a peer is added, it arranges to configure the corresponding network
interface correctly, and (if necessary) to initiate a dynamic
connection.
.hP \*o
When a peer is removed, it arranges to bring down the network interface.
.hP \*o
While the peer is known, it
.BR PING s
it at regular intervals.  If the peer fails to respond, it can be
removed or reconnected.
.PP
A peer may participate
.I actively
or
.I passively
in a connection.  A peer participating actively (an
.IR "active peer" )
must already know its peer's connection details \(en its server's IP
address and port.  Active connection is suitable when the peer is a
well-known server with stable details.
.PP
A server participating passively (a
.IR "passive peer" )
waits to be contacted by its peer, and discovers the peer's IP address
and port as a result of a simple protocol described below.  Passive
connection is suitable when the peer's IP address or port can vary over
time \(en e.g., if its IP address is assigned dynamically by DHCP or
PPP, or if it is hidden behind a NAT firewall.
.PP
If both peers are active, we say that they establish an
.IR "static connection" ;
if one is passive, we say that they establish a
.IR "dynamic connection" .
At least one of the peers must be active; it is not possible to
establish a connection if both peers are passive.
.SS "Command line"
In addition to the standard options described in
.BR tripe-service (7),
the following command-line options are recognized.
.TP
.BI "\-p, \-\-peerdb=" file
Use
.I file
as the (CDB format) peer database.  In the absence of this option, the
file named by the
.B TRIPEPEERDB
environment variable is used; if that's not set either, then the default
default of
.B peers.cdb
in the current working directory is used instead.
.
.\"--------------------------------------------------------------------------
.SH "BEHAVIOUR"
.
.SS "Adoption"
The
.B connect
service maintains a list of peers which it has adopted.  A peer is
.I eligible for adoption
if it has a record in the peer database
.BR peers.cdb (5)
in which the
.B watch
key is assigned the value
.BR t ,
.BR true ,
.BR y ,
.BR yes ,
or
.BR on .
.PP
The service pings adopted peers periodically in order to ensure that
they are alive, and takes appropriate action if no replies are received.
.PP
A peer is said to be
.I adopted
when it is added to this list, and
.I disowned
when it removed.
.
.SS "Configuring interfaces"
The
.B connect
service configures network interfaces by invoking an
.B ifup
script.  The script is invoked as
.IP
.I script
.IR args ...
.I peer
.I ifname
.IR addr ...
.PP
where the elements are as described below.
.TP
.IR script " and " args
The peer's database record is retrieved; the value assigned to the
.B ifup
key is split into words (quoting is allowed; see
.BR tripe-admin (5)
for details).  The first word is the
.IR script ;
subsequent words are gathered to form the
.IR args .
.TP
.I peer
The name of the peer.
.TP
.I ifname
The name of the network interface associated with the peer, as returned
by the
.B IFNAME
administration command (see
.BR tripe-admin (5)).
.TP
.I addr
The network address of the peer's TrIPE server, in the form output by
the
.B ADDR
administration command (see
.BR tripe-admin (5)).
The first word of
.I addr
is therefore a network address family, e.g.,
.BR INET .
.PP
The
.B connect
service deconfigures interfaces by invoking an
.B ifdown
script, in a similar manner.  The script is invoked as
.IP
.I script
.IR args ...
.I peer
.PP
where the elements are as above, except that
.I script
and
.I args
are formed by splitting the value associated with the peer record's
.B ifdown
key.
.PP
In both of the above cases, if the relevant key (either
.B ifup
or
.BR ifdown )
is absent, no action is taken.
.PP
The key/value pairs in the peer's database record and the server's
response to the
.B ALGS
administration command (see
.BR tripe-admin (5))
are passed to the
.B ifup
and
.B ifdown
scripts as environment variables.  The environment variable name
corresponding to a key is determined as follows:
.hP \*o
Convert all letters to upper-case.
.hP \*o Convert all sequences of one or more non-alphanumeric characters
to an underscore
.RB ` _ '.
.hP \*o Prefix the resulting name by
.RB ` P_ '
or
.RB ` A_ '
depending on whether it came from the peer's database record or the
.B ALGS
output respectively.
.PP
For example,
.B ifname
becomes
.BR P_IFNAME ;
and
.B cipher-blksz
becomes
.BR A_CIPHER_BLKSZ .
.
.SS "Dynamic connection"
If a peer's database record assigns a value to the
.B connect
key, then the
.B connect
service will attempt to establish a connection dynamically with the
peer.  The value of the
.B connect
key is invoked as a Bourne shell command, i.e.,
.IP
.B /bin/sh \-c
.I connect
.PP
is executed.  The command is expected to contact the remote server and
report, on standard output, a challenge string, typically by issuing
a
.B passive
command to the instance of the
.B connect
service running on the peer.  The
.B connect
service reads this challenge, and submits the command
.IP
.B GREET
.I peer
.I challenge
.PP
Typically, the
.B connect
command will issue a command such as
.IP
.B SVCSUBMIT connect passive
.I our-name
.PP
where
.I our-name
is the remote peer's name for this host.
.PP
Similarly, if the database record has a
.B disconnect
entry, then
.B connect
will use this to give the peer explicit notification that its services
are no longer needed.  The value of the
.B disconnect
key is invoked as a Bourne shell command.  This ought to result in a
.B KILL
command being issued to the peer's server.
.PP
In detail, the protocol for passive connection works as follows.
.hP 1.
The active peer
.BR ADD s
its partner, typically using the
.B \-cork
option to suppress the key-exchange message which the server usually
sends immediately, since otherwise the passive peer will warn about it.
.hP 2.
The active peer issues the command
.RS
.IP
.B SVCSUBMIT connect passive
.I user
.PP
to the passive peer's server.  (Here,
.I user
is a name identifying the active peer; see below.)  Doing this is the
responsibility of the
.B connect
command.
.RE
.hP 3.
The
.B connect
service on the passive peer responds with a
.I challenge
\(en a short Base64-encoded string.  Somehow this challenge is sent back
to the passive peer without being intercepted.
.hP 4.
The active peer sends a
.BR GREET ing
containing the challenge to its passive partner.  The passive server
announces the arrival of this message, and the originating address and
port.
.hP 5.
The
.B connect
service running on the passive host receives the notification, matches
it up with the
.I user
from the initial connection request, and
.BR ADD s
the appropriate peer, with the address from the
.BR GREET ing.
.
.SS "Operation"
On startup,
.B connect
requests a list of current peers from the
.BR tripe (8)
server, and adopts any eligible peers.  If the
.B \-\-startup
flag was passed on the command line, the newly adopted peers have their
interfaces configured and connection attempts are made.
.PP
Adopted peers are pinged at regular intervals (using the
.B PING
administrative command; see
.BR tripe-admin (5)).
This process can be configured by assigning values to keys in the peer's
database record.  Some of these parameters are time intervals,
expressed as a nonnegative integer followed optionally by
.BR d ,
.BR h ,
.BR m ,
or
.B s
for days, hours, minutes, or seconds, respectively; if no suffix is
given, seconds are assumed.
.PP
The parameters are as follows.
.TP
.B every
A time interval: how often to ping the peer to ensure that it's still
alive.  The default is 30 seconds for active dynamic peers, and 5
minutes for passive peers.
.IP
The period for dynamic peers should be no longer than
.I timeout
\(mu
.RI ( retries
\- 1).  Consider an idle mobile peer which has its IP address changed
just before its passive peer begins pinging.  The static peer's pings
will go to the old address until it receives a ping back from the mobile
peer.  Therefore, the static peer has to keep pinging until it would
definitely have received an unsolicited ping from the mobile peer, and
therefore be informed of the change of address.  And it's no use
learning about the change of address just after sending the last ping to
the old address, so the last retry doesn't count for the purposes of
this calculation.
.IP
Besides, the consequences of failed pinging differ between dynamic and
passive peers.  In the former case, a failure provokes a reconnection
attempt, after which (hopefully) things will work again: it's probably a
good thing to check frequently and fail fast.  In the latter case, the
dynamic peer will certainly have to notice that it's been abandoned and
arrange to retry, causing a communication failure where maybe there
wasn't really one before.
.TP
.B timeout
A time interval: how long to wait for a reply before retrying or giving
up.  The default is 10 seconds.
.TP
.B retries
An integer: how many failed attempts to make before deciding that the
peer is unreachable and taking action.  The default is 5 attempts.
.PP
The algorithm is as follows.  Send up to
.I retries
pings; if a reply is received before the
.I timeout
then the peer is alive; wait
.I every
and check again.  If no reply is received within the
.IR timeout ,
then try again up to
.I retries
times.  If no attempt succeeds, the peer is declared unreachable.  If
the peer has a
.B connect
command (i.e., it connects dynamically) then another connection attempt
is made.  Otherwise the peer is killed.
.
.\"--------------------------------------------------------------------------
.SH "SERVICE COMMAND REFERENCE"
.
.\"* 10 Service commands
The commands provided by the service are as follows.
.SP
.BI "active " peer
Make an active connection to the named
.IR peer .
The service will submit the command
.RS
.IP
.B ADD
.RB [ \-cork ]
.RB [ \-keepalive
.IR time ]
.RB [ \-key
.IR tag ]
.RB [ \-priv
.IR tag ]
.RB [ \-mobile ]
.RB [ \-tunnel
.IR driver ]
.I address
.PP
Specifically:
.hP \*o
The option
.B \-cork
is provided if the peer's database record assigns the
.B cork
key one of the values
.BR t ,
.BR true ,
.BR y ,
.BR yes,
or
.BR on .
.hP \*o
The option
.B \-keepalive
.I time
is provided if the database record assigns a value
.I time
to the
.B keepalive
key.
.hP \*o
The option
.B \-key
.I tag
is provided if the database record assigns a value
.I tag
to the
.B key
key.
.hP \*o
The option
.B \-priv
.I tag
is provided if the database record assigns a value
.I tag
to the
.B priv
key.
.hP \*o
The option
.B \-mobile
is provided if the peer's database record assigns the
.B mobile
key one of the values
.BR t ,
.BR true ,
.BR y ,
.BR yes,
or
.BR on .
.hP \*o
The option
.B \-tunnel
.I driver
is provided if the database record assigns a value
.I driver
to the
.B tunnel
key.
.hP \*o
The
.I address
is the value assigned to the
.B peer
key in the database record.
.RE
.SP
.B adopted
For each peer being tracked by the
.B connect
service, write a line
.B INFO
.IR name .
(Compatibility note: it's possible that further information will be
provided about each peer, in the form of subsequent tokens.  Clients
should be prepared to ignore such tokens.)
.SP
.BI "info " peer
Lists the database record for the named
.IR peer .
For each key/value pair, a line
.RS
.IP
.B INFO
.IB key = value
.PP
is output.  The key/value pairs are output in an arbitrary order.
.RE
.SP
.BI "kick " peer
If
.I peer
is currently added, and its record in the peer database contains a
.B connect
key (see
.BR peers.in )
then force a reconnection attempt.  See
.BR "Dynamic connection" .
.SP
.B "list-active"
Output a list of peers in the database.  For each peer name
.IR peer ,
a line
.RS
.IP
.B INFO
.I peer
.PP
is output.
.RE
.SP
.BI "passive \fR[" options "\fR]\fP " user
If the database contains a user record mapping
.I user
to some
.I peer
then an
.B INFO
line is written containing a freshly chosen challenge string.  If the
server receives a
.BR GREET ing
message quoting this challenge within 30 seconds, the
.B connect
service will issue an
.B ADD
request for the peer, as for the
.B active
command, except that the origin of the
.BR GREET ing
packet is used as the peer's address.
.RS
.\"+opts
.PP
The following option is recognized.
.TP
.BI "\-timeout " time
Wait for
.I time
instead of 30 seconds.  The
.I time
is expressed as a non-negative integer followed by
.BR d ,
.BR h ,
.BR m ,
or
.B s
for days, hours, minutes or seconds respectively; if no suffix is given,
seconds are assumed.
.\"-opts
.RE
.SP
.BI "userpeer " user
Output a single
.B INFO
line identifying the peer corresponding to the
.I user
name.
.
.\"--------------------------------------------------------------------------
.SH "NOTIFICATIONS"
.
.\"* 30 Notification broadcasts (NOTE codes)
All notifications issued by
.B connect
begin with the tokens
.BR "USER connect" .
.SP
.B "USER connect peerdb-update"
The peer database has changed.  Other interested clients should reopen
the database.
.SP
.BI "USER connect ping-failed " peer " " error\fR...
An attempt to
.B PING
the named
.I peer
failed; the server replied
.B FAIL
.IR error ...
.SP
.BI "USER connect " process\fR... " stdout " line
The
.I process
spawned by the
.B connect
service unexpectedly wrote
.I line
to its standard output.
.
.\"--------------------------------------------------------------------------
.SH "WARNINGS"
.
.\"* 40 Warning broadcasts (WARN codes)
All warnings issued by
.B connect
begin with the tokens
.BR "USER connect" .
.SP
.BI "USER connect auto-add-failed " name " " error\fR...
The attempt to add the peer
.I name
automatically failed: the
.B ADD
command reported
.B FAIL
.IR error ...
.SP
.BI "USER connect ping-ok " peer
A reply was received to a
.B PING
sent to the
.IR peer ,
though earlier attempts had failed.
.SP
.BI "USER connect ping-timeout " peer " attempt " i " of " n
No reply was received to a
.B PING
sent to the
.IR peer .
So far,
.I i
.BR PING s
have been sent; if a total of
.I n
consecutive attempts time out, the
.B connect
service will take further action.
.SP
.B "USER connect reconnecting " peer
The dynamically connected
.I peer
seems to be unresponsive.  The
.B connect
service will attempt to reconnect.
.SP
.BI "USER connect " process\fR... " stderr " line
The
.I process
spawned by the
.B connect
service wrote
.I line
to its standard error.
.SP
.BI "USER connect " process\fR... " exit-nonzero " code
The
.I process
spawned by the
.B connect
service exited with the nonzero status
.IR code .
.SP
.BI "USER connect " process\fR... " exit-signal S" code
The
.I process
spawned by the
.B connect
service was killed by signal
.IR code .
Here,
.I code
is the numeric value of the fatal signal.
.SP
.BI "USER connect " process\fR... " exit-unknown " status
The
.I process
spawned by the
.B connect
service exited with an unknown
.IR status .
Here,
.I status
is the raw exit status, as returned by
.BR waitpid (2),
in hexadecimal.
.
.\"--------------------------------------------------------------------------
.SH "CHILD PROCESS IDENTIFIERS"
.
.\"* 50 Child process identifiers
Some of the warnings and notifications refer to processes spawned by
.B connect
under various circumstances.  The process identifiers are as follows.
.SP
.BI "connect " peer
A child spawned in order to establish a dynamic connection with
.IR peer .
.SP
.BI "disconnect " peer
A child spawned in order to shut down a dynamic connection with
.IR peer .
.SP
.BI "ifdown " peer
A child spawned to deconfigure the network interface for
.IR peer .
.SP
.BI "ifup " peer
A child spawned to configure the network interface for
.IR peer .
.
.\"--------------------------------------------------------------------------
.SH "SUMMARY"
.
.\"= summary
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe-service (7),
.BR peers.in (5),
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------