First release: Apr 8, 2001
Last modified: Oct 1, 2006
English | Japanese
This patch adds (1) a heartbeat function to ssh, and adds (2) a watchdog function to sshd. This patch was originaly made to be used with Simple Authenticating Gateway. See each section for details.
This is a free patch for OpenSSH (portable versions). You can freely use, distribute or modify this patch, create a new patch based on this patch, or incorporate this patch into your codes, all without fee. This patch is provided ``AS IS''. The author is not responsible for any damage caused by this patch.
See Previous codes for other versions.
This patch adds a heartbeat (keepalive) function to ssh command. If the output channel has been silent for more than a specified time, a null message (SSH_MSG_IGNORE) is sent to the server as a heartbeat. Heartbeat is useful for keeping connections over IP masquerade / NAT boxes, firewalls, etc. The interval between heartbeats can be specified by
Heartbeat Nin the configuration file, where N denotes the interval in seconds. N=0 disables sending heartbeats. Although the interval between heartbeats is not very precise, it will be okay for many applications. If you experience undesirable disconnections behind an IP masquerade box or a NAT box,
Heartbeat 180or something may work.
Note: Heartbeat does not work if ServerAliveInterval (protocol version 2 only) is enabled at the same time.
There are some other SSH clients capable of emitting heartbeats (aka keepalives). Take a look at the bottom of this page.
There have been at least three patches for OpenSSH and I thank all of the authors for giving me good hints about the implementation.
This patch also adds a watchdog timeout function to sshd. The combination of the heartbeat and the watchdog timeout is very useful for detecting link down over unreliable connections such as wireless network.
If the input channel has been silent for more than the specified
time, sshd tries to kill the child process(es) as soon as
possible in order to protect server resources.
Since the heartbeats are sent over the encrypted channel
between the client and the server,
it's not easy to hijack the connection to keep
the user's processes running.
Unlike IdleTimeout supported by ssh.com SSH1,
this patch checks only incoming packets rather than
all packets. This makes it possible to terminate
user's login process even if the process continues
sending some data to the client.
The interval of timeout can be specified by
WatchdogTimeout Nin the configuration file, where N denotes the interval in seconds. N=0 disables the watchdog timeout function.
If you don't want to use the watchdog timeout for SSH2 protocol, the following option will be useful.
WatchdogTimeout1 NThis option turns on/off the watchdog timeout for SSH1 protocol only. This would be useful when you use ``ClientAliveInterval'' option at the same time.
Here's an example of the configuration pair for wireless gateways.
Heartbeat 5 # (in ssh_config) WatchdogTimeout1 20 # (in sshd_config) ClientAliveInterval 5 ClientAliveCountMax 4
Both ssh.com SSH and OpenSSH have KeepAlive (or TCPKeepAlive) option. However, this option doesn't help because it utilizes SO_KEEPALIVE of socket and the timeout is extremely long (at least 2hrs). Therefore, we need a watchdog...
(Be sure to use GNU tar.)
% tar zxpf openssh-X.Xp1-watchdog.patch.tgz % tar zxpf openssh-X.Xp1.tar.gz % cd openssh-X.Xp1 % patch < ../openssh-X.Xp1-watchdog.patch (Follow the instructions of OpenSSH.)X.X should be replaced with the version number of OpenSSH.
The codes for previous versions of OpenSSH are here only for references. You are strongly encouraged to use the newer OpenSSH, because the older versions may have security issues.
The following SSH clients have a heartbeat (aka keepalive) function. You can use them to connect to the OpenSSH server with the watchdog timeout enabled.