Commit | Line | Data |
---|---|---|
a62f8e8a MW |
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 ] | |
48b84569 MW |
175 | .RB [ \-key |
176 | .IR tag ] | |
a62f8e8a MW |
177 | .RB [ \-tunnel |
178 | .IR driver ] | |
179 | .I address | |
180 | .PP | |
181 | Specifically: | |
182 | .hP \*o | |
183 | The option | |
184 | .B \-cork | |
185 | is provided if the peer's database record assigns the | |
186 | .B cork | |
187 | key one of the values | |
188 | .BR t , | |
189 | .BR true , | |
190 | .BR y , | |
191 | .BR yes, | |
192 | or | |
193 | .BR on . | |
194 | .hP \*o | |
195 | The option | |
196 | .B \-keepalive | |
197 | .I time | |
198 | is provided if the database record assigns a value | |
199 | .I time | |
200 | to the | |
201 | .B keepalive | |
202 | key. | |
203 | .hP \*o | |
204 | The option | |
48b84569 MW |
205 | .B \-key |
206 | .I tag | |
207 | is provided if the database record assigns a value | |
208 | .I tag | |
209 | to the | |
210 | .B key | |
211 | key. | |
212 | .hP \*o | |
213 | The option | |
a62f8e8a MW |
214 | .B \-tunnel |
215 | .I driver | |
216 | is provided if the database record assigns a value | |
217 | .I driver | |
218 | to the | |
219 | .B tunnel | |
220 | key. | |
221 | .hP \*o | |
222 | The | |
223 | .I address | |
224 | is the value assigned to the | |
225 | .B peer | |
226 | key in the database record. | |
227 | .RE | |
228 | .SP | |
229 | .BI "info " peer | |
230 | Lists the database record for the named | |
231 | .IR peer . | |
232 | For each key/value pair, a line | |
233 | .RS | |
234 | .IP | |
235 | .B INFO | |
236 | .IB key = value | |
237 | .PP | |
238 | is output. The key/value pairs are output in an arbitrary order. | |
239 | .RE | |
240 | .TP | |
241 | .B "list" | |
242 | Output a list of peers in the database. For each peer name | |
243 | .IR peer , | |
244 | a line | |
245 | .RS | |
246 | .IP | |
247 | .B INFO | |
248 | .I peer | |
249 | .PP | |
250 | is output. | |
251 | .RE | |
252 | .SP | |
253 | .BI "passive \fR[" options "\fR]\fP " user | |
254 | If the database contains a user record mapping | |
255 | .I user | |
256 | to some | |
257 | .I peer | |
258 | then an | |
259 | .B INFO | |
260 | line is written containing a freshly chosen challenge string. If the | |
261 | server receives a | |
262 | .BR GREET ing | |
263 | message quoting this challenge within 30 seconds, the | |
264 | .B connect | |
265 | service will issue an | |
266 | .B ADD | |
267 | request for the peer, as for the | |
268 | .B active | |
269 | command, except that the origin of the | |
270 | .BR GREET ing | |
271 | packet is used as the peer's address. | |
272 | .RS | |
273 | .\"+opts | |
274 | .PP | |
275 | The following option is recognized. | |
276 | .TP | |
277 | .BI "\-timeout " time | |
278 | Wait for | |
279 | .I time | |
280 | instead of 30 seconds. The | |
281 | .I time | |
282 | is expressed as a non-negative integer followed by | |
283 | .BR d , | |
284 | .BR h , | |
285 | .BR m , | |
286 | or | |
287 | .B s | |
288 | for days, hours, minutes or seconds respectively; if no suffix is given, | |
289 | seconds are assumed. | |
290 | .\"-opts | |
291 | .RE | |
292 | . | |
293 | .\"-------------------------------------------------------------------------- | |
294 | .SH "ERROR MESSAGES" | |
295 | . | |
296 | .\"* 20 Error messages (FAIL codes) | |
297 | The following error codes may be reported. | |
298 | .SP | |
299 | .B "connect-timeout" | |
300 | (For | |
301 | .BR passive .) | |
302 | No | |
303 | .BR GREET ing | |
304 | was received within the timeout period (default 30 seconds). | |
305 | .SP | |
306 | .BI "malformed-peer " peer " missing-key " key | |
307 | The database record for | |
308 | .I peer | |
309 | has no value for the | |
310 | .I key | |
311 | but one was expected. | |
312 | .SP | |
313 | .BI "passive-peer " peer | |
314 | (For | |
315 | .BR active .) | |
316 | An active connection to | |
317 | .I peer | |
318 | was requested, but the database record indicates that it is passive, | |
319 | i.e., its | |
320 | .B peer | |
321 | key has the value | |
322 | .BR PASSIVE . | |
323 | .SP | |
324 | .BI "unknown-peer " peer | |
325 | The | |
326 | .I peer | |
327 | has no record in the database. | |
328 | .SP | |
329 | .BI "unknown-user " user | |
330 | (For | |
331 | .BR passive .) | |
332 | There is no record of | |
333 | .I user | |
334 | in the database. | |
335 | . | |
336 | .\"-------------------------------------------------------------------------- | |
337 | .SH "WARNINGS" | |
338 | . | |
339 | .\"* 40 Warning broadcasts (WARN codes) | |
340 | All warnings issued by | |
341 | .B connect | |
342 | begin with the tokens | |
343 | .BR "USER connect" . | |
344 | .SP | |
345 | .BI "USER connect auto-add-failed " name " " error\fR... | |
346 | The attempt to add the peer | |
347 | .I name | |
348 | automatically failed: the | |
349 | .B ADD | |
350 | command reported | |
351 | .B FAIL | |
352 | .IR error ... | |
353 | . | |
354 | .\"-------------------------------------------------------------------------- | |
355 | .SH "SUMMARY" | |
356 | . | |
357 | .\"= summary | |
358 | . | |
359 | .\"-------------------------------------------------------------------------- | |
360 | .SH "SEE ALSO" | |
361 | . | |
362 | .BR tripe-service (7), | |
363 | .BR peers.in (5), | |
364 | .BR watch (8), | |
365 | .BR tripe (8). | |
366 | . | |
367 | .\"-------------------------------------------------------------------------- | |
368 | .SH "AUTHOR" | |
369 | . | |
370 | Mark Wooding, <mdw@distorted.org.uk> | |
371 | . | |
372 | .\"----- That's all, folks -------------------------------------------------- |