Monday, September 3, 2012

CorkScrew for tunnelling SSH over HTTP Proxies

At the client site, the firewall denies standard SSH traffic over Port 22 from the internal network to the outside. I decided to enable my Mac ssh-ing through the HTTP-proxy through Port 443. A useful utility is Corkscrew; a tunneling application which enables the Mac SSH command to use a proxy. To get Corkscrew working on your Mac, you could find a port and install it or you can download the source code and build it yourself as described here. I decided to install it via the MacPorts system.

Prior to installing MacPorts

  • First install XCode. I installed the latest XCode distribution (4.4.1) via the App Store 
  • Open up XCode, agree with the EULA. 
  • Install the XCode Command Line Tools. These need to be installed seperately by going to XCode Preferences > Downloads, find the Command Line Tools item and click on the install button.

Install MacPorts

  • Download the MacPorts MacOS Package installer.
  • Update MacPorts by running the following command in Terminal: sudo port selfupdate. For more optional checks, go to

Install and configure Corkscrew

  • In Terminal, run the following command: sudo port install corkscrew
  • Create an authentication credentials file (just a text file with your proxy username and password, to stop you having to type it each time you connect): ~/.ssh/proxy_credentials. It should contain just one line, like this: username:password
  • Next, in your ~/.ssh/config (create the file if it doesn’t already exist), add the following to make ssh use corkscrew by default for ssh connections (all one line): ProxyCommand corkscrew your.local.proxy port %h %p ~/.ssh/proxy_credentials

Optional config:

  • In your ~/.ssh/config, add the following at the top to let SSH just use Corkscrew for specific hosts: Host
  • With this config, I use "#" to switch Corkscrew on and off when needed:
Host *
ProxyCommand corkscrew your.local.proxy port %h %p ~/.ssh/proxy_credentials
#ProxyCommand none

That should be enough – you should now be able to connect to your remote server by typing:
ssh -p 443 you@your.ssh.server