chiark - git - mdw - tripe/blob - 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 --------------------------------------------------