Ninjas are deadly. Chipmunk Ninjas are just weird.
About this blog
Marc Travels
Marc on Twitter
JustLooking on Twitter

Marc Wandschneider is a professional software developer with well over fifteen years of industry experience (yes, he really is that old). He travels the globe working on interesting projects and gives talks at conferences and trade shows whenever possible.

My Publications:

My book, "Core Web Application Programming with PHP and MySQL" is now available everywhere, including

My "PHP and MySQL LiveLessons" DVD Series has just been published by Prentice-Hall, and can be purchased on Amazon, through Informit, or Safari

Jan 08, 2008 | 21:36:33
Announcing TunnelerX 0.9.5 - An SSH Tunnel for your Mac OS X menu bar
By marcwan

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
ssh -N -D 8123:localhost

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.



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.


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.


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/ In the command window, type:


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”.


  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.


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,” 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,” if it is not already there.


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


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!

ssh with password
Posted By: Wallynear Feb 06, 2008 01:10:35
I think passing passwords to ssh is important enough.
You can easily do this with no need to show a terminal window: the 'expect' CLI utility is perfect for this. It will do the magic for you, with little effort.

Feature Request
Posted By: Andrew Vit Apr 26, 2008 22:03:38
I would love to have something that is essentially like SSHKeychain, but without the keychain part since Leopard handles that now. TunnelerX isn't very useful to me since it can't do more than one tunnel at a time...
Posted By: Chris Apr 07, 2009 16:27:12
I just got a OSX and would like to connect to my ssh tunnel. Can anybody please send me an the ssh verbose command to do this in Terminal?

On Windows I use the fallowing command via plink:
"plink.exe" -v -ssh -l username -N -D 55855 -P 22

Thank You
Was there/is there a 1.0?
Posted By: Josh May 21, 2009 19:54:45
Was a 1.0 every created? I would love something that could manage multiple tunnels, since like another poster, I usually tunnel with different ports for different purposes.
Port #
Posted By: marcwan Aug 01, 2009 04:13:38
Ooops, I never implemented support for using an SSH port other than 22. I'll add it to the list.

I recently switched to VPN access here in China, so I don't use this program as much any more, but it looks like other people do, so I'll find a weekend to add some more features to it :)

Add a Comment





Copyright © 2005-2008 Marc Wandschneider All Rights Reserved.