Troubleshooting Autossh/Ssh Failure Setting Tunnel with ExitOnForwardFailure

Autossh tunnels failing with ExitOnForwardFailure on public Wi-Fi usually stem from network instability or SSH configuration errors rather than a broken tunnel itself. Verify that your SSH daemon accepts the connection, ensure autossh is using the correct monitoring port, and check system logs for disconnection reasons to resolve the issue effectively.

Understanding ExitOnForwardFailure Behavior

The ExitOnForwardFailure option in OpenSSH is designed to terminate the client session if a requested port forwarding cannot be established. When combined with Autossh, this setting creates a strict environment where any interruption in the tunnel setup causes the process to exit immediately. This behavior is intentional and helpful for debugging because it prevents silent failures where a tunnel appears active but traffic is not flowing. However, on unstable networks like public Wi-Fi, this strictness can make the tunnel appear flaky if the initial handshake fails due to temporary connectivity issues. To understand why this happens, you must look at how Autossh manages its child processes. Autossh runs an SSH session and monitors it by sending periodic probes. If the underlying SSH connection drops, Autossh attempts to restart it. If ExitOnForwardFailure is set to yes, and the remote server refuses the port forward request during a restart attempt, the SSH client exits. Autossh then sees this exit and may restart, creating a loop of rapid connections and disconnections. This loop is often what users perceive as a "failure" to set up the tunnel, when in reality, the tunnel is being repeatedly destroyed and recreated.

Common Causes on Public Networks

Public Wi-Fi networks often employ captive portals, firewalls, or aggressive NAT timeouts that interfere with long-lived TCP connections. These intermediaries may drop idle connections or reset them unexpectedly. When Autossh tries to re-establish the tunnel after such a reset, the SSH handshake might fail momentarily, triggering ExitOnForwardFailure. Additionally, some public networks block non-standard ports or limit the number of concurrent connections per user, which can cause the initial port forwarding request to be rejected entirely. It is also important to consider authentication issues. If your SSH key has expired or the password prompt times out due to network latency, the SSH connection will fail. In these cases, ExitOnForwardFailure will trigger because the forward could not be established due to authentication failure. Checking whether you can manually connect via SSH without Autossh is the first step in isolating whether the issue is with the network or the configuration.

Diagnostic Steps for Stable Connections

Before adjusting complex configurations, perform basic diagnostics to ensure the foundation is solid. Start by testing the SSH connection manually from the command line. Use the verbose flag to see detailed output about what is happening during the connection attempt.

ssh -v -N -L 8080:localhost:80 user@remote_host

If this manual command succeeds, the SSH daemon and network path are functional. If it fails, note the error message. Common errors include "Connection refused," which indicates the remote service is down, or "Permission denied," which points to authentication problems. For more details on fixing authentication errors, you can refer to our guide on Fixing Permission denied with OpenSSH. Once manual SSH works, test the port forwarding specifically. Add the -f flag to background the process and keep it running while you test the local port. If the local port opens and stays open, the forwarding mechanism is working correctly. This confirms that ExitOnForwardFailure is not inherently broken, but rather reacting to external factors.

Configuring Autossh Correctly

Autossh requires careful configuration to handle network instability gracefully. The most common mistake is misconfiguring the monitoring port or the restart interval. Autossh uses a separate SSH connection to monitor the main tunnel. If this monitoring connection fails, Autossh assumes the main tunnel is dead and restarts it. Set the -M option to specify the monitoring port. This port should be a high-numbered, unused port on the local machine. For example:

autossh -M 50000 -N -L 8080:localhost:80 user@remote_host

Ensure that the monitoring port is not blocked by firewalls. Since it is a local port, it typically does not traverse the network, but some local security policies may restrict it. Additionally, adjust the -o options within the Autossh command to improve stability. Adding ServerAliveInterval 60 and ServerAliveCountMax 3 helps detect dead connections faster and reduces the chance of hanging sessions. For advanced users dealing with restrictive networks, establishing a reverse tunnel might be a more robust alternative. A reverse tunnel allows the remote host to initiate the connection, bypassing some inbound restrictions. Learn more about this approach in our article on VNC Connection to a Remote Host with Reverse SSH Tunnel.

Troubleshooting Specific Failure Scenarios

If the tunnel still fails after verifying the basics, examine the system logs. On Linux systems, use journalctl to view Autossh logs. Look for messages indicating why the SSH process exited. Common log entries include "channel 0: open failed" or "connect to host... Connection timed out." Another critical factor is the SSH configuration file (~/.ssh/config). Ensure that you are not overriding necessary settings globally. For instance, if you have StrictHostKeyChecking no set globally, it might interact poorly with ExitOnForwardFailure in certain edge cases. Review your config file for any conflicting directives. If you are behind a proxy, ensure that SSH is configured to use it correctly. Some proxies require specific headers or authentication methods that standard SSH does not support. In such cases, you may need to use tools like proxychains or configure SSH to use a SOCKS proxy. Refer to our guide on Bypass Restrictions with SSH for strategies on navigating restricted environments. Finally, consider the impact of MTU (Maximum Transmission Unit) issues. Large packets may be dropped by intermediate routers on public Wi-Fi, causing TCP resets. Try reducing the MTU size on your interface to see if stability improves. This is a less common but possible cause of intermittent tunnel failures.

Frequently Asked Questions

Why does my tunnel disconnect immediately after starting?

This usually happens because ExitOnForwardFailure is triggered by a failed port forward request. Check if the remote port is already in use or if the SSH daemon rejects the forwarding request. Verify the connection manually with ssh -v to see the exact error.

Can I disable ExitOnForwardFailure temporarily?

Yes, you can override it in your SSH command or config file by setting ExitOnForwardFailure no. This allows the tunnel to stay up even if port forwarding fails, but it means traffic will not flow through the tunnel. Use this only for debugging to isolate whether the issue is the forward or the connection itself.

How do I choose a safe monitoring port for Autossh?

Choose a port above 1024 that is not used by any other application on your local machine. Ports between 50000 and 60000 are generally safe for this purpose. Ensure that your local firewall allows outbound connections to this port, although since it is local, this is rarely an issue unless strict rules are in place.

What if the public Wi-Fi blocks SSH traffic?

Some public networks block port 22. You can try connecting over port 443 (HTTPS) if the remote SSH server is configured to listen on that port. Alternatively, use a tool like stunnel to wrap your SSH traffic in TLS, making it look like regular web traffic.

Does ExitOnForwardFailure work with dynamic port forwarding?

Yes, ExitOnForwardFailure applies to all types of port forwarding, including dynamic (-D), local (-L), and remote (-R). If the dynamic port binding fails, the SSH session will exit. This is useful for ensuring that your SOCKS proxy is actually operational before you start routing traffic through it.