Updated 2009-11-23 16:22:32 by dkf

WHAT IT IS (short version)

Burrow creates a persistent and resilient TCP/IP tunnel between two hosts over which other TCP services can be routed. It is written in Tcl (which makes socket programming so easy!) and distributed under an MIT/X11-style open source license.

WHERE TO GET IT

SEH 20080730 -- sourceforge project page: [1]

Burrow's home is: http://michael.cleverly.com/software/burrow/ (Not Found @ 2009-01-31)

Larry Smith: I've set up a mirror at http://www.smith-house.org:8000/burrow-1.0.1.tgz. (Connection failed @ 2009-01-31)

AvL: removed previous (un- and)availability-comments.
 Current state: server available, file is 26915 bytes, gunzip complains about "unexpected end of file".
 break off is after ChangeLog, which appears to be (short but) complete.

WHAT IT IS (long version)

As the Wiki page on tunnelling elaborates, other solutions exist. I wrote Burrow to solve a problem I encounter that other solutions are less equipped at dealing with: being behind a firewall which does NAT whose admins find it necessary to reboot said firewall repeatedly throughout the business day (which naturally kills all the connections in & out).

Burrow is resilient to this flakey network enviroment. As soon as the male Burrow ("Jack", who initiates the connection) detects that the tunneled connection has dropped, he immediately begins attempting to reconnect to the female Burrow ("Jenny").

Jack is configured to listen on a set of port(s) (possibly on different IP addresses). The data received on these sockets is forwarded across the tunnel to Jenny where an outgoing client socket is opened (for each client who connects to Jack), and, in effect, the pair of client sockets are "glued" together over the Burrowed tunnel. This can work in reverse too (see diagram below).

While the tunnel between Jack & Jenny is unavailable, each side queues up any data received from their respective clients. Once the shared tunnel is re-established the queued data is sent across & on to the corresponding outgoing client connection. So when our friendly firewall admins reboot, rather than losing all of our connections as we normally would, our burrowed connections simply appear to "freeze up" momentarily until Jack reconnects to Jenny, and then everything picks up right where it left off.

DIAGRAM OF HOW BURROW WORKS
   +------+                                                   +------+
   | sshd |\                                                 /| irc  |
   +------+ \  +-----------+                +------------+  / +------+
             \ |           |   __________   |            | /
   +------+   \|  Male     |  ( firewall )  | Female     |/   +------+
   | ssh  |----|  Burrow   >==(flakey ISP)==> Burrow     |----| sshd |
   +------+   /|  (JACK)   |  (_Internet_)  | (JENNY)    |\   +------+
             / |           |                |            | \
   +------+ /  +-----------+                +------------+  \ +------+
   | ircd |/                                                 \| ssh  |
   +------+                                                   +------+

CONFIGURATION FILE EXAMPLE

The configuration file format is a Tcl script which is sourced into a safe interpreter. Two commands commands are added: config & map. Config is used to set various Burrow settings. Map is used to define what services get mapped where. The basic format is:
      map mode jack direction jenny ?hosts.allowed?

For example, to implement the above:
    map plaintext 10.1.2.3.4:22   <= 192.168.150.42:22
    map plaintext 10.1.2.3.5:22   => 192.168.150.43:22
    map encrypted 10.1.2.3.4:6667 <= 192.168.150.42:6667

Connections can be mapped in one of three modes: plaintext, obfuscated (hex encoded), or encrypted (blowfish). In this example the irc connection from Jenny to Jack is encrypted, while the two SSH connections (one each way) are not--since SSH itself is already encrypted.

Enjoy. -- Michael A. Cleverly