Fix SSH Sessions That Keep Freezing or Locking Up

SSH sessions that freeze or lock up are a common annoyance, especially over unstable networks or when a connection sits idle for a while. This guide walks you through the most effective fixes, from client-side keepalive settings to server-side timeouts and network-level tweaks. You’ll learn how to diagnose the cause and apply the right solution so your remote sessions stay responsive.

What You’ll Need

• Access to your SSH client configuration file (usually ~/.ssh/config on Linux/macOS, or C:\Users\\.ssh\config on Windows).
• Sudo or root access on the SSH server to edit /etc/ssh/sshd_config.
• Ability to restart the SSH service (e.g., sudo systemctl restart sshd or sudo service ssh restart).
• Basic familiarity with a terminal and editing files (vi, nano, or any text editor).

Step-by-Step

1. Add Client-Side Keepalive Messages

The most common cause of SSH freezes is that the connection silently drops due to NAT timeouts or idle timeouts. The client can send periodic keepalive packets to keep the connection alive. Edit your ~/.ssh/config file (create it if it doesn’t exist) and add these lines:

Host *
    ServerAliveInterval 30
    ServerAliveCountMax 3

ServerAliveInterval sends a keepalive every 30 seconds. ServerAliveCountMax means that if 3 consecutive keepalives are unanswered (90 seconds), the client will terminate the session instead of hanging forever. You can adjust the interval to your needs—lower for flaky connections, higher for stable ones.

2. Enable Server-Side Keepalive (if you control the server)

On the SSH server, edit /etc/ssh/sshd_config and add or uncomment these lines:

ClientAliveInterval 30
ClientAliveCountMax 3

This makes the server send keepalive messages to the client. After 30 seconds of inactivity, it sends a message; if 3 are unanswered, the server drops the connection. This prevents zombie sessions from piling up.

After editing, restart the SSH service:

sudo systemctl restart sshd

3. Use a Faster Cipher or Compression (for slow links)

If your network is slow or has high latency, the default encryption might be overkill. You can try a faster cipher and enable compression in your client config:

Host *
    Ciphers aes128-ctr,aes192-ctr,aes256-ctr
    Compression yes

This can reduce the amount of data transmitted and speed up the session, reducing the chance of timeouts.

4. Disable DNS Lookups on the Server

Sometimes the server tries to do a reverse DNS lookup on the client’s IP, which can hang if the DNS server is slow. In /etc/ssh/sshd_config, ensure this line is set:

UseDNS no

This prevents the server from doing a reverse lookup, which can cause delays or freezes during connection establishment.

5. Set a Keepalive in Your Terminal Emulator (if using PuTTY)

If you’re using PuTTY on Windows, go to Connection in the left sidebar, and under “Sending of null packets to keep session alive,” set the seconds between keepalives to, for example, 30. This works similarly to the client config above.

6. Use a VPN or Mosh for Extremely Unstable Networks

If your network is extremely flaky (e.g., satellite, mobile hotspot), consider using Mosh (Mobile Shell) instead of raw SSH. Mosh is designed to handle roaming and intermittent connectivity gracefully. It runs over UDP and doesn’t freeze when the network drops; it just waits and reconnects when the network returns.

7. Check for Firewall or NAT Timeouts

If you’re behind a NAT or firewall that drops idle connections, you can also adjust the TCP keepalive on your OS. On Linux, you can set the system-wide TCP keepalive time:

sudo sysctl -w net.ipv4.tcp_keepalive_time=60
sudo sysctl -w net.ipv4.tcp_keepalive_intvl=10
sudo sysctl -w net.ipv4.tcp_keepalive_probes=3

This sends TCP-level keepalives every 60 seconds, which can prevent NAT timeouts even before SSH’s keepalive kicks in. To make it permanent, add those lines to /etc/sysctl.conf.

Common Mistakes

• Setting only the client keepalive but not the server – If the server has a shorter timeout than your client’s keepalive interval, the server may still drop the connection. Ensure both sides are configured appropriately.
• Using too aggressive keepalive intervals – Setting ServerAliveInterval to 1 second can cause unnecessary overhead and may even trigger rate-limiting on some networks. 30 seconds is usually fine.
• Forgetting to restart the SSH server – After editing sshd_config, you must restart the service, otherwise the changes don’t take effect.
• Editing the wrong config file – On the client, the config file is ~/.ssh/config, not /etc/ssh/ssh_config (system-wide). Make sure you’re editing the right one.

Tips

• Test with verbose output – Run ssh -vvv user@host to see detailed debug output. This can help you see where the connection is hanging.
• Use ControlMaster – If you open multiple SSH sessions to the same host, you can reuse a single connection. Add these lines to your client config:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

This speeds up new connections and reduces the number of idle sessions.

• Consider using a screen or tmux – Even with keepalives, if the network drops, your session will still die. Running your work inside tmux or screen on the server means you can reconnect and resume exactly where you left off.

Troubleshooting

If you’ve applied the above and still have freezes, try these steps:

1. Check the SSH logs – On the server, look at /var/log/auth.log or /var/log/secure for any errors around the time of the freeze. Look for messages like “Timeout, client not responding” or “Connection reset by peer”.
2. Test with a different client – Try connecting from a different machine or with a different client (e.g., PuTTY instead of OpenSSH) to isolate if the issue is client-specific.
3. Check network stability – Run a continuous ping to the server (ping -t host on Windows, ping host on Linux) and see if packets are dropped during the freeze. If you see packet loss, the issue is the network, not SSH.
4. Try a different port – Sometimes ISPs or firewalls throttle or interfere with port 22. Try running SSH on port 443 or 2222 (if allowed) to see if the freezes stop.
5. Disable IPv6 – If your server has IPv6 enabled but the network is misconfigured, SSH might try IPv6 first and hang. Force IPv4 with ssh -4 user@host or add AddressFamily inet to your client config.

Frequently Asked Questions

Why does my SSH session freeze after a few minutes of inactivity?

Most likely a NAT or firewall on your network is dropping idle connections. The server or client doesn’t send any data during idle time, so the connection is considered dead. Setting keepalive messages (as described in Step 1 and 2) solves this by sending periodic packets.

What’s the difference between ServerAliveInterval and ClientAliveInterval?

ServerAliveInterval is set on the client and sends keepalive messages to the server. ClientAliveInterval is set on the server and sends keepalive messages to the client. They serve the same purpose but from opposite ends. You can use either, but using both is more robust.

Can I set keepalive only for specific hosts?

Yes. Instead of Host *, use a specific host pattern, e.g., Host myserver or Host 192.168.1.*. This allows you to have different settings for different servers.

Will keepalive messages slow down my SSH session?

No. The keepalive message is a small packet (a few bytes) sent every 30 seconds, which is negligible. It won’t affect the performance of your actual data transfer.

My session still freezes even with keepalive set. What else can I do?

If you’ve set keepalives on both client and server and still have freezes, the issue might be a very unstable network or a middlebox that drops even keepalive packets. Try using Mosh, or consider using a VPN that maintains a persistent connection.

Is it safe to disable DNS lookups on the server?

Yes, setting UseDNS no is safe and recommended for most setups. It only affects reverse DNS lookups, which are rarely needed. It can also speed up connection establishment.

Related

• How to Use How-To Geek’s Holiday Gift Guide
• Should You Buy AI Prompts? What to Know First
• Essential Work From Home Gadgets for a Better Setup