server/tests.at: Add a retry loop in `COMMS_EPING'.

[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 2 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, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man.in \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
connect \- tripe service to make connections to 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 registers new peers with the
.BR tripe (8)
server.
.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.
.SS "Dynamic connection protocol"
Dynamic connections are used when the peer's address or port are
unknown, e.g., when it is hidden behind a NAT firewall.
.PP
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 somehow 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.)  This may be handled
by the
.BR watch (8)
service.
.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.
.PP
The
.BR watch (8)
service is capable of performing the active-peer part of this protocol,
sending the correct
.B GREET
command once the challenge has been obtained.  The remaining difficulty
is in collecting the challenge from the passive peer.
.
.\"--------------------------------------------------------------------------
.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 [ \-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 \-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
.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
.TP
.B "list"
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
.
.\"--------------------------------------------------------------------------
.SH "ERROR MESSAGES"
.
.\"* 20 Error messages (FAIL codes)
The following error codes may be reported.
.SP
.B "connect-timeout"
(For
.BR passive .)
No
.BR GREET ing
was received within the timeout period (default 30 seconds).
.SP
.BI "malformed-peer " peer " missing-key " key
The database record for
.I peer
has no value for the
.I key
but one was expected.
.SP
.BI "passive-peer " peer
(For
.BR active .)
An active connection to
.I peer
was requested, but the database record indicates that it is passive,
i.e., its
.B peer
key has the value
.BR PASSIVE .
.SP
.BI "unknown-peer " peer
The
.I peer
has no record in the database.
.SP
.BI "unknown-user " user
(For
.BR passive .)
There is no record of
.I user
in the database.
.
.\"--------------------------------------------------------------------------
.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 ...
.
.\"--------------------------------------------------------------------------
.SH "SUMMARY"
.
.\"= summary
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe-service (7),
.BR peers.in (5),
.BR watch (8),
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------