.\" -*-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, . .\"----- That's all, folks --------------------------------------------------