Tunneler 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
Downloading
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 will add support for entering passwords in version 1.0 of Tunneler, but it’s so easy to set up password-less login that I figured I’d release 0.9 for now without that feature.
Tunneler 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.
Using
After setting up and configuring Tunneler, 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, Tunneler 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.
In this 0.9 version, Tunneler will on occasion get a little confused if you connect and disconnect and sleep and wake up your computer a few too many times. Clicking on Disconnect in the menu and then re-connecting will fix this most of the time. Worst case, click on the Kill all Tunnels... menu item, and restart the app. I will clean all this up for the 1.0 release.
Installation
Here’s how to get running with Tunneler 0.9
- Set up password-less login to your remote server
- Download Tunneler and install it to your /Applications or ~/Applications folder
- [optional] Add Tunneler to your startup programs in System Preferences
- Launch Tunneler, enter Preferences, and click “Connect”
- 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 Tunneler 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 Tunneler 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 Tunneler you saved to the hard disk – do not accidentally select the one in the disk image if that is still mounted.
Launch Tunneler, enter Preferences, and click “Connect”
Startup Tunneler 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:
- Your user name (on the remote host, not the local machine)
- The remote host name (or IP address—entering the IP saves a DNS lookup).
- 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.
- 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:
- Whether you chose to use a full proxy server or the built-in SSH SOCKS5 proxy.
- 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.
If you have any artistic skills whatsoever and a little free time to spare, I would dearly appreciate a new icon for this program. You’ll get credits and the gratitude of anybody who previously had to look at the abomination of an icon that I am currently using !!!
Happy browsing!
