What is AutoSSH
Autossh is a program to start a copy of ssh and monitor it, restarting it as necessary should it die or stop passing traffic.
How to install AutoSSH on various systems via their package manager.
Debian / Ubuntu $ sudo apt-get install autossh
CentOS / Fedora / RHEL $ sudo yum install autossh
ArchLinux $ sudo pacman -S autossh
FreeBSD # pkg install autossh
cd /usr/ports/security/autossh/ && make install clean
OSX $ brew install autossh
Basic usage of Autossh
usage: autossh [-V] [-M monitor_port[:echo_port]] [-f] [SSH_OPTIONS]
-M for now.
-V simply displays the version and exits. The important part to remember is that
-f (run in background) is not passed to the
ssh command, but handled by
autossh itself. Apart from that you can then use it just like you would use ssh to create any forward or reverse tunnels.
Let’s take the basic example from part one of this article series (forwarding a remote MySQL port to my local machine on port 5000):
ssh -L 5000:localhost:3306 firstname.lastname@example.org
This can simply be turned into an autossh command:
autossh -L 5000:localhost:3306 email@example.com
This is basically it. Not much magic here.
Note 1: Before you use
autossh, make sure the connection works as expected by trying it with
Note 2: Make sure you use public/private key authentification instead of password-based authentification when you use
-f. This is required for
ssh as well as for
autossh, simply because in a background run a passphrase cannot be entered interactively.
-M (monitoring port)
-M AutoSSH will continuously send data back and forth through the pair of monitoring ports in order to keep track of an established connection. If no data is going through anymore, it will restart the connection. The specified monitoring and the port directly above (+1) must be free. The first one is used to send data and the one above to receive data on.
Unfortunately, this is not too handy, as it must be made sure both ports (the specified one and the one directly above) a free (not used). So in order to overcome this problem, there is a better solution:
ServerAliveCountMax – they cause the SSH client to send traffic through the encrypted link to the server. This will keep the connection alive when there is no other activity and also when it does not receive any alive data, it will tell AutoSSH that the connection is broken and AutoSSH will then restart the connection.
The AutoSSH man page also recommends the second solution:
In many ways this [ServerAliveInterval and ServerAliveCountMax options] may be a better solution than the monitoring port.
You can disable the built-in AutoSSH monitoring port by giving it a value of 0:
autossh -M 0
Additionally you will also have to specify values for
autossh -M 0 -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3"
So now the complete tunnel command will look like this:
autossh -M 0 -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -L 5000:localhost:3306 firstname.lastname@example.org
ServerAliveInterval: number of seconds that the client will wait before sending a null packet to the server (to keep the connection alive).
Sets the number of server alive messages which may be sent without ssh receiving any messages back from the server. If this threshold is reached while server alive messages are being sent, ssh will disconnect from the server, terminating the session.
In the previous article we were able to simplify the tunnel command via
~/.ssh/config. Luckily autossh is also aware of this file, so we can still keep our configuration there.
This was our very customized configuration for ssh tunnels which had custom ports and custom rsa keys:
$ vim ~/.ssh/config Host cli-mysql-tunnel HostName everythingcli.org User cytopia Port 1022 IdentityFile ~/.ssh/id_rsa-cytopia@everythingcli LocalForward 5000 localhost:3306
We can also add the
ServerAliveCountMax options to that file in order to make things even easier.
$ vim ~/.ssh/config Host cli-mysql-tunnel HostName everythingcli.org User cytopia Port 1022 IdentityFile ~/.ssh/id_rsa-cytopia@everythingcli LocalForward 5000 localhost:3306 ServerAliveInterval 30 ServerAliveCountMax 3
If you recall all the ssh options we had used already, we can now simply start the autossh tunnel like so:
autossh -M 0 -f -T -N cli-mysql-tunnel
AutoSSH environment variables
AutoSSH can also be controlled via a couple of environmental variables. Those are useful if you want to run AutoSSH unattended via
cron, using shell scripts or during boot time with the help of
systemd services. The most used variable is probably
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_GATETIME to 0 is most useful when running AutoSSH at boot time.
All other environmental variables including the once responsible for logging options can be found in the AutoSSH Readme.
AutoSSH during boot with systemd
If you want a permanent SSH tunnel already created during boot time, you will (nowadays) have to create a systemd service and enable it. There is however an important thing to note about systemd and AutoSSH:
-f (background usage) already implies
-f is not supported by systemd.
[…] running programs in the background using “&”, and other elements of shell syntax are not supported.
So in the case of
systemd we need to make use of
AUTOSSH_GATETIME. Let’s look at a very basic service:
$ vim /etc/systemd/system/autossh-mysql-tunnel.service [Unit] Description=AutoSSH tunnel service everythingcli MySQL on local port 5000 After=network.target [Service] Environment="AUTOSSH_GATETIME=0" ExecStart=/usr/bin/autossh -M 0 -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -NL 5000:localhost:3306 email@example.com -p 1022 [Install] WantedBy=multi-user.target
Tell systemd that we have added some stuff:
Start the service
systemctl start autossh-mysql-tunnel.service
Enable during boot time
systemctl enable autossh-mysql-tunnel.service
This is basically all I found useful about AutoSSH. If you thing I have missed some important parts or you know any other cool stuff, let me know and I will update this post.
Starting Autossh on startup
AutoSSH is a great tool to maintain a persistent SSH tunnel. Here is how to start AutoSSH on boot so that the tunnel can survive system reboot of the local machine.
Here we assume you can already ssh into the remote machine without typing the password.
First, on your local machine, switch to root user:
$ sudo su
Second, ssh into remote machine as root so the remote machine is added to your root’s known_hosts.
Third, add this line to your /etc/rc.local.
autossh -N -f -i /home/<user>/.ssh/id_rsa -R 22222:localhost:22 <user>@<remote_host>
The command arguments are:
- -N: tell ssh to not execute any command, since we only use it for tunneling.
- -f: tell autossh to fall into background on start.
- -i: tell ssh to use the proper identity.
- -R 22222:localhost:22: reverse tunnel remote host’s 22222 port to localhost’s 22 port. So that we can use ssh -p 22222 localhost on remote host to ssh into local machine.