Enabling a SOCKS proxy via SSH tunnel in Ubuntu or Mac OS X at startup

There are two ways to enable a SOCKS5 proxy at startup in Ubuntu. For either to work, you must have previously configured ssh public/private key authentication, so make sure that works and that you can do a “normal” ssh login without entering a password. Note that the second method described below is better because it is persistent – if the connection goes down, it will attempt to reconnect automatically.

Method 1 (Ubuntu and similar versions of Linux only):

I’ll briefly show the first method, but keep in mind that if the ssh connection is lost, it will not automatically reconnect.

First install screen from the standard repository if you have not done so already, and change the permissions of /run/screen to 775.

In Ubuntu’s Startup Applications Preferences, add this command, replacing the italicized parts with the correct values:

screen -dmS tunnel ssh username@server_address -D local_socks_proxy_port

tunnel” can be any word you like, “username” is your account name on the remote server, “server_address” is the address of the remote server, and “local_socks_proxy_port” is the port number your local software will use when connecting to the SOCKS proxy (7777 is a frequently-used choice).

Ubuntu Startup Applications Preferences - adding SOCKS proxy
Ubuntu Startup Applications Preferences – adding SOCKS proxy

Method 2:

Ubuntu users, first go into the Ubuntu Software Center and search for autossh (other Linux users, check your repository for the autossh package):

Ububtu Software Center - autossh

If you click “More Info” you can read the description:

Ubuntu Software Center - autossh - details

Go ahead and install it, and after installation it will show you which programs can be run:

Ubuntu Software Center - autossh - installed

Mac OS X users, there is an autossh package for recent versions of OS X among the Rudix packages. Be sure to select your version of OS X in the left-hand sidebar, then download the autossh package for your version of OS X and then click on the downloaded package to run the installer:

Rudix autossh installer

Click Continue and you will see an “Important Information” screen, the text of which is copied to the bottom of this article in case you want to review it. Note that you do NOT need to do the build procedure shown there; you just continue the installation as you would any other OS X software you have downloaded.

Rudix autossh Important Information screen

Whether you are installing in Linux or OS X, after you complete the installation the next thing to do is open a terminal window and run autossh manually one time. Remember, you must have previously configured ssh public/private key authentication for this to work. The reason for running autossh manually the first time is that a window will pop up asking you to approve the connection and accept the RSA key. So open a terminal window and run a line of this form:

Ubuntu: autossh -f -N username@server_address -D local_socks_proxy_port
Mac OS X: autossh -M 0 username@server_address -D local_socks_proxy_port

As in the first method, “username” is your account name on the remote server, “server_address” is the address of the remote server, and “local_socks_proxy_port” is the port number your local software will use when connecting to the SOCKS proxy (7777 is a frequently-used choice, but it can be any unused port numbered 1080 or above). If the popup appears asking you to approve the connection, answer “yes”, and that should be the last time you see that dialog (unless, perhaps, some drastic changes are made at the server).

Note that under OS X, we could not get the -f option to work, even though it’s supposed to. When we tried to use it, no ssh connection was opened (as determined by watching Activity Monitor). So, unfortunately, you will need to leave a terminal or iTerm window open with autossh running in it, unless you can figure out some way to make backgrounding it work. This was in OS X Lion; perhaps the -f option works in other versions. Feel free to experiment.

After running autossh from a terminal window, open your browser and make sure the SOCKS proxy works. How you configure it will vary by browser. For example, under Firefox you’d open the Preferences pane, select Advanced, click the Network tab, and then click the Settings button. In the window that opens you’d select Manual Proxy Configuration, then for SOCKS Host you can use localhost, and for Port the local_socks_proxy_port number you set when you started autossh. Select SOCKS v5 as the proxy type. In the “No Proxy for:” window, enter some sane values for your network — generally these will include your local machine and other addresses on your local network. For example (assuming your local network addresses are in the 192.168.x.x range):


In Google Chrome you can use an extension such as Proxy SwitchySharp to configure your proxy settings.

After saving those settings, go to a site that will show you the IP address that it thinks you are coming in from, such as http://ipchicken.com/ – make sure that the address it shows is that of the system you are using for your proxy, and not your local address.

Once you are sure it is working, in Ubuntu you can open Ubuntu’s Startup Applications Preferences and add the same line you typed in the terminal window.

Add autossh to Startup Applications

Under OS X it’s a little more complicated. If you use iTerm, you could create a Profile (similar to a bookmark) and for the command use the same command you used in the terminal window, but specify the full path to autossh, e.g.:

/usr/local/bin/autossh -M 0 username@server_address -D local_socks_proxy_port

iTerm profile setup for autossh

Name your profile something meaningful, and make sure that when you click on the profile in the sidebar to runs autossh and opens the connection. The use the AppleScript Editor to build a script that will start iTerm and open the profile. Your script could look something like this:

tell application "iTerm"
tell the current terminal
launch session "Profile_name"
delay 3
tell the last session
set name to "Profile_name - SOCKS proxy using autossh"
end tell
end tell
end tell

Creating iTerm launcher script in AppleScript Editor

Substitute the name you gave the profile for the two occurrences of Profile_name in the sample script. Compile the AppleScript and when it compiles with no errors, save it as an Application. Make sure it works as intended (starts up iTerm and loads the Profile that runs autossh), then simply set that application to run at startup (Under System Preferences | Users & Groups | (select current user) | Login Items).

Now your SOCKS5 proxy should start up each time you reboot your system, and if the tunnel goes down it should reconnect within a few minutes. To learn more about autossh, open a terminal window and type man autossh, or see any of these articles (note that some of them overly complicate the process of setting up the tunnel):

Permanent SSH Tunnels with autossh (Linuxaria)
Using SSH for IPv6-enabled HTTP Proxying (see comment below main article – The Daily Build)
SSH Socks proxy with Chromium 18 (krenel.org)
Autossh Startup Script for Multiple Tunnels (Surnia Ulula)

Here is the text from the “Important Information” screen in the Rudix autossh installer;

autossh Version 1.4

Building and Installing Autossh

With version 1.4, autossh now uses autoconf. So the build procedure
is now the well-known:

make install

Look at autossh.host for an example wrapper script.

autossh -M [:echo_port] [-f] [SSH OPTIONS]


autossh is a program to start a copy of ssh and monitor it, restarting
it as necessary should it die or stop passing traffic.

The original idea and the mechanism were from rstunnel (Reliable SSH
Tunnel). With version 1.2 the method changed: autossh now uses ssh to
construct a loop of ssh forwardings (one from local to remote, one
from remote to local), and then sends test data that it expects to get
back. (The idea is thanks to Terrence Martin.)

With version 1.3, a new method is added (thanks to Ron Yorston): a
port may be specified for a remote echo service that will echo back
the test data. This avoids the congestion and the aggravation of
making sure all the port numbers on the remote machine do not
collide. The loop-of -forwardings method remains available for
situations where using an echo service may not be possible.

autossh has only three arguments of its own:

-M [:echo_port], to specify the base monitoring port to use, or
alternatively, to specify the monitoring port and echo service
port to use.

When no echo service port is specified, this port and the port
immediately above it (port# + 1) should be something nothing
else is using. autossh will send test data on the base monitoring
port, and receive it back on the port above. For example, if you
specify "-M 20000", autossh will set up forwards so that it can
send data on port 20000 and receive it back on 20001.

Alternatively a port for a remote echo service may be
specified. This should be port 7 if you wish to use the
standard inetd echo service. When an echo port is specified,
only the specified monitor port is used, and it carries the
monitor message in both directions.

Many people disable the echo service, or even disable inetd,
so check that this service is available on the remote
machine. Some operating systems allow one to specify that the
service only listen on the localhost (loopback interface),
which would suffice for this use.

The echo service may also be something more complicated:
perhaps a daemon that monitors a group of ssh tunnels.

-M 0 will turn the monitoring off, and autossh will only
restart ssh on ssh exit.

For example, if you are using a recent version of OpenSSH, you
may wish to explore using the ServerAliveInterval and
ServerAliveCountMax options to have the SSH client exit if it
finds itself no longer connected to the server. In many ways
this may be a better solution than the monitoring port.

-f Causes autossh to drop to the background before running ssh. The
-f flag is stripped from arguments passed to ssh. Note that there
is a crucial a difference between the -f with autossh, and -f
with ssh: when used with autossh, ssh will be *unable* to ask for
passwords or passphrases. When -f is used, the "starting gate"
time (see AUTOSSH_GATETIME) will be set to 0.

-V to have autossh display its version and exit.

All other arguments are passed to ssh. There are a number of
other settings, but these are all controlled through environment
variables. ssh seems to be appropriating more and more letters for
options, and this seems the easiest way to avoid collisions.

autossh tries to distinguish the manner of death of the ssh process it
is monitoring and act appropriately. The rules are:

- If the ssh process exited normally (for example, someone typed
"exit" in an interactive session), autossh exits rather than
- If autossh itself receives a SIGTERM, SIGINT, or a SIGKILL
signal, it assumes that it was deliberately signalled, and exits
after killing the child ssh process;
- If autossh itself receives a SIGUSR1 signal, it will kill the child
ssh process and start a new one;
- Periodically (by default every 10 minutes), autossh attempts to pass
traffic on the monitor forwarded port. If this fails, autossh will
kill the child ssh process (if it is still running) and start a new
- If the child ssh process dies for any other reason, autossh will
attempt to start a new one.

Startup behaviour:

- If the ssh session fails with an exit status of 1 on the very first
try, autossh will assume that there is some problem with syntax or
the connection setup, and will exit rather than retrying;
- There is now a "starting gate" time. If the first ssh process fails
within the first few seconds of being started, autossh assumes that
it never made it "out of the starting gate", and exits. This is to handle
initial failed authentication, connection, etc. This time is 30 seconds
by default, and can be adjusted (see the AUTOSSH_GATETIME environment
variable below).
- NOTE: If AUTOSSH_GATETIME is set to 0, then BOTH of the above
behaviours are disabled. This is useful for, for example,
having autossh start on boot. The "starting gate" time is
also set to 0 with the -f flag to autossh is used.

Continued failures:

- If the ssh connection fails and attempts to restart it fail in
quick succession, autossh will start delaying its attempts to
restart, gradually backing farther and farther off up to a
maximum interval of the autossh poll time (usually 10 minutes).
autossh can be "prodded" to retry by signalling it, perhaps with
SIGHUP ("kill -HUP").

Connection Setup

As connections must be established unattended, the use of autossh
requires that some form of automatic authentication be set up. The use
of RSAAuthentication with ssh-agent is the recommended method. The
example wrapper script attempts to check if there is an agent running
for the current environment, and to start one if there isn't.

It cannot be stressed enough that you must make sure ssh works on its
own, that you can set up the session you want before you try to
run it under autossh.

If you are tunnelling and using an older version of ssh that does not
support the -N flag, you should upgrade (your version has security
flaws). If you can't upgrade, you may wish to do as rstunnel does, and
give ssh a command to run, such as "sleep 99999999999".

Disabling connection monitoring

A monitor port value of "0" ("autossh -M 0") will disable use of
the monitor ports; autossh will then only react to signals and the
death of the ssh process.

Environment Variables

The following environment variables can be set:

AUTOSSH_DEBUG - sets logging level to LOG_DEBUG, and if
the operating system supports it, sets
syslog to duplicate log entries to stderr.
AUTOSSH_FIRST_POLL - time to initial poll (default is as
AUTOSSH_GATETIME - how long ssh must be up before we consider
it a successful connection. Default is 30
seconds. If set to 0, then this behaviour
is disabled, and as well, autossh will retry
even on failure of first attempt to run ssh.
AUTOSSH_LOGFILE - sets autossh to use the named log file,
rather than syslog.
AUTOSSH_LOGLEVEL - log level, they correspond to the levels
used by syslog; so 0-7 with 7 being the
AUTOSSH_MAXLIFETIME - Sets the maximum number of seconds the process
should live for before killing off the ssh child
and exiting.
AUTOSSH_MAXSTART - specifies how many times ssh should be started.
A negative number means no limit on the number
of times ssh is started. The default value is -1.
AUTOSSH_MESSAGE - append a custom message to the echo string (max 64
AUTOSSH_NTSERVICE - when set to "yes" , setup autossh to run as an
NT service under cygrunsrv. This adds the -N flag
for ssh if not already set, sets the log output
to stdout, and changes the behaviour on ssh exit
so that it will restart even on a normal exit.
AUTOSSH_PATH - path to the ssh executable, in case
it is different than that compiled in.
AUTOSSH_PIDFILE - write autossh pid to specified file.
AUTOSSH_POLL - poll time in seconds; default is 600.
If the poll time is less than twice the
network timeouts (default 15 seconds) the
network timeouts will be adjusted downward
to 1/2 the poll time.
AUTOSSH_PORT - set monitor port. Mostly in case ssh
appropriates -M at some time. But because
of this possible use, AUTOSSH_PORT overrides
the -M flag.

Logging and Syslog

autossh logs to syslog using the LOG_USER facility. Your syslog may
have to be configured to accept messages for this facility. This is
usually done in /etc/syslog.conf.

Kudos and raspberries to harding [at] motd.ca

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Recent Posts

Recent Comments




GiottoPress by Enrique Chavez