Tunnel Library

Introduction

The Tunnel Library is a Java library for doing stream based I/O in Java over different kinds of transports. The design philosophy behind the Tunnel Library is to provide the developer with plain Java Socket and ServerSocket instances so that 1) the developer does not have to learn a new or complicated API to use the Tunnel Library, and 2) the developer can directly reuse any existing code or third-party libraries based on Java sockets without any modifications.

Basic Usage

The basics are always the same: on the client side you use a TunnelClient instance to create connections to the the tunnel server. The code looks like this:

TunnelClient tc = ...;
Socket s = tc.connect();

The returned socket is a regular Java socket and can be used like any other Socket. How the TunnelClient instance is obtained depends on the specific transport you want to use. For example, to obtain an HttpTunnelClient instance for tunneling over HTTP, the following code would do the trick:

TunnelClient tc = new HttpTunnelClient(new URI("http://myserver.mydomain.com/myservlet"));

On the server side you use a TunnelServer instance to accept connections to the tunnel server. The code looks like this:

TunnelServer ts = ...;
while (condition) {
  Socket s = ts.accept();
  handleInAnotherThread(s);
}

where the handleInAnotherThread method is your method to handle the socket (which should typically be done in another thread so that the server can accept new connections immediately). If you need a ServerSocket instead of a TunnelServer, you can create one as simply as this:

TunnelServer ts = ...;
ServerSocket ss = new TunnelServerSocket(ts);

Key Features

HTTP Tunnel

In many environments, making a direct TCP/IP connection is becoming ever more difficult due to intervening (content-filtering) firewalls, proxies and NAT routers. Outgoing client connections are often restricted to HTTP connections on port 80 only, while incoming client connections are made impossible due to NAT routers and standard firewall software. Even when normal outgoing TCP connections are possible, badly implemented NAT routers often cause the connections to be brittle and reset if the connection is idle for too long (with too long sometimes being less than 60 seconds).

The HTTP tunnel supports Java Socket based I/O transparently over HTTP in all these situations, doing all the hard work for you and letting you concentrate on developing the core of your application. The HTTP tunnel:

• is extremely fast (it can easily handle 100MB/s)
• supports a large number of tunnels to a single server
• supports both the http and https protocols
• supports http proxies
• supports basic/digest/ntlm authentication
• supports basic/digest/ntlm proxy authorization
• is compatible with Apache 2.2 mod_proxy or mod_jk (ajp required, MPM-worker recommended)
• runs on any Servlet 2.4 compatible servlet container
• has many parameters to tune the tunnel to specific use cases

Multiplexer

The Multiplexer acts both as a TunnelClient and TunnelServer and multiplexes many connections over a single Java Socket (and thus also possibly over another tunnel). Since the multiplexer acts as a TunnelServer it also accepts connections, allowing connections to be made both ways even in environments with NAT. The Multiplexer:

• is extremely fast
• supports up to 64K connections per underlying connection
• shares bandwidth fairly between all the connections and saves on connection setup time
• allows the server side of the underlying connection to make connections back to the client
• is very useful when combined with the HTTP tunnel, allowing transparent bidirectional setup of connections

Multiplexed RMI Socket Factories

The multiplexed RMI Socket Factories combine the power of the Multiplexer with RMI. This allows you to use the RMI framework over a single underlying connection. Together with the HTTP tunnel this allows you to use bidirectional RMI over the internet, without having to worry about firewalls, HTTP proxies, or NAT routers. Since the RMI connections are multiplexed, setup time for new connections is minimal and the bandwidth sharing of the Multiplexer guarantees smoother operation than plain RMI. Using the Multiplexed RMI Socket Factories you can:

• look up and reference remote objects on the RMI server
• export remote interfaces from the client to the server, and let the server call methods of these interfaces
• replace complicated stateless web service oriented protocols with RMI, even when faced with firewalls, NAT routers and proxies

Port Forwarding Utility

The Tunnel Library contains a port forwarding utility which can be used to tunnel any TCP based applications, such as SSH, database connections, etc. In combination with the HTTP tunnel using the https protocol, it is an easy way to tunnel arbitrary TCP connections securely over HTTP.

Licensing

To use a TunnelServer from the Tunnel Library you need a License Key. There are two different kinds of License Keys, described below. For the full text of the license to which you are bound if you choose to purchase a License Key and use the software, see the license. If none of the License Keys below meet your requirements please contact insight@sebster.com, and we can discuss a custom licensing scheme.

Single Server License Key

A Single Server License Key grants the licensee the right to run as many TunnelServer instances as desired on one computer.

Site License Key

A Site License Key grants the licensee the right to run as many TunnelServer instances as desired at a single site.

Trial License Key

If you want to try out the software, do not hesitate to contact us at insight@sebster.com. We can provide you with a trial License Key, and help to get you up and running quickly.

Upgrades

When you purchase a License Key for a specific Tunnel Library version, it will also grant you the right to free upgrades to any higher version with the same revision number. In other words, if you purchase a License Key for version 2.0.4, it will allow free upgrades to 2.0.5, 2.0.6, ..., 2.0.12, etc. For other upgrades, of a minor version number or more (e.g., 2.0.4 to 2.2.1), a special Upgrade License Key will be made available at a discounted price.