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" "01 Mai 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--connect \fIHOST\fB:\fIPORT\fB\fR
 180 Connect the client to the given host and port.  This will be read
 181 by the Clarkway master.  Thus, domain names are resolved in the
 182 master network instead of locally, and
 183 \fBlocalhost\fR will refer to the master
 184 itself.  This option is mandatory for client mode and ignored
 185 otherwise.
 186 .TP
 187 \fB--direct \fIHOST\fB[:\fIPORT\fB]\fR
 188 If a Clarkway client connects to the master LAN, the gateway
 189 usually has to forward all traffic between master and client.
 190 Alternatively, the client can ask the master to connect to it
 191 directly, bypassing the gateway.  This mode is faster and avoids
 192 traffic on the gateway host, but it requires that the host running
 193 the client is not firewalled (or at least accessible via port
 194 forwarding).  To activate direct connections, just pass the public
 195 IP address of the local host as \fIHOST\fR;
 196 \fIPORT\fR is chosen randomly if it is
 197 omitted.
 198
 199 If the gateway answers with ``sorry'', its Clarkway
 200 version is too old to support direct connection handling.
 201 .TP
 202 \fB--[no-]stdio\fR
 203 Write to standard output and read from standard input instead of
 204 opening a TCP server.  This is useful for debugging purposes and
 205 together with the \fBProxyCommand\fR option of
 206 \fBssh(1)\fR (see \fBssh_config(5)\fR).
 207 This option is optional for client mode and ignored otherwise.
 208 .TP
 209 \fB--listen [\fIHOST\fB:]\fIPORT\fB\fR
 210 Open a server on the given host and port.  If
 211 \fIHOST\fR is omitted, it defaults to
 212 \fB0.0.0.0\fR (all interfaces, gateway mode) or
 213 \fB127.0.0.1\fR (only available locally, client
 214 mode).  If \fB--listen\fR is not specified, the port
 215 will be chosen randomly if Clarkway acts as client, or set to 4354
 216 if acting as gateway.  This option is optional for client and
 217 gateway modes and ignored otherwise.
 218 .TP
 219 \fB--[no-]once\fR
 220 If operating in client mode, break down the server after the first
 221 connection finishes.  Otherwise, the option is ignored.
 222 .TP
 223 \fB--[no-]daemon\fR
 224 By default, Clarkway masters and gateways will go to background
 225 and detach from the current session.  You can use
 226 \fB--no-daemon\fR to avoid that.  Clients can also be
 227 given the \fB--daemon\fR switch to make them fork; as a
 228 special exception, clients with activated \fB--stdio\fR
 229 switch will never daemonize.
 230 .TP
 231 \fB--exec \fICOMMAND\fB\fR
 232 If operating in client mode, Clarkway will execute
 233 \fICOMMAND\fR after startup:  If
 234 \fB--stdio\fR is enabled, a pipe to the command is
 235 opened; otherwise, the command will be run upon server setup, and
 236 ``%h'' (hostname) and ``%p'' (port) will be
 237 substituted.  Implies \fB--once\fR\&.
 238 .TP
 239 \fB--pidfile \fIFILE\fB\fR
 240 Write Clarkway's process ID to \fIFILE\fR\&.
 241 If the file already exists on startup and contains a PID of a
 242 process that is still running, do not start.
 243 .TP
 244 \fB--logfile \fIFILE\fB\fR
 245 Log to \fIFILE\fR\&.  By default, logging is
 246 disabled or, if \fB--no-daemon\fR or
 247 \fB--stdio\fR is active, directed to standard error
 248 output.  Use the special value ``-'' to force logging
 249 to stderr, or ``off'' to disable it.
 250
 251 Clarkway will re-open the logfile on
 252 \fBSIGHUP\fR; this is useful for programs like
 253 \fBlogrotate(8)\fR\&.
 254 .TP
 255 \fB--loglevel \fILEVEL\fB\fR
 256 Set the minimum severity of log messages to
 257 \fILEVEL\fR\&.  Possible values are
 258 ``info'' (default), ``warn'' and
 259 ``fatal''\&.
 260 .TP
 261 \fB--logname \fINAME\fB\fR
 262 When logging, identify as program \fINAME\fR\&.
 263 This makes it easier to distinguish between multiple Clarkway
 264 daemons writing to one shared logfile.
 265 .TP
 266 \fB--help\fR
 267 Print a short usage information.
 268 .SH "YAML CONFIGURATION"
 269 .PP
 270 To simplify the invocation of Clarkway, YAML (YAML Ain't Markup
 271 Language) is used to provide for configuration files.  When stored in
 272 \fI~/.clw/profiles/\fR, these configuration files are
 273 called \fBprofiles\fR, and can be used like the
 274 \fBmaster\fR, \fBgateway\fR and
 275 \fBclient\fR options.  Inside the file, every option is
 276 specified on a line on its own, without the double dash, followed by a
 277 colon and the option's value.  Boolean options are set using the values
 278 \fByes\fR and \fBno\fR\&.  Option names
 279 inside curly braces are substituted by the according value,
 280 \fB{~}\fR expands to \fI~/.clw\fR,
 281 \fB{host}\fR/\fB{port}\fR to the given
 282 attribute of the \fB--connect\fR option and
 283 \fB{open}\fR/\fB{close}\fR to the
 284 respective brace.
 285 .SH "EXAMPLES"
 286
 287 .nf
 288 $ clw master --ca ~/.clw/example.com/ca.pem \\
 289              --cert ~/.clw/example.com/master.pem \\
 290              --key ~/.clw/example.com/masterkey.pem \\
 291              --subject '/C=AT/CN=Clarkway Example Gateway' \\
 292              --gateway example.com \\
 293              --reconnect 600 \\
 294              --pidfile /var/run/clarkway.pid \\
 295              --logfile /var/log/clarkway.log
 296
 297 .fi
 298 .PP
 299 Be a master using the specified SSL options.  On startup, connect to
 300 \fBexample.com\fR, port 4354, and reconnect after ten
 301 minutes (600 seconds) if the connection is lost.  Log everything to
 302 \fI/var/log/clarkway.log\fR\&.  Write the process ID to
 303 \fI/var/run/clarkway.pid\fR and refuse to start if
 304 another instance is already running.
 305
 306 .nf
 307 $ clw gateway --ca ~/.clw/example.com/ca.pem \\
 308               --cert ~/.clw/example.com/gateway.pem \\
 309               --key ~/.clw/example.com/gatewaykey.pem \\
 310               --subject '/C=AT/CN=Clarkway Example Master' \\
 311               --no-daemon
 312
 313 .fi
 314 .PP
 315 Act as a gateway using the specified SSL options.  All connections whose
 316 certificate subject are \fB/C=AT/CN=Clarkway Example
 317 Master\fR will be treated as master connections.  Clarkway
 318 will not daemonize, but instead stay in foreground and write its log
 319 messages to the standard error output.
 320 .PP
 321 For the last two examples, suppose the following file is saved as
 322 \fI~/.clw/profiles/irc\fR:
 323
 324 .nf
 325   mode: client
 326   ca: "{~}/example.com/ca.pem"
 327   cert: "{~}/example.com/client.pem"
 328   key: "{~}/example.com/clientkey.pem"
 329   subject: /C=AT/CN=Clarkway Example Gateway
 330   gateway: example.com
 331   connect: localhost:6667
 332   listen: "{port}"
 333   exec: "irssi -p %p -c %h"
 334
 335 .fi
 336
 337 .nf
 338 $ clw irc
 339 $ clw ~/.clw/profiles/irc
 340 $ clw client --ca ~/.clw/example.com/ca.pem \\
 341              --cert ~/.clw/example.com/client.pem \\
 342              --key ~/.clw/example.com/clientkey.pem \\
 343              --subject '/C=AT/CN=Clarkway Example Gateway' \\
 344              --gateway example.com \\
 345              --connect localhost:6667 \\
 346              --listen 6667 \\
 347              --exec 'irssi -p %p -c %h'
 348
 349 .fi
 350 .PP
 351 These three lines have the same effect: Start a client listening on port
 352 6667, using the specified CA, certificate and key, connected to port
 353 6667 on master and managed by the gateway on
 354 \fBexample.com\fR:4354.  Afterwards, run
 355 \fBirssi(1)\fR and connect it to
 356 \fBlocalhost\fR:6667.
 357
 358 .nf
 359 $ clw irc --connect localhost:5678
 360
 361 .fi
 362 .PP
 363 Use the \fIirc\fR profile defined above, but instead of
 364 connecting to port 6667 on the master server, open the non-standard port
 365 5678.  This will, in turn, cause Clarkway to listen on port 5678, and to
 366 execute \fBirssi\fR correctly.
 367 .SH "BUGS"
 368 .PP
 369 Please report bugs to the author.
 370 .SH "SEE ALSO"
 371 .PP
 372 \fBruby(1), openssl(1), openvpn(8)\fR
 373 .SH "COPYRIGHT"
 374 .PP
 375 Copyright (C) 2007 Michael Schutte <m.schutte.jr@gmail.com>
 376 .PP
 377 This is free software; you may redistribute unmodified and modified
 378 copies of it under the terms of the GNU General Public License.  There
 379 is \fBno warranty\fR, to the extent permitted by law.