How to Prevent the SSH Broken Pipe Error

How to Prevent SSH Broken Pipe Error in Linux

Struggling with the “Broken Pipe” error while managing SSH on Linux?

A “Broken Pipe” error can be frustrating, considering it cannot be easily identified. If proper measures aren’t promptly taken, the issue has a tendency to resurface frequently,

In this guide, we will explore the “Broken Pipe” error and take steps to prevent it so that we can maintain a stable and secure connection, whether managing a single server or an entire network.

Let’s dive right in!

What Is a Broken Pipe Error?

The “Broken Pipe” error in SSH can be noticed when the communication between the client and server is disrupted. Unfortunately, this error doesn’t occur due to a fixed reason. Hence it isn’t easy to pin down the exact cause.

However, the most likely cause for this error is when the server closes the connection due to inactivity or a network issue that interrupts the connection.

In other words, the “Broken Pipe” error occurs when one side of the communication channel sends data to the other side that has already closed the connection.

Common Causes for the Broken Pipe Error

Although, as we mentioned in the previous section, the cause of the “Broken Pipe” error cannot be identified instantly, it can be narrowed down by considering the following common scenarios:

  • If the SSH connection remains idle for a certain period that exceeds the server’s configured timeout
  • If the remote server is rebooted or shut down while an SSH connection is active
  • Unstable or poor network connections can cause the SSH connection to drop
  • Strict firewall rules or security software may terminate the connection unexpectedly
  • If the client’s network configuration or hardware has issues.
  • When the SSH server reaches a maximum number of simultaneous connections
  • When the keep-alive settings between the client and server are not properly configured or mismatched

What You’ll Need to Know

Before we explain how to manage the SSH files, it is important to understand the following metrics, as you will use them to modify the SSH files to prevent the “Broken Pipe” error:

  • ClientAliveInterval: This metric represents the time interval, measured in seconds, that the server will wait before sending a “null” data packet to the connected client to verify the availability. The server sends these null data packets regularly and ensures the connection remains active. 
  • ServerAliveInterval: ServerAliveInterval is the client-side equivalent of ClientAliveInterval, a server-side configuration (also measured in seconds) that determines if the client is still responsive. This metric specifies how frequently the client will transmit empty packets to the server to maintain the connection.
  • ClientAliveCountMax: This metric determines the number of cycles or checks that the server will tolerate an unresponsive client before interrupting the connection. If the client fails to respond to the server’s null data packets several times, the server will conclude that the connection is broken and proceed to terminate it.
  • ServerAliveCountMax: ServerAliveCountMax is the client-side equivalent of ClientAliveCountMax, which defines the number of times the client will send a keep-alive message to the server without receiving a response before terminating the connection.

Now that you have an understanding of each of the metrics, we will proceed to the steps to modify the SSH files of the client and server using these metrics in order to prevent the SSH “Broken Pipe” error.

Let’s begin.

How to Prevent SSH Broken Pipe Error in Linux: 2 Steps

Step 1: Modify Client Side SSH Configuration File

Here are the steps to modify the client-side SSH configuration file using the “ServerAliveInterval” metric:

  1. To maintain a stable connection even when there’s no activity, keep an SSH connection alive with up to 10 minutes (600 seconds) of idle time.
  2. For this to happen, specify the ServerAliveInterval value using the command below to set the keep-alive interval to 600 seconds:
ssh -o ServerAliveInterval=600 username@server_ip_address
  1. Once done, you might notice that it has to be done every time the device reboots or any major changes have occurred. To avoid this inconsistency, modify the SSH configuration file on the client side by creating a new one using the following command:
touch ~/.ssh/config 
  1. After creating the SSH config file, provide proper permissions using the below command to avoid permission-denied errors: 
chmod 600 ~/.ssh/config
  1. If you’re not interested in manually setting the “ServerAliveInterval” value to all SSH connections, use the following command to apply the same interval for all connections:
echo "ServerAliveInterval 600" >> ~/.ssh/config
  1. (Optional) Although using the echo command is efficient, if you prefer a more organized and specific configuration, then you can add the setting under a particular host using the following command:
Host *
ServerAliveInterval 600

This is everything you will need to modify on the client side. Take note to ensure to enter the commands right, as none generate an output. Hence making any mistake is untraceable until the final point of execution. 

Also read: How to Enable and Disable Firewall on Alpine Linux

Step 2: Modify Server Side SSH Configuration File

Here are the steps to modify the server-side SSH configuration file located at “/etc/ssh/sshd_config” using the ClientAliveInterval and the ClientAliveCountMax metrics.

  1. Start by opening the SSH config file on any terminal-based editor you choose. Here is the command to open the file on the Nano editor:
sudo nano /etc/ssh/sshd_config
  1. Now set the ClientAliveInterval and the ClientAliveCountMax metrics per your needs (as shown in the screenshot below):
How to Prevent the SSH Broken Pipe Error

Note: If you set “ClientAliveInterval 60”, the server will check in with the client every minute (1 minute = 60 seconds) to keep the connection alive. On the other hand, if you set “ClientAliveCountMax 3”, the server will give the client three chances to respond before cutting off the connection.

  1. After editing the SSH config file, you can save your changes and exit by pressing CTRL + X, Y, and Enter key.


Congratulations on successfully preventing the SSH Broken Pipe error! 

The approach described in this article is arguably the most efficient and easiest one to implement. While this is easy, there is room for wastage of resources, and to prevent that from happening, do not set SSH connection timeout to several hours.

If you find this approach difficult, check out tools like “screen” or “tmux” to keep sessions active, even during connection interruptions.

Related Posts