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 [ \-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
 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
 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 --------------------------------------------------