How to use the command `autossh` (with examples)

autossh is a versatile tool designed to enhance the reliability and robustness of SSH connections. It automatically monitors and restarts SSH sessions, ensuring persistent communication even in unstable network environments. This feature is especially useful for scenarios involving port forwarding, where maintaining an uninterrupted connection is crucial. autossh accepts all SSH flags and adds functionality for monitoring and automatically reconnecting broken SSH sessions.

Use case 1: Start an SSH session, restarting when the monitoring port fails to return data

Code:

autossh -M monitor_port "ssh_command"

Motivation:

Maintaining a stable SSH connection is vital for secure remote operations, especially when operating over unreliable networks. This command ensures that should the connection fail, autossh will automatically attempt to restart it. This reliability is crucial for ongoing tasks that depend on consistent connection, such as remote monitoring or administration.

Explanation:

• -M monitor_port: This specifies the monitoring port. autossh checks the health of the SSH connection using this port. If it detects a failure, it restarts the session.
• "ssh_command": Represents the SSH command you want to execute. It can be any standard SSH command, such as connecting to a remote server.

Example Output:

Establishing SSH session to user@host...
Connection lost. Attempting to restart...
SSH session re-established.

Use case 2: Forward a local port to a remote one, restarting when necessary

Code:

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

Motivation:

Port forwarding is essential for redirecting local network traffic to a remote server securely through an SSH tunnel. In cases of unstable network connectivity, ensuring the SSH tunnel automatically restarts is vital to maintaining this forwarding, especially when it’s integral to application workflow or network security.

Explanation:

• -M monitor_port: Sets the port used by autossh to monitor the SSH connection’s status.
• -L local_port:localhost:remote_port: Specifies local forwarding. It maps local_port on the local machine to remote_port on the remote host. This configuration is useful for accessing resources on a remote server through a local port.
• user@host: Specifies the remote server and username to connect with.

Example Output:

Forwarding local port XXXXX to remote port YYYYY...
SSH tunnel active. Monitor active on port ZZZZZ.

Use case 3: Fork autossh into the background before executing SSH and do not open a remote shell

Code:

autossh -f -M monitor_port -N "ssh_command"

Motivation:

Running autossh in the background is advantageous for long-term tasks where maintaining a constant SSH session is crucial, but where interactive shell access to the remote server is unnecessary. This configuration is ideal for developing backend services or scripts that don’t require user interaction after startup.

Explanation:

• -f: Forks autossh into the background, allowing the SSH command to execute without blocking the terminal, enabling other tasks to continue concurrently.
• -M monitor_port: As before, indicates the port for monitoring the SSH connection.
• -N: Specifies that no remote shell should be opened—ideal for port forwarding or data transfer tasks.

Example Output:

autossh running in background with SSH session...
Monitor active, ready for any required restarts.

Use case 4: Run in the background, with no monitoring port, and instead send SSH keep-alive packets every 10 seconds to detect failure

Code:

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

Motivation:

In some environments, the overhead of a monitoring port may be undesirable. This use case allows autossh to detect disconnections through periodic keep-alive packets, ensuring SSH session stability without additional network resources.

Explanation:

• -f: Runs autossh in the background.
• -M 0: Disables monitoring via a specific port and opts to use SSH keep-alive packets instead.
• -N: Means no remote shell is necessary.
• -o "ServerAliveInterval 10": Sends keep-alive messages every 10 seconds.
• -o "ServerAliveCountMax 3": If 3 consecutive keep-alive messages fail, the connection is considered lost, prompting a restart.

Example Output:

Session maintained via keep-alive packets. Monitoring ensures reconnection upon failure.

Use case 5: Run in the background, with no monitoring port and no remote shell, exiting if the port forward fails

Code:

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

Motivation:

When security and reliability are key, it’s crucial to ensure that even port forwarding connections terminate if they cannot establish. This configuration alerts the user to network issues swiftly by terminating unresponsive forwarding attempts.

Explanation:

• -f: The command will execute in the background.
• -M 0: Defaults to using keep-alive packets instead of a monitoring port.
• -N: Specifies no shell is opened.
• -o "ServerAliveInterval 10" and -o "ServerAliveCountMax 3": Work together to maintain the connection through keep-alive checks.
• -o ExitOnForwardFailure=yes: Ensures that the SSH session will terminate if port forwarding cannot be established, preventing incomplete operations.
• -L local_port:localhost:remote_port: Configures local to remote port forwarding.

Example Output:

Port forwarding active. Connection terminated due to forwarding failure.

Use case 6: Run in the background, logging autossh debug output and SSH verbose output to files

Code:

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

Motivation:

For auditing and troubleshooting purposes, logging the details of SSH and autossh can provide insights into connection issues, retries, and system behavior. This is vital for system administrators and security professionals who need to maintain comprehensive records.

Explanation:

• AUTOSSH_DEBUG=1: Enables debug mode for detailed logging of autossh actions.
• AUTOSSH_LOGFILE=path/to/autossh_log_file.log: Specifies the file path to log autossh debug information.
• -f: Executes the process in the background.
• -M monitor_port: Indicates the monitoring port.
• -v: Activates verbose mode for SSH, providing detailed SSH operation logs.
• -E path/to/ssh_log_file.log: Directs SSH verbose logs to the specified file.

Example Output:

Debug logs: /path/to/autossh_log_file.log
SSH verbose logs: /path/to/ssh_log_file.log
Monitoring connection with detailed logs for diagnostics.

Conclusion:

The autossh command is a powerful and flexible tool for maintaining reliable SSH connections, especially in conditions where network reliability is unpredictable. By understanding and utilizing its diverse options, users can ensure persistent connectivity, robust data forwarding, and comprehensive logging, making it an invaluable tool for administrators and developers alike.