HTTPTunnel v1.2.1

©2010 by Sebastian Weber <webersebastian at>

This software is licensed under the GNU general public license
Powered Logo
Download HTTPTunnel


Introduction to HTTPTunnel
HTTPTunnel is a tunneling software that can tunnel network connections through restrictive HTTP proxies over pure HTTP "GET" and "POST" requests.
HTTPTunnel consists of two components:
  1. The client that resides behind the firewall and accepts network connections on ports that will either be mapped to a specific remote target server/port (portmapping) or will act as a SOCKS (v4 and v5) proxy. The SOCKS authentication source can be a fixed user list, an LDAP or MySQL directory. The client is available as platform-independent Perl script or as Win32 binary.
  2. The server that resides on the internet and accepts HTTP requests from the client which will be translated and forwarded to network connections to the remote servers. Two different servers are available:
    • The hosted server, which is basically a PHP script that must be put on a PHP enabled web server. Putting the PHP script on a webserver enables the webserver to act as your HTTP tunnel server.
    • The standalone server, which is available as platform-independent Perl script or as Win32 binary. This server can be used if you have a box on the internet where you can run your own programs (e.g. your box at home).
Using the standalone server (as opposed to the hosted server) is recommended as it does not suffer from many restrictions that the webserver may impose on the PHP script, e.g. maximum script runtime (which will limit the duration of your connections), load-balanced server environments, provider policies etc.

Configuration of all components is done over a web-based GUI. SOCKS proxy cascading is supported.
Main features of HTTPTunnel
  • HTTPTunnel Client written in Perl for maximum portability, but also available as Win32 binary
  • HTTPTunnel Server available in two versions:
    - Standalone server (available as Perl script or Win32 binary)
    - Hosted PHP server to be used on an existing, PHP-enabled webserver
  • Configuration of all components is done over a web based GUI
  • Support of multiple simultaneous connections over one HTTPTunnel client/server
  • One HTTPTunnel server can serve multiple HTTPTunnel clients
  • SOCKS4 and SOCKS5 support
  • SOCKS cascading support
  • Multiple Security Features:
    - Strong network traffic encryption and/or compression
    - optional compression of tunnelled data
    - SOCKS and/or HTTP authentication from multiple directories
    - Intrusion Detection


To download the HTTPTunnel package, follow this link: Download HTTPTunnel
HTTPTunnel Client and HTTPTunnel Standalone Server (Perl script)
Perl v5.8.x or above
module threads 1.51 or above
optional modules:
- for compression support: Compress::Zlib
- for encryption support: Crypt::OpenSSL::RSA and Mcrypt
- for LDAP authentication: Net::LDAP
- for MySQL authentication: DBI and DBD::mysql or Net::MySQL
HTTPTunnel Client and HTTPTunnel Standalone Server (Win32 binary)
Tested on WinXP - should work on any 32-bit Windows though.
Please note: authentication from LDAP and MySQL ist disabled in the Win32 binaries.
HTTPTunnel PHP Server
PHP enabled webserver - PHP Version 5 or above is required!
optional PHP extensions:
- for compression support: zlib
- for encryption support: openssl and mcrypt
- for LDAP authentication: ldap
- for MySQL authentication: mysql
If you are running a Linux system (or most UNIX systems, including Mac OS X), you probably already have an installation of perl that was packaged with it. Type perl -v at the command line to find out which version.
ActivePerl is currently the most popular way to get Perl for Windows.
Unfortunately, most current perl distributions do not have the most recent threads module included. If you get a warning from HTTPTunnel about your threads version, you should upgrade your threads module. Please check the FAQ for instructions on doing this.
Installation of HTTPTunnel Client and Server Perl Scripts
To install the HTTPTunnel client and server Perl scripts, follow the steps below:
  1. Unpack the installation package
    tar xzf HTTPTunnel_*.tgz
  2. Copy the subdirectory "common" into the subdirectory "perl"
    cp -R common perl
  3. Change into the "perl" subdirectory
    cd perl
  4. Start or
  5. Open your browser to http://localhost:1079 (for the client configuration) or http://localhost (for the server configuration)
  6. Configure the HTTPTunnel client or server to meet your system and requirements
Installation of HTTPTunnel PHP Server
To install the HTTPTunnel PHP server, follow the steps below:
  1. Unpack the installation package
    tar xzf HTTPTunnel_*.tgz
  2. Copy the subdirectory "common" into the subdirectory "php"
    cp -R common php
  3. Copy the contents of the subdirectory "php" to a directory on your webserver
  4. Check the file htaccess.txt if you need to rename the file to .htaccess
  5. Open your browser to http://<yourhost>/<path to>/admin.php
  6. Configure the HTTPTunnel PHP server to meet your system and requirements
Installation of HTTPTunnel Client and Server Win32 binaries
Double-click the installer - d'oh :-)


Usage of HTTPTunnel
After you have successfully installed and set up the HTTPTunnel client and server, you can test your setup by trying to establish your first tunnel connection.

Start your network application and direct it either to a mapped port on the HTTPTunnel client or connect over the SOCKS proxy. If your application does not support SOCKS, there are utility programs that socksify, which allows adaptation of any software to connect to external networks via SOCKS, e.g.:

Client License Platform
FreeCap GPL Windows
Proxifier Shareware Windows
SocksCap Non-Commercial home use Windows
tsocks GPL POSIX (source)
NetConceal Anonymizer Shareware Windows

If your connection is successful - Congratulations, you set up your HTTPTunnel successfully. If not, check below under troubleshooting.
If you're having problems, do the following:
  1. Recheck your setup (HTTPTunnel client, HTTPTunnel server and - if applicable - your socksifier).
  2. check the client and server log for errors or start the client with the --debug option (see below).
  3. Check the FAQ.
  4. Increase the loglevel.
  5. As a last resort, file a bugreport at the project homepage or get support in the forum (see Feedback).
Usage and Command Line Options
httptunnel_* [--debug] [--<varname>=<value> ...] [<configfilename>]
Will cause all logging to be written to the logfile and the screen (n/a for Win32 binary)
Overrides settings in the configuration file
The program will use the given <filename> as configuration file


Frequently Asked Questions
The FAQ section is constantly growing - depending on what kind of feedback and questions I get from people using HTTPTunnel.
My tunnel setup does not work - what can I do to find out the reason?
I get a warning about my threads version - what can I do?
Issues with the PHP Server
The PHP Server does not work - I see traffic coming in, but no traffic being sent.
Even after checking the "Support load balanced servers" option the PHP server does not work.
Authentication does not work with the PHP Server
Inside HTTPTunnel
Can you provide some details on the HTTPTunnel protocol?
How exactly does HTTPTunnel encrypt network traffic?

Back to TopMy tunnel setup does not work - what can I do to find out the reason?

The most obvious setup errors are discovered by just checking the HTTPTunnel client or server log. If the log does not provide sufficient information, you should start a systematic troubleshooting going through your whole chain of proxies:

  1. Can your application connect to the HTTPTunnel Client? If not, the following could be the reason:
    • Does your application connect to the correct port on the HTTPTunnel client?
    • Is this port configured as portmapping or SOCKS port in the client config?
    • Did you turn on SOCKS authentication and is your application authenticating correctly?
    • Did you turn on "Limit access to IPs" but did not include the IP of the box your network app is running on?
  2. Can your HTTPTunnel client connect to the HTTPTunnel server? If not, the following could be the reason:
    • Check your proxy server name, port and authentication
    • Does your proxy support basic or NTLM authentication? If it only supports NTLM, you need an additional proxy to translate basic to NTLM authentication - e.g. NTLM Authorization Proxy Server
    • Check your HTTPTunnel server name and port - the server name MUST be a publicly available name on the internet - NOT a private address on your home network. This means, if you're using your dial-up box at home you need to specify the internet address your provider assigns to you, not the address on your local network (e.g. NOT 192.168.x.x). For dial-up boxes, it also helps to register with a free dynamic DNS service. Please note, that if your HTTPTunnel server resides on a private network, you need to set up your router to forward incoming traffic on the HTTPTunnel server port to the correct box (the one that the HTTPTunnel server is actually running on).
    • Is your box at home connected to the internet at all? It might be, that your provider disconnected your box because of network inactivity. If this happens, you should turn on the internet keep-alive on the HTTPTunnel server.
    • Check, if you can access the HTTPTunnel server admin interface from your HTTPTunnel client box with your browser. If yes, your client should also be able to access the server.
    • Did you turn on HTTP authentication on the server, and is your client authenticating correctly?
    • Did you turn on "Limit access to IPs"? If yes, please note, that you MUST include the IP of the public interface of your HTTP proxy - not the IP of your HTTPTunnel client. If you don't know the address and you need the enhanced security, please leave the field blank, connect to the server, check the server log to see what your IP was and include this IP into the field.
  3. Can your HTTPTunnel server access the remote server? If not, this should be stated in the HTTPTunnel client log.

Back to TopI get a warning about my threads version - what can I do?

You need to upgrade your threads version. This is done by downloading the most recent version from CPAN and installing it. Unfortunately, for installation to work, you need a working C-compiler on your system. On most UNIX systems this is not an issue, but on other systems like Microsoft Windows it is. This is why a pre-compiled version of the threads module 1.61 for win32 and ActivePerl is included into the distribution package. Just unpack the zip file into your ActivePerl installation directory, overwriting existing files if necessary. Afterwards you should not get the warning about your threads version anymore.
Other pre-compiled versions for systems without a C-compiler installed by default are welcome and will be included into the HTTPTunnel distribution.

Issues with the PHP server

Back to TopThe PHP Server does not work - I see traffic coming in, but no traffic being sent.

This is often a problem related to load-balanced web servers. Many webspace providers distribute HTTP requests to a single address evenly among multiple servers.
Solution: Check the "Support load balanced servers" option in the server configuration. This will make the PHP script try to cope with a load balanced server environment.

Back to TopEven after checking the "Support load balanced servers" option the PHP server does not work.

Then you're out of luck. Some webspace providers who use load balancing do not allow their servers to communicate with each other. This, however, is a prerequisite for the PHP server to work. Try if you can find a different webspace provider.

Back to TopAuthentication does not work with the PHP Server

For authentication to work, one of the following has to be true:

  • either PHP is running as a server module, not as CGI binary.
  • or mod_rewrite is installed and enabled on the webserver and the use of .htaccess files is permitted. If this is true, rename the supplied htaccess.txt file to .htaccess in the HTTPTunnel PHP directory. This .htaccess file will do the trick and store the HTTP username and password in an environment variable even if PHP is running as a CGI binary.
If neither of the above if true, HTTPTunnel native authentication will not work! As a workaround you can use the web server authentication. For this, you need to follow the steps below:
  1. Turn off all authentication in the HTTPTunnel PHP server config by leaving the username for the admin interface blank and setting HTTP Authentication Method to "none".
  2. Delete the supplied .htaccess file.
  3. Create two new files, .htaccess and .htpasswd, with the following contents (content in brackets [...] should be replaced by your own information).
    AuthType Basic
    AuthName "[Password Protected Area]"
    AuthUserFile [/path/to/].htpasswd
    require user [Username]


    To encrypt the plaintext password, you can use this page.
  4. Set all authentication in the HTTPTunnel client to use your specified username and password.
Inside HTTPTunnel

Back to TopCan you provide some details on the HTTPTunnel protocol?

The HTTPTunnel client listens on configured network ports for incoming client connections. Each new client connection triggers the following sequence of actions. The HTTPTunnel client and server will be referred to as the "httpclient" and "httpserver" - the network client and server will be referred to as the "client" and "server":

  1. If the port the client connected to, is the httpclient SOCKS port, a SOCKS handshake will be performed, thereby acquiring the server IP and port number and - if applicable - authenticating the client.
  2. The httpclient will open a main HTTP connection to the httpserver (using a proxy if applicable) via a HTTP GET request. This connection will stay open as long as the client or server does not close the connection.
  3. The httpserver will connect to the server and acknowlegde the connection to the httpclient if successful.
  4. From now on, any incoming data from the server will be forwarded by the httpserver to the httpclient over the main HTTP connection. Before sending the data, it will be compressed, encrypted and base64 encoded. The httpclient will base64 decode, decrypt and uncompress any data coming in from the main HTTP connection and forward it to the client.
  5. Any incoming data from the client will be forwarded by the httpclient to the httpserver over new, "outbound" HTTP connections. Whenever an outbound HTTP connection is triggered (see also the httpclient advanced configration options), the data will be sent inside a HTTP POST request to the httpserver. Afterwards the connection is closed again. Just like incoming data, outbound data is compressed, encrypted and base64 encoded before being sent. Unlike the main HTTP connection which is established one per tunneled connection, outbound HTTP connections are established whenever needed and can even transmit data packages belonging to different tunneled connections within one request.
    After receiving an outbound HTTP request, the httpserver will base64 decode, decrypt and uncompress the POSTed data. Afterwards it will distribute and forward the data to the correct server(s).
  6. The main HTTP tunnel connection is disconnected if either the server or client closes the network connection.

Back to TopHow exactly does HTTPTunnel encrypt network traffic?

The network traffic is encrypted using a symmetric stream cipher (RC4) with a key length of 2048 bit.
The symmetric key itself is encrypted using RSA public key encryption with a key length of 1024 bit and secure padding.


Feedback, Feature Requests, Bug Reporting etc.
Any kind of feedback is appreciated. I'm interessted in bug reports but also success stories. As the HTTPTunnel project is hosted by, all feedback mechanisms are provided by them:

Release Notes

Known Bugs / Limitations
  • PHP Server: at rare occasions, the PHP server seems to buffer too much data coming in from the tunnel client - especially if the connection to the remote server is slow.
HTTPTunnel Release Notes

f Bug fixed c Change of existing functionality + Added new functionality - Removed functionality
*1.2.1* 22.09.2010 Sebastian Weber + Client and server now available as Win32 binary (with shiny tray icons) f Perl: Fixed a bug with Base64 padding (thanks to hondza) f Perl Server: Fixed a bug in the tunnel servers main loop (thanks to Ron Harding) f PHP: Fixed a bug with the UNIX socket names *1.2* 16.05.2007 Sebastian Weber c Introduced config save workaround for PHP if cfg.php is not writeable c Performance enhancements sending outbound traffic by - increased IO buffering - connection keepalive + New option to disallow unencrypted connections on the server f Got rid of "connection refused" messages at the end of connections c Admin Interface will now redirect to /admin.tpl if no path is given f Fixed problems with restart after config change (module threads 1.51 or higher is required for this!) *1.1* 02.01.2007 Sebastian Weber f Fixed buggy logfile rotation in PHP + New DNS name resolution options + SOCKS BIND support + Encryption support + Intrusion detection c Client fallback for compression or encryption if server has no support c New connection handshake - v1.1 client will not work with v1.0 server and vice versa! *1.0 final* 27.12.2006 Sebastian Weber + Input validation in admin web interfaces + Client, Perlserver: the server sockets can be configured to listen on a specific interface c Client, Perlserver: now handles most startup errors gracefully f Client: fixed a bug related to UDP package tunneling *1.0 RC3* 27.10.2006 Sebastian Weber f PHPserver - Output buffering was not turned off correctly. Caused the PHP script not to work if buffering was turned on in php.ini f Perlserver, PHPserver - Remote IP was not returned correctly. Caused errors when the tunnel client could not resolve destination address *1.0 RC2* 21.10.2006 Sebastian Weber + Perl: Logfile cycling with zip and cleanup + Limit access to tunnel client/server by IP/netmask f Perl: got rid of perl -w warnings c Perl: Code cleaned up, moved to library + New functionality to view the logfile over the web admin interface + Perl: config parameter override through command line parameters (--varname=value) f Multiple Bugfixes *1.0 RC1* 11.10.2006 Sebastian Weber + Initial release