LinuxCommandLibrary

autossh

Maintain persistent SSH tunnels automatically

TLDR

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

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

Forward a [L]ocal port to a remote one, restarting when necessary
$ autossh -M [monitor_port] -L [local_port]:localhost:[remote_port] [user]@[host]
copy

Fork autossh into the background before executing SSH and do [N]ot open a remote shell
$ autossh -f -M [monitor_port] -N "[ssh_command]"
copy

Run in the background, with no monitoring port, and instead send SSH keep-alive packets every 10 seconds to detect failure
$ autossh -f -M 0 -N -o "ServerAliveInterval 10" -o "ServerAliveCountMax 3" "[ssh_command]"
copy

Run in the background, with no monitoring port and no remote shell, exiting if the port forward fails
$ autossh -f -M 0 -N -o "ServerAliveInterval 10" -o "ServerAliveCountMax 3" -o ExitOnForwardFailure=yes -L [local_port]:localhost:[remote_port] [user]@[host]
copy

Run in the background, logging autossh debug output and SSH verbose output to files
$ 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]
copy

SYNOPSIS

autossh [-V] [-M monitorport[:echoport]] [-f] [SSH options] [user@]host [command]

PARAMETERS

-V
    Print version information and exit

-M monitorport[:echoport]
    Enable monitoring via TCP connection to monitorport on server (local echo on echoport if specified; auto-generates if omitted). Use -M 0 to disable

-f
    Fork into background after starting SSH process

-o option=value
    Pass SSH configuration options (e.g., -o ServerAliveInterval=30)

DESCRIPTION

Autossh is a reliable wrapper for the SSH client that automatically restarts SSH sessions and tunnels if they fail due to network issues or server restarts. It detects connection drops using a monitoring mechanism, typically involving local and remote ports for echo testing, and re-establishes the connection transparently.

Key features include forking to background, customizable monitoring ports, and compatibility with all standard SSH options. This makes it ideal for persistent tasks like port forwarding, remote command execution, or maintaining tunnels for VPNs, backups, or monitoring services.

Without autossh, SSH connections often die silently on disruptions, requiring manual intervention. Autossh handles this by polling the connection health and reconnecting within seconds, configurable via environment variables for poll intervals, gate times, and max lifetime. It's widely used in scripts and production environments for robust remote access.

CAVEATS

Requires available ports for monitoring (avoid conflicts); initial connection delay possible; environment vars like AUTOSSH_GATETIME control behavior—set to 0 for no auto-reconnect; not suitable for interactive sessions without tweaks.

ENVIRONMENT VARIABLES

AUTOSSH_GATETIME=5: Seconds to wait for initial connection before monitoring (0 disables autossh).
AUTOSSH_MAXLIFE=0: Max seconds before forced exit (0=disabled).
AUTOSSH_POLL=10: Poll interval for monitoring (seconds).

EXIT CODES

0: Normal exit.
1: General error.
255: SSH exit code passed through.

HISTORY

Developed by Carson Harding in 2003-2006 as an enhancement to SSH for automatic reconnection. Inspired by unreliable long-running SSH tunnels; maintained on SourceForge with ports to major distros via packages like Debian's autossh.

SEE ALSO

ssh(1), scp(1), sftp(1)

Copied to clipboard