org.mpr.util
Class TCPTunnel

java.lang.Object
  java.lang.Thread
      org.mpr.util.TCPTunnel

All Implemented Interfaces:

java.lang.Runnable

public class TCPTunnel
extends java.lang.Thread

Forwards TCP connections from a local port to a remote machine, optionally logging the passing traffic for observation. You can use TCPTunnel from your Java code, or as a command line tool. Possible uses include:

• debugging a conversation between a browser and a web server by examining the headers;
• mirroring a telnet session to a file so that many people can watch a delicate operation at the command line;
• logging the traffic for a particular service to scan for bugs or security breaches;
• opening an easily-configurable hole between network boundaries.

Here are a few examples to give you a feel for how it works:

• A simple HTTP tunnel:

  java org.mpr.util.TCPTunnel -m 31415 www.mpr.org 80

  This tells TCPTunnel to listen for connections on port 31415, and tunnel them to www.mpr.org, port 80. (31415 is just an arbitrary high port number that's probably not in use; 80 is the standard port for HTTP.) Point a browser at http://localhost:31415, and you'll see MPR's lovely home page. The -m option tells the tunnel to allow multiple simultaneous connections, which is a good idea if you're not logging traffic. Try the same command without -m, and see how much slower the images load.

• Watching a browser talk to a web server:

  java org.mpr.util.TCPTunnel -v -o out 31415 www.mpr.org 80

  Point a browser http://localhost:31415, and watch a whole mess o'HTTP scroll by! The -o out option tells TCPTunnel to log the network traffic in both directions to the console; -v enables verbose information on when connections open, how they're terminated, and other such good stuff.

  If that output is too much of a mess and you really only want to see the browser's requests, not the responses, try:

  java org.mpr.util.TCPTunnel -v -o http 31415 www.mpr.org 80 &
java org.mpr.util.StreamSplitter -f http_in.log out

  The first line logs the traffic to two files (the -o http option gives the name for the files), and the second line dumps the input log to the console as it grows. (The & on the first line is the UN*X-style of running the command in the background; substitute as appropriate for your OS.)

  Note that this trick won't always work perfectly -- as you'll see if you try these examples, your browser thinks the web server's hostname is "localhost:31415", and tells it so in the "Host" header. If the web server uses this header to differentiate multiple sites with the same IP, it will become confused.

• Mirroring a telnet session for your all buddies to watch:

  java org.mpr.util.TCPTunnel -o telnet_mirror -l 2 31415 some-machine 23 &
telnet localhost 31415

  Here we're using port 23 (telnet) instead of 80 (HTTP). The -l 2 option sets a very low read latency, which makes the tunnel more responsive to your keystrokes. (Be careful if you do this one -- your login password will end up in telnet_mirror_in.log in plaintext! You may want to delete that file after logging in.) Now anybody who wants to watch what you're doing can just follow along with the log:

  java org.mpr.util.StreamSplitter -l 1 -f telnet_mirror_out.log out

  That's good clean fun for the whole family!

You could easily modify this class to filter traffic, do TCP broadcasts, and other such insanity -- the source license allows modification, so go to it! And, if you're a good soul, share your cool mods with the world.

Maturity: This is mature code. It has worked very well in several different real-world settings. I have seen a connection-dangling problem when this class is used as an HTTP proxy; I'd like to track this down.

Plans: Though there are possibilities for interesting derived utilities (mentioned above), there are no current plans to expand or revise this class's functionality -- except to track down the connection dangling problem mentioned above. High-volume performance testing and tuning might be useful in the future.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

TCPTunnel(int localPort, java.lang.String remoteHost, int remotePort)
Creates a new TCP tunnel from the local machine to a remote one.

TCPTunnel(int localPort, java.lang.String remoteHost, int remotePort, java.io.OutputStream inTraffic, java.io.OutputStream outTraffic)
Creates a new TCP tunnel from the local machine to a remote one, splitting a copy of the network traffic to local streams for observation.

Method Summary

int	getBufferSize() Returns the maximum number of bytes the tunneler will hold in each internal buffer.
int	getLatency() Returns the time in milliseconds which this tunnel will sleep waiting for new input.
boolean	getMultiConnection() Allows or disallows multiple simultaneous connections.
boolean	getVerbose() Turns debugging output on and off.
static void	main(java.lang.String[] args) Command line handling
void	run() Begins forwarding connections.
void	setBufferSize(int bufferSize) Returns the maximum number of bytes the tunneler will hold in each internal buffer.
void	setLatency(int latency) Sets the time in milliseconds which this tunnel will sleep waiting for new input.
void	setMultiConnection(boolean multi) Allows or disallows multiple simultaneous connections.
void	setVerbose(boolean verbose) Turns debugging output on and off.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TCPTunnel

public TCPTunnel(int localPort,
                 java.lang.String remoteHost,
                 int remotePort)
          throws java.io.IOException

Creates a new TCP tunnel from the local machine to a remote one.

Parameters:

localPort - The local port to forward connections from.

remoteHost - The name or IP of the remote machine to forward connections to.

remotePort - The port on the remote machine to forward connections to.

Throws:

java.io.IOException

TCPTunnel

public TCPTunnel(int localPort,
                 java.lang.String remoteHost,
                 int remotePort,
                 java.io.OutputStream inTraffic,
                 java.io.OutputStream outTraffic)
          throws java.io.IOException

Creates a new TCP tunnel from the local machine to a remote one, splitting a copy of the network traffic to local streams for observation.

Parameters:

localPort - The local port to forward connections from.

remoteHost - The name or IP of the remote machine to forward connections to.

remotePort - The port on the remote machine to forward connections to.

inTraffic - Logs the traffic from local to remote.

outTraffic - Logs the traffic from remote to local.

Throws:

java.io.IOException

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Command line handling

Throws:

java.io.IOException

getVerbose

public boolean getVerbose()

Turns debugging output on and off. False by default.

setVerbose

public void setVerbose(boolean verbose)

Turns debugging output on and off. False by default.

getMultiConnection

public boolean getMultiConnection()

Allows or disallows multiple simultaneous connections. True by default.

setMultiConnection

public void setMultiConnection(boolean multi)

Allows or disallows multiple simultaneous connections. True by default. If this property is false, the tunnel forces connections to queue up single file, which makes for cleaner logs.

getBufferSize

public int getBufferSize()

Returns the maximum number of bytes the tunneler will hold in each internal buffer. The default buffer size is 32k.

setBufferSize

public void setBufferSize(int bufferSize)

Returns the maximum number of bytes the tunneler will hold in each internal buffer.

getLatency

public int getLatency()

Returns the time in milliseconds which this tunnel will sleep waiting for new input. The default latency is 30ms.

setLatency

public void setLatency(int latency)

Sets the time in milliseconds which this tunnel will sleep waiting for new input. A longer latency may speed things up if a lot of data is moving through the pipe, but may slow things down if the data is arriving slowly or in bursts.

run

public void run()

Begins forwarding connections. You can run this in the background by calling Thread.start(). This method will continue indefinitely until one of the following happens:

• An exception occurs binding to the local port, or opening a socket to the remote host/port. Note that this method will not terminate due to exceptions during traffic forwarding (such as the remote host closing the connection). The sorts of things that will terminate this method are the local port being in use, a DNS error on the remote host name, connection refused by remote, etc.
• The thread is interrupted.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread