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