autossh

Start an SSH session, restarting when the [M]onitoring port fails to return data

$ autossh -M [monitor_port] "[ssh_command]"

$ autossh -M [monitor_port] -L [local_port]:localhost:[remote_port] [user]@[host]

$ autossh -f -M [monitor_port] -N "[ssh_command]"

$ autossh -f -M 0 -N -o "ServerAliveInterval 10" -o "ServerAliveCountMax 3" "[ssh_command]"

$ autossh -f -M 0 -N -o "ServerAliveInterval 10" -o "ServerAliveCountMax 3" -o ExitOnForwardFailure=yes -L [local_port]:localhost:[remote_port] [user]@[host]

$ AUTOSSH_DEBUG=1 AUTOSSH_LOGFILE=[path/to/autossh_log_file.log] autossh -f -M [monitor_port] -v -E [path/to/ssh_log_file.log] [ssh_command]

autossh [options] [--] [ssh_options] [user@]host [command]

-M port[:count]
    Specifies a port for the monitoring connection. If set to 0, no monitoring port is used. If count is specified, autossh exits after count consecutive failures of the monitoring connection. The monitoring connection provides a more robust check for stalled tunnels beyond just the SSH process exit status.

-f
    Causes autossh to fork into the background before executing ssh. This is useful when running autossh as a service or from a startup script.

-N
    Instructs ssh not to execute a remote command. This option is passed directly to ssh and is commonly used when setting up port forwarding (e.g., -L, -R, -D) without an interactive shell.

-t
    Forces pseudo-terminal allocation on the remote system. Passed directly to ssh. Useful for interactive sessions or when a command requires a TTY.

-T
    Disables pseudo-terminal allocation. Passed directly to ssh.

ssh_options ...
    Any remaining arguments on the command line are passed directly to the ssh command that autossh executes. This allows the use of all standard ssh options like -L, -R, -D, -p, -l, -i, etc.

AUTOSSH_POLL
    An environment variable setting the interval (in seconds) between connection checks (default: 10 seconds). This applies to both monitoring port checks and process exit status checks.

AUTOSSH_GATETIME
    An environment variable setting the time (in seconds) that ssh must be successfully running before autossh considers the connection stable (default: 30 seconds). If ssh exits before this time, it's considered a fast failure.

AUTOSSH_MAXSTART
    An environment variable setting the maximum number of times ssh can be started before autossh gives up and exits (default: 0, which means never give up).

AUTOSSH_LOGLEVEL
    An environment variable setting the verbosity of autossh's logging (0=none, 1=default, 2=verbose, 3=debug).

AUTOSSH_PATH
    An environment variable to specify the full path to the ssh executable, if it's not in the system's PATH.

autossh is a utility designed to automatically monitor and restart an SSH session if it detects the connection has dropped or become unresponsive. It works by launching ssh and continuously checking its exit status or by using a dedicated monitoring port mechanism. If ssh exits with a non-zero status, or if the monitoring port mechanism fails to echo data, autossh will attempt to re-establish the connection. This functionality is invaluable for maintaining persistent SSH tunnels (e.g., local or remote port forwards), reverse SSH tunnels for NAT traversal, or long-running interactive SSH sessions over unreliable networks. It ensures that critical connections remain active and automatically recover from network glitches or server-side disconnects, providing a robust solution for continuous remote access and tunneling needs.

While autossh is excellent for maintaining SSH connections, it primarily monitors the SSH process and, with -M, the underlying TCP connection.
It may not detect issues within the application layer of an SSH tunnel (e.g., a stalled SOCKS proxy over -D) if the SSH connection itself remains active and the monitoring ports continue to echo. Users should also be mindful of security implications when keeping long-lived SSH tunnels open, especially for reverse SSH scenarios, and ensure appropriate firewall rules and SSH server configurations are in place.

When the -M option is used, autossh sets up two local listener ports (port and port + 1) and forwards them to corresponding remote ports on the SSH server. autossh then periodically sends data to the local 'monitor' port, which is forwarded to the remote 'monitor' port. The remote 'monitor' port immediately echoes the data back to the remote 'reply' port, which is then forwarded back to the local 'reply' port. If the data sent is not echoed back to the local 'reply' port within a set timeout, autossh concludes the connection is stalled or broken and restarts the ssh process. This mechanism provides a robust way to detect connection health even if the ssh process itself hasn't exited.

autossh is widely used for several critical scenarios:
Persistent SSH Tunnels: It is ideal for maintaining long-lived local or remote port forwards (e.g., ssh -L 8080:localhost:80 or ssh -R 2222:localhost:22), ensuring continuous access to services behind a firewall.
Reverse SSH for NAT Traversal: It's commonly employed to establish a persistent reverse tunnel from a machine behind a NAT or firewall to a publicly accessible server, thereby enabling remote access to the NAT'd machine.
Reliable Remote Sessions: While screen or tmux are often preferred for direct interactive use, autossh can ensure a base SSH connection remains stable for automated scripts or long-running background tasks.

autossh was created by Jeremy Baum to address the common problem of SSH connections dropping due to network instability or inactivity timeouts. Before its existence, users often resorted to simple shell scripts (like `while true; do ssh ...; done`) to try and keep connections alive, which were far less robust and lacked sophisticated monitoring capabilities. autossh significantly improved the reliability of persistent SSH tunnels and remote access, gaining widespread adoption as a standard tool for this purpose since its initial public releases around the early 2000s.

ssh(1), sshd(8), screen(1), tmux(1), systemd(1)