=======
General
=======

HTTPTunnel - A simple client/server application for wrapping an arbitrary
TCP socket connection in HTTP.

Developed by Dr. Richard Mills of The Linux Academy Ltd.
Email: rmills@the-linux-academy.co.uk

Patches for building on Mac OSX supplied by Rachel Blackman.
Email: sparks@noderunner.net

Other patches/suggestions and debugging assistance also gratefully received
from Michael Weiser.
Email: michael@weiser.dinsnail.net

Licensed under the GPL - See the file COPYING for more details.

Any bug reports/patches for this software are most welcome (there's nothing
worse than stumbling across a report of a bug on some discussion board
somewhere that hasn't been reported back to me; if you tell me about a
problem I'll try my best to fix it), as are any questions about using
HTTPTunnel or updates people might feel are useful to this rather cursory
documentation.

A commercial HTTP tunnelling service called FireDrill based on this software
is also available for use. Please see http://www.fire-drill.com for more
details.


=======
Running
=======

A HTTPTunnel session consists of both a client and server end of a HTTP tunnel.

At the client end, the HTTPTunnel instance accepts incoming connections on a
TCP socket from some client application. Any traffic on that connection is
then wrapped in HTTP and transmitted down the tunnel to the server end. Any
HTTP traffic coming back from the server is correspondingly unwrapped at the
client instance and returned down the TCP socket to the connected client
application.

At the server end, the HTTPTunnel instance waits for a connection from a
HTTPTunnel client. It then reads wrapped HTTP data from that client instance,
and after unwrapping it, forwards it out over a TCP socket to its final
destination. Any traffic coming back from that destination is correspondingly
wrapped in HTTP and returned down the tunnel to the client instance.

A HTTPTunnel session therefore looks something like the sequence shown below:

----------  Raw   ----------  Tunnelled ----------  Raw   ----------
Client App <====> Client End <========> Server End <====> Server App
----------  Data  ----------    Data    ----------  Data  ----------

It is also possible for there to be an HTTP proxy between the HTTPTunnel
client and the HTTPTunnel server. This may be an explicit proxy that you
have to explicitly tell the HTTPTunnel client to send tunnelled data via,
or it can be an implicit (transparent) proxy that you don't need to know
anything about.


=================
Command Line Args
=================

HTTPTunnel takes a single mandatory command line argument - the location
of a configuration file. See below for an explanation of what to put in
the configuration file, or see the example configuration file
'example-configs.cfg' to be found in the config directory of this archive.


==========================
Configuration File Options
==========================

The config file specifies exactly how HTTPTunnel should operate and allows
the user to control such things as the type of tunnel to be used, the
addresses of either end of the tunnel, whether to go via a proxy server,
and more besides. Some examples of typical configuration setups are provided
in a file 'example-configs.cfg' to be found in the config directory of this
archive.

The config file is split into sections, the start of which is denoted by
the section name (in capital letters) within square brackets. At a minimum,
a complete config file must contain exactly one [GLOBAL] section and at least
one [CLIENT] or [SERVER] section. If so desired you may configure multiple
clients and/or servers by including additional [CLIENT] or [SERVER] sections.

Any lines in the config file after the start of the current section and
before the start of a subsequent section are considered to be within that 
labelled section. A line may then either contain a configuration option for
that section, be a comment, or be blank.

A configuration option line must not contain any whitespace at the start or
end of the line, it must begin with the name of the option being specified
(in lowercase), and any arguments for the option must be listed on the same
line separated by single spaces.

A comment line must begin with a '#', and everything else on that line is
ignored.

A blank line must contain no other characters.


The first section within the config file must be the [GLOBAL] section. This
section may contain the following options:

debug <level>
  This option controls the level of logging performed by HTTPTunnel. The debug
  level can be between 0 (minimal logging) and 5 (verbose logging).

pidfile <pidfile file>
  This option instructs HTTPTunnel to create the specified file containing
  our PID at startup, and remove it again at shutdown.

nodaemon
  This option instructs HTTPTunnel not to run as a daemon (the default
  behaviour is for HTTPTunnel to daemonize at launch).

dotest
  This option instructs HTTPTunnel to perform periodic tests on the connection
  to the other end of the tunnel so as to try and determine the best tunneling
  parameters to use. The testing enabled by this option is currently very
  experimental, and while it may help in some situations it is disabled by
  default.


A [CLIENT] config file section specifies the behaviour of a HTTPTunnel client
side instance. This section may contain the following options:

fixed <host> <port> [udp]
  This option tells the HTTPTunnel client to configure a fixed (as opposed to
  SOCKS) HTTP tunnel. A fixed tunnel is one where the ultimate destination for
  tunnelled traffic is fixed for all time. The address and port for the
  ultimate tunnelled traffic destination is given by the <host> and <port>
  arguments. If a third argument of 'udp' is specified, then HTTPTunnel will
  tunnel UDP data instead of the normal TCP connections. A [CLIENT] section
  must contain either a 'fixed' config option or a 'socks' config option.

socks
  This option tells the HTTPTunnel client to run a SOCKS server for client
  applications to connect to. A SOCKS server allows connecting client
  applications to control where the ultimate destination for tunnelled traffic
  is on a connection by connection basis. SOCKS tunnels are therefore more
  flexible than fixed tunnels and generally easier to configure and use.
  A [CLIENT] section must contain either a 'socks' config option or a 'fixed'
  config option.

listen {<ip> <port>} | {<port> [IPv4 | IPv6]}
  This option tells the HTTPTunnel client what IP address and port it should
  listen for incoming connections from client applications on. There are 2
  formats for the arguments; you must either specify both the port and the
  address of a local interface to listen on, or alternatively you can just
  specify a port to listen on (in which case HTTPTunnel will listen for
  incoming connections on any interface) and optionally specify whether to
  create an IPv4 or an IPv6 socket. If your are configuring a SOCKS tunnelling
  client you will probably want to specify the standard SOCKS port 1080 here.

tunsvr <host> [<port>]
  This option tells the HTTPTunnel client the address of the corresponding
  HTTPTunnel server it should connect to. If you do not specify a port it will
  assume it should connect on the standard HTTP port 80.

proxy <host> <port>
  This option tells the HTTPTunnel client the address of an explicit proxy
  server it should route all traffic via.

proxyauth <user> <passwd>
  This option tells the HTTPTunnel client what username and password to use
  if the proxy it is routing via requires authentication. The same username
  and password is used for basic, digest or NTLM authentication. If you need
  to also specify a domain to which the user belongs (sometimes necessary if
  you are going via a Windows proxy requiring NTLM authentication), you can
  combine the domain name with the username using a '\'. For example;
  DomainName\UserName.

cliauth <user> <passwd>
  This option tells the HTTPTunnel client what username and password to use
  to authenticate itself at the HTTPTunnel server.

ssl
  This option tells the HTTPTunnel client to create a secure encrypted (SSL)
  tunnel between itself and the HTTPTunnel server.


A [SERVER] config file section specifies the behaviour of a HTTPTunnel server
side instance. This section may contain the following options:

listen {<ip> <port>} | {<port> [IPv4 | IPv6]}
  This option tells the HTTPTunnel server what IP address and port it should
  listen for incoming connections from HTTPTunnel client applications on. There
  are 2 formats for the arguments; you must either specify both the port and the
  address of a local interface to listen on, or alternatively you can just
  specify a port to listen on (in which case HTTPTunnel will listen for
  incoming connections on any interface) and optionally specify whether to
  create an IPv4 or an IPv6 socket. Typically you will probably want to specify
  a standard HTTP port here, such as 80 or 8080.

svrauth
  This option tells the HTTPTunnel server that it should only accept
  connections from HTTPTunnel clients who successfully authenticate themselves.

user <user> <passwd> <max tunnels> <max bandwidth>
  This option allows you to specify the authentication details for connecting
  HTTPTunnel clients. The <user> and <passwd> fields are the username and
  password for the connecting client and correspond to the <user> and <passwd>
  arguments to the cliauth option in the [CLIENT] configuration. The
  <max tunnels> field specifies the maximum number of active tunnels that user
  will be permitted to have running at once. The <max bandwidth> field
  specifies the total maximum bandwidth (in Kb/s) that user will be permitted
  to use over all their currently active tunnels. A value of 0 for either
  <max tunnels> or <max bandwidth> means there is no limit imposed for that
  user. Multiple users can be configured simply by including multiple user
  configuration lines.

denyips <ip>[,<ip>...]
  This option tells the HTTPTunnel server to block any attempts to create
  tunnels to the specified IP address(es). A limited form of wildcard is
  supported for addresses ending in .* (for example; 127.*).

denyports <port>[,<port>...]
  This option tells the HTTPTunnel server to block any attempts to create
  tunnels to the specified port(s).

ssl <certificate file> <private key file>
  This option tells the HTTPTunnel server to create a secure encrypted (SSL)
  tunnel between itself and any connecting HTTPTunnel clients, and specifies
  the location of the SSL certificate file and private key file to use in
  negotiating the secure connection.


=============
Example Usage
=============

In this example we will show how to configure and run HTTPTunnel to tunnel an
SSH session over port 80 from a HTTPTunnel client on IP address 192.168.1.1,
via a HTTPTunnel server on IP address 192.168.2.1, to an ultimate SSH server
destination on IP address 192.168.3.1.

1) At the HTTPTunnel server end (192.168.2.1) create a config file containing
   the following options:

   [GLOBAL]
   # No special global options required

   [SERVER]
   # Listen for connections from the HTTPTunnel client on port 80
   listen 80


2) Run the HTTPTunnel server (still on 192.168.2.1):

   # httptunnel server.cfg


3) At the HTTPTunnel client end (192.168.1.1) create a config file containing
   the following options:

   [GLOBAL]
   # No special global options required

   [CLIENT]
   # Listen for connections from the ssh client on port 22
   listen 22

   # The HTTPTunnel server is at IP address 192.168.2.1, port 80
   tunsvr 192.168.2.1 80

   # Create a fixed tunnel to the ssh server at address 192.168.3.1, port 22
   fixed 192.168.3.1 22


4) Run the HTTPTunnel client (still on 192.168.1.1):

   # httptunnel client.cfg


5) At the client end you can now launch a tunnelled ssh session with:

   $ ssh user@localhost


