doc/clw.1

   1 .\" This manpage has been automatically generated by docbook2man
   2 .\" from a DocBook document.  This tool can be found at:
   3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
   4 .\" Please send any bug reports, improvements, comments, patches,
   5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
   6 .TH "CLW" "1" "10 Juni 2007" "Clarkway" ""
   7
   8 .SH NAME
   9 clw \- an SSL tunnelling application
  10 .SH SYNOPSIS
  11
  12 \fBclw\fR { \fB\fIMODE\fB\fR | \fB\fIOPTION\fB\fR\fI ...\fR }
  13
  14 .SH "INTRODUCTION"
  15 .PP
  16 \fBclw\fR, short for Clarkway, is a simple SSL tunnel
  17 written in \fBruby(1)\fR\&.  Its main purpose is to make
  18 hosts inside a local area network available to the outside world,
  19 thereby bypassing firewalls.
  20 .PP
  21 Usually, forwarding of a virtual private network (VPN,
  22 \fBopenvpn(8)\fR) is a smarter way to achieve that, but
  23 sometimes, it can be a security risk to make your computer a part of a
  24 network which is potentially far away.  At this point, Clarkway comes in
  25 handy: It has a very strict distinction between source and target of the
  26 connection.  While an attacker on the ``target'' host can
  27 connect to the ``source'' host when a VPN exists between
  28 them, Clarkway operates unidirectionally.  If the target host is
  29 properly secured and bidirectionality is important to you, a VPN is
  30 almost certainly the right choice.  Else, read on.
  31 .SH "DESCRIPTION"
  32
  33 .nf
  34                                                    +--------------+
  35          MASTER LAN                           +--- | --< [client] |
  36 +--------------------------+                  |    +--------------+
  37 | [.] [.] [.] [master] >-- | --> [gateway] <--+
  38 +--------------------------+                  |    +--------------+
  39                                               +--- | --< [client] |
  40                                                    +--------------+
  41
  42 .fi
  43 .PP
  44 The figure above shows the typical Clarkway architecture.  The
  45 \fBmaster\fR, part of the master LAN, is the host that
  46 you want to connect to.  One or more \fBclient\fRs, which
  47 may also be behind a firewall, want to connect to a host in the master
  48 network.  To achieve that, the master and the clients connect to a
  49 \fBgateway\fR which virtually connects them.
  50 .PP
  51 The usual procedure is as follows:
  52 .TP 3
  53 1.
  54 The Clarkway gateway starts up and waits for a master (control)
  55 connection.
  56 .TP 3
  57 2.
  58 The master connects to the gateway and waits for instructions.  The
  59 gateway is now ready to accept client connections.
  60 .TP 3
  61 3.
  62 A client connects to the gateway and requests a connection to a
  63 certain host and port in the master LAN.
  64 .TP 3
  65 4.
  66 The gateway forwards the connection request to the master host.
  67 .TP 3
  68 5.
  69 The master opens a TCP socket connected to the requested host and
  70 port.  Then, it opens another connection back to the gateway.  This
  71 complication is necessary because the gateway cannot connect to the
  72 master; a firewall might be between them.
  73 .TP 3
  74 6.
  75 The gateway notifies the client that the connection is available and
  76 starts to redirect the traffic between client and master.
  77 .PP
  78 To make sure that the first host which connects to the gateway really
  79 \fBis\fR the master, as well as assuring that only
  80 clients connect to the gateway, OpenSSL is used.  This means that you
  81 will have to set up a certificate authority before you can start using
  82 Clarkway.  \fBopenssl(1)\fR and several tutorials on the
  83 World Wide Web will help you with that.
  84 .SH "INVOCATION"
  85 .PP
  86 Clarkway does not follow the usual GNU command line syntax.  All options
  87 start with two dashes (``--'').  Arguments to options have to
  88 be separated using a whitespace; the ``assignment style''
  89 involving the equation mark is not supported.  Command line parameters
  90 which do not start with two dashes are treated as profile filenames.
  91 .TP
  92 \fBmaster\fR
  93 Act as Clarkway master: Connect to the gateway and handle
  94 connection requests from the clients.
  95
  96 This mode requires \fB--ca\fR, \fB--cert\fR,
  97 \fB--key\fR, \fB--subject\fR and
  98 \fB--gateway\fR\&.
  99 .TP
 100 \fBgateway\fR
 101 Act as Clarkway gateway: Start up an SSL server and wait for the
 102 master connection.  Then, allow clients to connect and arbitrate
 103 between them and the master.
 104
 105 This mode requires \fB--ca\fR, \fB--cert\fR,
 106 \fB--key\fR and \fB--subject\fR\&.
 107 .TP
 108 \fBclient\fR
 109 Act as Clarkway client: Connect to the gateway and be virtually
 110 connected to a host in the master network.  Redirect this traffic
 111 to another TCP port (which, absurdly, makes a Clarkway client a
 112 TCP server) or to standard output.
 113
 114 This mode requires \fB--ca\fR, \fB--cert\fR,
 115 \fB--key\fR, \fB--subject\fR,
 116 \fB--gateway\fR and \fB--connect\fR\&.
 117 .TP
 118 \fB\fIPROFILE\fB\fR
 119 Load a YAML configuration file from
 120 \fI~/.clw/profiles/PROFILE\fR\&.
 121 This only works if \fIPROFILE\fR does not
 122 contain dots or slashes.  See the ``YAML
 123 configuration'' section below.
 124 .TP
 125 \fB\fIFILENAME\fB\fR
 126 Load a YAML configuration file from
 127 \fIFILENAME\fR\&.  If
 128 \fIFILENAME\fR does not contain slashes or
 129 dots, a profile name is expected instead; you may prepend
 130 ``\&./'' to resolve the issue if the file is in the
 131 working directory.
 132 .TP
 133 \fB--ca \fIFILE\fB\fR
 134 Use the certificate authority (CA) found in
 135 \fIFILE\fR\&.  It will be
 136 used to check the identification of the site you connect to, or
 137 the site that connects to you, respectively.  Clients which are
 138 not known to the given CA will be refused.  This option is
 139 mandatory for all modes.
 140 .TP
 141 \fB--cert \fIFILE\fB\fR
 142 Load the certificate from
 143 \fIFILE\fR\&.  This option
 144 is mandatory for all modes.
 145 .TP
 146 \fB--key \fIFILE\fB\fR
 147 Load the RSA private key from
 148 \fIFILE\fR\&.  If
 149 necessary, the user is prompted for a passphrase to unlock the key
 150 before Clarkway is daemonized.  Always protect your private key;
 151 don't take it with you if it has not got a passphrase or is stored
 152 on a encrypted filesystem and watch out not to make it
 153 world-readable.  This option is mandatory for all modes.
 154 .TP
 155 \fB--crl \fIFILE\fB\fR
 156 Use the certificate revocation list stored in
 157 \fIFILE\fR\&.  The use of a CRL is optional.
 158 .TP
 159 \fB--subject \fIDN\fB\fR
 160 Master or client mode: Expect the gateway's certificate to have
 161 the given distinguished name (DN).  If the expected and the actual
 162 DN do not match, immediately close the connection again.
 163
 164 Gateway mode: Expect the master's certificate to have the given
 165 distinguished name.  If the expected and the actual DN do not
 166 match, consider peer to be a Clarkway client.
 167 .TP
 168 \fB--gateway \fIHOST\fB[:\fIPORT\fB]\fR
 169 Connect to the gateway listening on the given host and port.  If
 170 \fIPORT\fR is omitted, 4354 is used.  This
 171 option is mandatory for the client and master modes and ignored if
 172 running as a gateway.
 173 .TP
 174 \fB--reconnect \fIN\fB\fR
 175 If the master loses the gateway connection, retry after
 176 \fIN\fR instead of 60 seconds.  This option
 177 is optional for master mode and ignored otherwise.
 178 .TP
 179 \fB--keepalive \fIN\fB\fR
 180 Some routers close inactive TCP connections after a specific time.
 181 Use this option on the gateway side to send a
 182 ``keepalive'' line every \fIN\fR
 183 seconds of idle time to avoid that.  Recommended values are 3600
 184 (every hour) or 0 (default, disables the feature).
 185 .TP
 186 \fB--connect \fIHOST\fB:\fIPORT\fB\fR
 187 Connect the client to the given host and port.  This will be read
 188 by the Clarkway master.  Thus, domain names are resolved in the
 189 master network instead of locally, and
 190 \fBlocalhost\fR will refer to the master
 191 itself.  This option is mandatory for client mode and ignored
 192 otherwise.
 193 .TP
 194 \fB--direct \fIHOST\fB[:\fIPORT\fB]\fR
 195 If a Clarkway client connects to the master LAN, the gateway
 196 usually has to forward all traffic between master and client.
 197 Alternatively, the client can ask the master to connect to it
 198 directly, bypassing the gateway.  This mode is faster and avoids
 199 traffic on the gateway host, but it requires that the host running
 200 the client is not firewalled (or at least accessible via port
 201 forwarding).  To activate direct connections, just pass the public
 202 IP address of the local host as \fIHOST\fR;
 203 \fIPORT\fR is chosen randomly if it is
 204 omitted.
 205
 206 If the gateway answers with ``sorry'', its Clarkway
 207 version is too old to support direct connection handling.
 208 .TP
 209 \fB--direct-ports \fIPORT[RANGE]\fB,\fIPORT[RANGE]\fB,...\fR
 210 If the Clarkway master is behind a firewall, direct connections to
 211 filtered ports can cause problems.  This option allows to enable
 212 only certain ports which the master will connect to.  You can
 213 specify single ports (like 8080) or port ranges (like 500..1000);
 214 all other ports will be refused.  An example value is
 215 ``22,80,443,4000..5000'' to allow direct connections to
 216 the SSH, HTTP and HTTPS ports as well as to the port range 4000
 217 through 5000.
 218 .TP
 219 \fB--[no-]stdio\fR
 220 Write to standard output and read from standard input instead of
 221 opening a TCP server.  This is useful for debugging purposes and
 222 together with the \fBProxyCommand\fR option of
 223 \fBssh(1)\fR (see \fBssh_config(5)\fR).
 224 This option is optional for client mode and ignored otherwise.
 225 .TP
 226 \fB--listen [\fIHOST\fB:]\fIPORT\fB\fR
 227 Open a server on the given host and port.  If
 228 \fIHOST\fR is omitted, it defaults to
 229 \fB0.0.0.0\fR (all interfaces, gateway mode) or
 230 \fB127.0.0.1\fR (only available locally, client
 231 mode).  If \fB--listen\fR is not specified, the port
 232 will be chosen randomly if Clarkway acts as client, or set to 4354
 233 if acting as gateway.  This option is optional for client and
 234 gateway modes and ignored otherwise.
 235 .TP
 236 \fB--[no-]once\fR
 237 If operating in client mode, break down the server after the first
 238 connection finishes.  Otherwise, the option is ignored.
 239 .TP
 240 \fB--[no-]daemon\fR
 241 By default, Clarkway masters and gateways will go to background
 242 and detach from the current session.  You can use
 243 \fB--no-daemon\fR to avoid that.  Clients can also be
 244 given the \fB--daemon\fR switch to make them fork; as a
 245 special exception, clients with activated \fB--stdio\fR
 246 switch will never daemonize.
 247 .TP
 248 \fB--exec \fICOMMAND\fB\fR
 249 If operating in client mode, Clarkway will execute
 250 \fICOMMAND\fR after startup:  If
 251 \fB--stdio\fR is enabled, a pipe to the command is
 252 opened; otherwise, the command will be run upon server setup, and
 253 ``%h'' (hostname) and ``%p'' (port) will be
 254 substituted.  Implies \fB--once\fR\&.
 255 .TP
 256 \fB--pidfile \fIFILE\fB\fR
 257 Write Clarkway's process ID to \fIFILE\fR\&.
 258 If the file already exists on startup and contains a PID of a
 259 process that is still running, do not start.
 260 .TP
 261 \fB--logfile \fIFILE\fB\fR
 262 Log to \fIFILE\fR\&.  By default, logging is
 263 disabled or, if \fB--no-daemon\fR or
 264 \fB--stdio\fR is active, directed to standard error
 265 output.  Use the special value ``-'' to force logging
 266 to stderr, or ``off'' to disable it.
 267
 268 Clarkway will re-open the logfile on
 269 \fBSIGHUP\fR; this is useful for programs like
 270 \fBlogrotate(8)\fR\&.
 271 .TP
 272 \fB--loglevel \fILEVEL\fB\fR
 273 Set the minimum severity of log messages to
 274 \fILEVEL\fR\&.  Possible values are
 275 ``info'' (default), ``warn'' and
 276 ``fatal''\&.
 277 .TP
 278 \fB--logname \fINAME\fB\fR
 279 When logging, identify as program \fINAME\fR\&.
 280 This makes it easier to distinguish between multiple Clarkway
 281 daemons writing to one shared logfile.
 282 .TP
 283 \fB--help\fR
 284 Print a short usage information.
 285 .SH "YAML CONFIGURATION"
 286 .PP
 287 To simplify the invocation of Clarkway, YAML (YAML Ain't Markup
 288 Language) is used to provide for configuration files.  When stored in
 289 \fI~/.clw/profiles/\fR, these configuration files are
 290 called \fBprofiles\fR, and can be used like the
 291 \fBmaster\fR, \fBgateway\fR and
 292 \fBclient\fR options.  Inside the file, every option is
 293 specified on a line on its own, without the double dash, followed by a
 294 colon and the option's value.  Boolean options are set using the values
 295 \fByes\fR and \fBno\fR\&.  Option names
 296 inside curly braces are substituted by the according value,
 297 \fB{~}\fR expands to \fI~/.clw\fR,
 298 \fB{host}\fR/\fB{port}\fR to the given
 299 attribute of the \fB--connect\fR option and
 300 \fB{open}\fR/\fB{close}\fR to the
 301 respective brace.
 302 .SH "EXAMPLES"
 303
 304 .nf
 305 $ clw master --ca ~/.clw/example.com/ca.pem \\
 306              --cert ~/.clw/example.com/master.pem \\
 307              --key ~/.clw/example.com/masterkey.pem \\
 308              --subject '/C=AT/CN=Clarkway Example Gateway' \\
 309              --gateway example.com \\
 310              --reconnect 600 \\
 311              --pidfile /var/run/clarkway.pid \\
 312              --logfile /var/log/clarkway.log
 313
 314 .fi
 315 .PP
 316 Be a master using the specified SSL options.  On startup, connect to
 317 \fBexample.com\fR, port 4354, and reconnect after ten
 318 minutes (600 seconds) if the connection is lost.  Log everything to
 319 \fI/var/log/clarkway.log\fR\&.  Write the process ID to
 320 \fI/var/run/clarkway.pid\fR and refuse to start if
 321 another instance is already running.
 322
 323 .nf
 324 $ clw gateway --ca ~/.clw/example.com/ca.pem \\
 325               --cert ~/.clw/example.com/gateway.pem \\
 326               --key ~/.clw/example.com/gatewaykey.pem \\
 327               --subject '/C=AT/CN=Clarkway Example Master' \\
 328               --no-daemon
 329
 330 .fi
 331 .PP
 332 Act as a gateway using the specified SSL options.  All connections whose
 333 certificate subject are \fB/C=AT/CN=Clarkway Example
 334 Master\fR will be treated as master connections.  Clarkway
 335 will not daemonize, but instead stay in foreground and write its log
 336 messages to the standard error output.
 337 .PP
 338 For the last two examples, suppose the following file is saved as
 339 \fI~/.clw/profiles/irc\fR:
 340
 341 .nf
 342   mode: client
 343   ca: "{~}/example.com/ca.pem"
 344   cert: "{~}/example.com/client.pem"
 345   key: "{~}/example.com/clientkey.pem"
 346   subject: /C=AT/CN=Clarkway Example Gateway
 347   gateway: example.com
 348   connect: localhost:6667
 349   listen: "{port}"
 350   exec: "irssi -p %p -c %h"
 351
 352 .fi
 353
 354 .nf
 355 $ clw irc
 356 $ clw ~/.clw/profiles/irc
 357 $ clw client --ca ~/.clw/example.com/ca.pem \\
 358              --cert ~/.clw/example.com/client.pem \\
 359              --key ~/.clw/example.com/clientkey.pem \\
 360              --subject '/C=AT/CN=Clarkway Example Gateway' \\
 361              --gateway example.com \\
 362              --connect localhost:6667 \\
 363              --listen 6667 \\
 364              --exec 'irssi -p %p -c %h'
 365
 366 .fi
 367 .PP
 368 These three lines have the same effect: Start a client listening on port
 369 6667, using the specified CA, certificate and key, connected to port
 370 6667 on master and managed by the gateway on
 371 \fBexample.com\fR:4354.  Afterwards, run
 372 \fBirssi(1)\fR and connect it to
 373 \fBlocalhost\fR:6667.
 374
 375 .nf
 376 $ clw irc --connect localhost:5678
 377
 378 .fi
 379 .PP
 380 Use the \fIirc\fR profile defined above, but instead of
 381 connecting to port 6667 on the master server, open the non-standard port
 382 5678.  This will, in turn, cause Clarkway to listen on port 5678, and to
 383 execute \fBirssi\fR correctly.
 384 .SH "BUGS"
 385 .PP
 386 Please report bugs to the author.
 387 .SH "SEE ALSO"
 388 .PP
 389 \fBruby(1), openssl(1), openvpn(8)\fR
 390 .SH "COPYRIGHT"
 391 .PP
 392 Copyright (C) 2007 Michael Schutte <m.schutte.jr@gmail.com>
 393 .PP
 394 This is free software; you may redistribute unmodified and modified
 395 copies of it under the terms of the GNU General Public License.  There
 396 is \fBno warranty\fR, to the extent permitted by law.