chiark / gitweb /
Use the new `mLib' annotations on varargs functions.
[tripe] / svc / connect.8.in
1 .\" -*-nroff-*-
2 .\".
3 .\" Manual for the connect service
4 .\"
5 .\" (c) 2008 Straylight/Edgeware
6 .\"
7 .
8 .\"----- Licensing notice ---------------------------------------------------
9 .\"
10 .\" This file is part of Trivial IP Encryption (TrIPE).
11 .\"
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.
16 .\"
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.
21 .\"
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.
25 .
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \"@@@PRE@@@
28 .
29 .\"--------------------------------------------------------------------------
30 .TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 connect \- tripe service to make connections to peers
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "SYNOPSIS"
39 .
40 .B connect
41 .RB [ \-a
42 .IR socket ]
43 .RB [ \-d
44 .IR dir ]
45 .RB [ \-p
46 .IR file ]
47 .br
48 \&      \c
49 .RB [ \-\-daemon ]
50 .RB [ \-\-debug ]
51 .RB [ \-\-startup ]
52 .
53 .\"--------------------------------------------------------------------------
54 .SH "DESCRIPTION"
55 .
56 The
57 .B connect
58 service registers new peers with the
59 .BR tripe (8)
60 server.
61 .PP
62 A peer may participate
63 .I actively
64 or
65 .I passively
66 in a connection.  A peer participating actively (an
67 .IR "active peer" )
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.
71 .PP
72 A server participating passively (a
73 .IR "passive peer" )
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.
79 .PP
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.
86 .SS "Command line"
87 In addition to the standard options described in
88 .BR tripe-service (7),
89 the following command-line options are recognized.
90 .TP
91 .BI "\-p, \-\-peerdb=" file
92 Use
93 .I file
94 as the (CDB format) peer database.  In the absence of this option, the
95 file named by the
96 .B TRIPEPEERDB
97 environment variable is used; if that's not set either, then the default
98 default of
99 .B peers.cdb
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.
104 .PP
105 The protocol for passive connection works as follows.
106 .hP 1.
107 The active peer
108 .BR ADD s
109 its partner, typically using the
110 .B \-cork
111 option to suppress the key-exchange message which the server usually
112 sends immediately, since otherwise the passive peer will warn about it.
113 .hP 2.
114 The active peer somehow issues the command
115 .RS
116 .IP
117 .B SVCSUBMIT connect passive
118 .I user
119 .PP
120 to the passive peer's server.  (Here,
121 .I user
122 is a name identifying the active peer; see below.)  This may be handled
123 by the
124 .BR watch (8)
125 service.
126 .RE
127 .hP 3.
128 The
129 .B connect
130 service on the passive peer responds with a
131 .I challenge
132 \(en a short Base64-encoded string.  Somehow this challenge is sent back
133 to the passive peer without being intercepted.
134 .hP 4.
135 The active peer sends a
136 .BR GREET ing
137 containing the challenge to its passive partner.  The passive server
138 announces the arrival of this message, and the originating address and
139 port.
140 .hP 5.
141 The
142 .B connect
143 service running on the passive host receives the notification, matches
144 it up with the
145 .I user
146 from the initial connection request, and
147 .BR ADD s
148 the appropriate peer, with the address from the
149 .BR GREET ing.
150 .PP
151 The
152 .BR watch (8)
153 service is capable of performing the active-peer part of this protocol,
154 sending the correct
155 .B GREET
156 command once the challenge has been obtained.  The remaining difficulty
157 is in collecting the challenge from the passive peer.
158 .
159 .\"--------------------------------------------------------------------------
160 .SH "SERVICE COMMAND REFERENCE"
161 .
162 .\"* 10 Service commands
163 The commands provided by the service are as follows.
164 .SP
165 .BI "active " peer
166 Make an active connection to the named
167 .IR peer .
168 The service will submit the command
169 .RS
170 .IP
171 .B ADD
172 .RB [ \-cork ]
173 .RB [ \-keepalive
174 .IR time ]
175 .RB [ \-key
176 .IR tag ]
177 .RB [ \-mobile ]
178 .RB [ \-tunnel
179 .IR driver ]
180 .I address
181 .PP
182 Specifically:
183 .hP \*o
184 The option
185 .B \-cork
186 is provided if the peer's database record assigns the
187 .B cork
188 key one of the values
189 .BR t ,
190 .BR true ,
191 .BR y ,
192 .BR yes,
193 or
194 .BR on .
195 .hP \*o
196 The option
197 .B \-keepalive
198 .I time
199 is provided if the database record assigns a value
200 .I time
201 to the
202 .B keepalive
203 key.
204 .hP \*o
205 The option
206 .B \-key
207 .I tag
208 is provided if the database record assigns a value
209 .I tag
210 to the
211 .B key
212 key.
213 .hP \*o
214 The option
215 .B \-mobile
216 is provided if the peer's database record assigns the
217 .B mobile
218 key one of the values
219 .BR t ,
220 .BR true ,
221 .BR y ,
222 .BR yes,
223 or
224 .BR on .
225 .hP \*o
226 The option
227 .B \-tunnel
228 .I driver
229 is provided if the database record assigns a value
230 .I driver
231 to the
232 .B tunnel
233 key.
234 .hP \*o
235 The
236 .I address
237 is the value assigned to the
238 .B peer
239 key in the database record.
240 .RE
241 .SP
242 .BI "info " peer
243 Lists the database record for the named
244 .IR peer .
245 For each key/value pair, a line
246 .RS
247 .IP
248 .B INFO
249 .IB key = value
250 .PP
251 is output.  The key/value pairs are output in an arbitrary order.
252 .RE
253 .TP
254 .B "list"
255 Output a list of peers in the database.  For each peer name
256 .IR peer ,
257 a line
258 .RS
259 .IP
260 .B INFO
261 .I peer
262 .PP
263 is output.
264 .RE
265 .SP
266 .BI "passive \fR[" options "\fR]\fP " user
267 If the database contains a user record mapping
268 .I user
269 to some
270 .I peer
271 then an
272 .B INFO
273 line is written containing a freshly chosen challenge string.  If the
274 server receives a
275 .BR GREET ing
276 message quoting this challenge within 30 seconds, the
277 .B connect
278 service will issue an
279 .B ADD
280 request for the peer, as for the
281 .B active
282 command, except that the origin of the
283 .BR GREET ing
284 packet is used as the peer's address.
285 .RS
286 .\"+opts
287 .PP
288 The following option is recognized.
289 .TP
290 .BI "\-timeout " time
291 Wait for
292 .I time
293 instead of 30 seconds.  The
294 .I time
295 is expressed as a non-negative integer followed by
296 .BR d ,
297 .BR h ,
298 .BR m ,
299 or
300 .B s
301 for days, hours, minutes or seconds respectively; if no suffix is given,
302 seconds are assumed.
303 .\"-opts
304 .RE
305 .SP
306 .BI "userpeer " user
307 Output a single
308 .B INFO
309 line identifying the peer corresponding to the
310 .I user
311 name.
312 .
313 .\"--------------------------------------------------------------------------
314 .SH "ERROR MESSAGES"
315 .
316 .\"* 20 Error messages (FAIL codes)
317 The following error codes may be reported.
318 .SP
319 .B "connect-timeout"
320 (For
321 .BR passive .)
322 No
323 .BR GREET ing
324 was received within the timeout period (default 30 seconds).
325 .SP
326 .BI "malformed-peer " peer " missing-key " key
327 The database record for
328 .I peer
329 has no value for the
330 .I key
331 but one was expected.
332 .SP
333 .BI "passive-peer " peer
334 (For
335 .BR active .)
336 An active connection to
337 .I peer
338 was requested, but the database record indicates that it is passive,
339 i.e., its
340 .B peer
341 key has the value
342 .BR PASSIVE .
343 .SP
344 .BI "unknown-peer " peer
345 The
346 .I peer
347 has no record in the database.
348 .SP
349 .BI "unknown-user " user
350 (For
351 .B passive
352 and
353 .BR userinfo .)
354 There is no record of
355 .I user
356 in the database.
357 .
358 .\"--------------------------------------------------------------------------
359 .SH "WARNINGS"
360 .
361 .\"* 40 Warning broadcasts (WARN codes)
362 All warnings issued by
363 .B connect
364 begin with the tokens
365 .BR "USER connect" .
366 .SP
367 .BI "USER connect auto-add-failed " name " " error\fR...
368 The attempt to add the peer
369 .I name
370 automatically failed: the
371 .B ADD
372 command reported
373 .B FAIL
374 .IR error ...
375 .
376 .\"--------------------------------------------------------------------------
377 .SH "SUMMARY"
378 .
379 .\"= summary
380 .
381 .\"--------------------------------------------------------------------------
382 .SH "SEE ALSO"
383 .
384 .BR tripe-service (7),
385 .BR peers.in (5),
386 .BR watch (8),
387 .BR tripe (8).
388 .
389 .\"--------------------------------------------------------------------------
390 .SH "AUTHOR"
391 .
392 Mark Wooding, <mdw@distorted.org.uk>
393 .
394 .\"----- That's all, folks --------------------------------------------------