TunnelerX is an application for Mac OS X to let you run a single SSH tunnel from your system menu bar, typically to securely re-route HTTP (web browsing) traffic to a remote proxy server. If you have ever had to run one of the following commands in a little Terminal window in the corner of your screen, then this application is for you:

ssh -N -L 8123:localhost:8123 bobo@theclown.com
ssh -N -D 8123:localhost bobo@theclown.com

Changes for 0.9.5:

• The application is now named TunnelerX instead of Tunneler
• A few bugs have been fixed related to sleeping and waking up the computer
• New graphics and icons for the application. It’s a bit less ghetto looking now.

For the 1.0 release (upcoming), I will add Growl notifications for those who wish them. The Growl website is currently down, so I can’t do much yet.

Downloading

• Download TunnelerX-0.9.5.dmg now (HTTP – San Diego, CA)

Introduction

Tunneling is useful for those stuck behind firewalls that block or otherwise prohibit visiting large numbers of sites on the Intarwebs, or perhaps watch your traffic a little too closely for comfort. Common scenarios are office environments or living in countries with national firewalls. This method of circumventing those restrictions has the following requirements:

• You have to have an SSH-accessible account on a server outside of your network somewhere, and you must be proficient enough with unix to set up password-less login for that remote account.
• That remote server must either be:
  • Running a full proxy server of some sort that allows access from localhost
  • Running a recent (in the last 2 years or so) version of SSH that supports the -D flag for SOCKS5 proxy support.
• You must have set up password-less login for your local machine to that remote machine.

I had originally thought of adding support for entering passwords in version 1.0, but it turns out that the ssh program works with ttys directly, and I really don’t want to go down that road, so I’ll stick with the requirement that you enable passwordless logins. If there is enough clamour, I’ll investigate other options.

TunnelerX is free software, and has the following system requirements:

• Mac OS X 10.4 (Tiger) or greater
• Enough RAM to boot your computer
• 1MB of disk space.

TunnelerX is a universal binary and has been tested on Intel and PowerPC macs running both Tiger and Leopard.

Using

After setting up and configuring TunnelerX, you will have a T item on your menu bar. After configuring the item, you just click “Connect” whenever you want to set up the proxy tunnel.

Please note that if you put your computer to sleep, the tunnel will be disconnected, and after waking up, TunnelerX will not reconnect the tunnel automatically (I hope to add this for version 1.0). Furthermore, it will disable itself for 30 seconds or so after the computer wakes up to wait for the networks to reconnect and re-establish themselves. Again, I hope to remove this as well in future versions.

Installation

Here’s how to get running with TunnelerX 0.9.5

1. Set up password-less login to your remote server
2. Download TunnelerX and install it to your /Applications or ~/Applications folder
3. [optional] Add TunnelerX to your startup programs in System Preferences
4. Launch TunnelerX, enter Preferences, and click “Connect”
5. Setup your browser to use the tunnel

More details follow now:

Set up password-less login to remote server

On the local machine, launch /Application/Utilities/Terminal.app. In the command window, type:

ssh user@remotehostname.com

If you are asked for a password, you have not set up password-less login. You can search for google for “passwordless login” or just use this link .

Download TunnelerX and install it to your /Applications or ~/Applications folder

Just use one of the download links from above and drag the icon from the .dmg file to either your /Applications or ~/Applications folder.

[optional] Add TunnelerX to your startup programs in System Preferences

You do this by launching System Preferences, going to “Accounts”, click on the “Login Items” tab, and then clicking the the + symbol below the list of login items. A dialog will show up asking you to select an application, and you should select the version of TunnelerX you saved to the hard disk – do not accidentally select the one in the disk image if that is still mounted.

Launch TunnelerX, enter Preferences, and click “Connect”

Startup TunnelerX manually now to get started with the application. You will see a T show up on your menu bar. Click on this T and select “Preferences”.

Enter:

1. Your user name (on the remote host, not the local machine)
2. The remote host name (or IP address—entering the IP saves a DNS lookup).
3. Select one of the two tunneling options. If you know for sure that your remote host has a proper proxy server, then you can select the first option. Otherwise, use the SSH SOCKS5 proxy by selecting the second option.
4. Finally, pick a port number to do the forwarding over. You need to remember this number for your browser configuration screens later.

Click Save to save the options, and then from the T menu in the System Menu Bar, select Connect.

Setup your browser to use the Tunnel

You will need to know two things before proceeding here:

1. Whether you chose to use a full proxy server or the built-in SSH SOCKS5 proxy.
2. The port number you chose to forward the tunnel over. We’ll call this PORTNUM.

Firefox

To configure Firefox, go to the Preferences dialog, choose “Advanced”, “Network”, and then “Settings…” to configure how Firefox connects to the Internet.

• “Manual proxy configuration:”
• If you chose a full remote proxy server:
  • HTTP Proxy: localhost, Port: PORTNUM
  • Click “Use this proxy server for all protocols”
  • For “No proxy for:”, you can fill in “localhost, 127.0.0.1” if it is not already there.
• If you are using the built-in SSH SOCKS5 proxy:
  • Leave HTTP proxy blank
  • UNcheck “Use this proxy server for all protocols”
  • Under “SOCKS Host:” enter localhost, PORTNUM
  • leave all other protocol thingies blank.
  • For “No proxy for:”, you can fill in “localhost, 127.0.0.1” if it is not already there.

Safari/Camino

Both of these browsers use the system preferences connection settings, so you need to configure them as follows:

• Launch System Preferences
• Click on “Network”
• Choose and double click on the network interface over which you wish to route your traffic (note that if you want to configure this for both your wireless internet and your ethernet cable-based connections, you will have to repeat these instructions for each interface.
• Click on “Proxies”
• If you chose a full remote proxy server:
  • Click on the checkbox next to “Web Proxy (HTTP”)
  • For “Web Proxy Server”, enter localhost:PORTNUM
• If you are using the built-in SSH SOCKS5 proxy:
  • Click on the checkbox next to “SOCKS Proxy”
  • For “Socks Proxy Server” enter localhost:PORTNUM
• Click “Apply Now”

Other Notes

Traffic

If you (or the friend you are bumming the SSH connection from) pays for bandwidth on the remote SSH server, be aware that routing all of your web traffic over that connection is going to result in a spike in their traffic usage – every thing you download will count as double its actual size against any traffic limits (once to download the file to the server, and another to send it back to you over the SSH tunnel). Please be aware of your traffic consumption.

Bug Reports, Feature Requests

Please feel free to send any comments or questions my way to marcwan at this domain.

Happy browsing!