--- /dev/null
+.\" -*-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 [ \-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 \-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 --------------------------------------------------
~mdw / tripe / blobdiff