Configuring ssh keepalives

If you find ssh connections from your computer or mobile device to a Maths ssh gateway or any other remote system terminate unexpectedly after a few minutes of inactivity, or if you receive a message similar to this example:

client_loop: send disconnect: Broken pipe

this may be caused by either your broadband modem/router or by an intermediate network between your Internet connection and the college through which your connection is routed. Some modem/routers will deliberately drop a connection at the TCP level after 2-3 minutes of inactivity with no network traffic passing through it to or from your computer - this can happen when you are busy reading a webpage that is already downloaded to your system, or you have a ssh connection open but you are not typing or receiving any data from the remote system. You can get around this problem by telling your ssh client software to send 'TCP keep-alive' packets at regular intervals even if you are not doing anything with the network or you have left your computer to go and make a coffee, for instance.

Linux, Mac and UNIX users can add the following option to their ssh command:

-o ServerAliveCountMax=1000 -o ServerAliveInterval=60

where the ServerAliveCountMax option is the maximum number of keepalive packets (in this case 1000) sent by your ssh client without the remote connection (the ssh server) sending back a response before your ssh client assumes the connection has been broken for some reason and disconnects anyway; the second option ServerAliveInterval sets the delay in seconds between the last packet being received from the remote ssh server and your client sending a keepalive packet to it. So if your existing ssh command looks something like this:


then after adding the two keep-alive options to the command it should now look like this:

ssh -o ServerAliveCountMax=1000 -o ServerAliveInterval=60

Typing this long-winded stanza every time you want to make a ssh connection soon loses its charm and you can instead save these options in your ~/.ssh/config file (if this file does not exist, just create it using your favourite text editor):

# Site-wide defaults for various options
Host *
ServerAliveCountMax 1000
ServerAliveInterval 60

If you are using the PuTTY ssh client for Windows, the default setting for 'Connection: seconds between keepalives' is 0 (= off) but you can change this in the PuTTY GUI - setting this to 60 seems to work well with the modem/routers supplied by popular broadband ISPs.

This page was originally written in 2015 for the benefit of users of VirginMedia's cable broadband service after Virgin introduced their Superhub 2 modem/router at that time and ssh disconnections became a real problem that was never addressed by VirginMedia; the later Superhub 3 (and the Hitron modem/routers supplied with VirginMedia business cable broadband connections) do not have these problems. However, this issue has recently resurfaced for some users on broadband connections outside the UK and while it is possible in some cases to reconfigure your modem/router through its web-based control panel to maintain the connection even when there is no network traffic, not all broadband routers have this option.

Andy Thomas

Research Computing Manager,
Department of Mathematics

last updated: 04.05.2020