3 .\" Manual for the connect service
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
12 .\" TrIPE is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \"@@@PRE@@@
29 .\"--------------------------------------------------------------------------
30 .TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 connect \- tripe service to make connections to peers
37 .\"--------------------------------------------------------------------------
53 .\"--------------------------------------------------------------------------
58 service registers new peers with the
62 A peer may participate
66 in a connection. A peer participating actively (an
68 must already know its peer's connection details \(en its server's IP
69 address and port. Active connection is suitable when the peer is a
70 well-known server with stable details.
72 A server participating passively (a
74 waits to be contacted by its peer, and discovers the peer's IP address
75 and port as a result of a simple protocol described below. Passive
76 connection is suitable when the peer's IP address or port can vary over
77 time \(en e.g., if its IP address is assigned dynamically by DHCP or
78 PPP, or if it is hidden behind a NAT firewall.
80 If both peers are active, we say that they establish an
81 .IR "static connection" ;
82 if one is passive, we say that they establish a
83 .IR "dynamic connection" .
84 At least one of the peers must be active; it is not possible to
85 establish a connection if both peers are passive.
87 In addition to the standard options described in
88 .BR tripe-service (7),
89 the following command-line options are recognized.
91 .BI "\-p, \-\-peerdb=" file
94 as the (CDB format) peer database. In the absence of this option, the
97 environment variable is used; if that's not set either, then the default
100 in the current working directory is used instead.
101 .SS "Dynamic connection protocol"
102 Dynamic connections are used when the peer's address or port are
103 unknown, e.g., when it is hidden behind a NAT firewall.
105 The protocol for passive connection works as follows.
109 its partner, typically using the
111 option to suppress the key-exchange message which the server usually
112 sends immediately, since otherwise the passive peer will warn about it.
114 The active peer somehow issues the command
117 .B SVCSUBMIT connect passive
120 to the passive peer's server. (Here,
122 is a name identifying the active peer; see below.) This may be handled
130 service on the passive peer responds with a
132 \(en a short Base64-encoded string. Somehow this challenge is sent back
133 to the passive peer without being intercepted.
135 The active peer sends a
137 containing the challenge to its passive partner. The passive server
138 announces the arrival of this message, and the originating address and
143 service running on the passive host receives the notification, matches
146 from the initial connection request, and
148 the appropriate peer, with the address from the
153 service is capable of performing the active-peer part of this protocol,
156 command once the challenge has been obtained. The remaining difficulty
157 is in collecting the challenge from the passive peer.
159 .\"--------------------------------------------------------------------------
160 .SH "SERVICE COMMAND REFERENCE"
162 .\"* 10 Service commands
163 The commands provided by the service are as follows.
166 Make an active connection to the named
168 The service will submit the command
183 is provided if the peer's database record assigns the
185 key one of the values
196 is provided if the database record assigns a value
205 is provided if the database record assigns a value
213 is the value assigned to the
215 key in the database record.
219 Lists the database record for the named
221 For each key/value pair, a line
227 is output. The key/value pairs are output in an arbitrary order.
231 Output a list of peers in the database. For each peer name
242 .BI "passive \fR[" options "\fR]\fP " user
243 If the database contains a user record mapping
249 line is written containing a freshly chosen challenge string. If the
252 message quoting this challenge within 30 seconds, the
254 service will issue an
256 request for the peer, as for the
258 command, except that the origin of the
260 packet is used as the peer's address.
264 The following option is recognized.
266 .BI "\-timeout " time
269 instead of 30 seconds. The
271 is expressed as a non-negative integer followed by
277 for days, hours, minutes or seconds respectively; if no suffix is given,
282 .\"--------------------------------------------------------------------------
285 .\"* 20 Error messages (FAIL codes)
286 The following error codes may be reported.
293 was received within the timeout period (default 30 seconds).
295 .BI "malformed-peer " peer " missing-key " key
296 The database record for
300 but one was expected.
302 .BI "passive-peer " peer
305 An active connection to
307 was requested, but the database record indicates that it is passive,
313 .BI "unknown-peer " peer
316 has no record in the database.
318 .BI "unknown-user " user
321 There is no record of
325 .\"--------------------------------------------------------------------------
328 .\"* 40 Warning broadcasts (WARN codes)
329 All warnings issued by
331 begin with the tokens
334 .BI "USER connect auto-add-failed " name " " error\fR...
335 The attempt to add the peer
337 automatically failed: the
343 .\"--------------------------------------------------------------------------
348 .\"--------------------------------------------------------------------------
351 .BR tripe-service (7),
356 .\"--------------------------------------------------------------------------
359 Mark Wooding, <mdw@distorted.org.uk>
361 .\"----- That's all, folks --------------------------------------------------