First release: Apr 8, 2001
Last modified: Oct 1, 2006
English | Japanese

Heartbeat/Watchdog Patch for OpenSSH

Description

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.

Legal notice : This patch does NOT contain any cryptographic codes.

      See Previous codes for other versions.


(1) Heartbeat function

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 N
in 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 180
or 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.


(2) Watchdog function

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 N
in 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 N
This 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...

Compiling patched OpenSSH

(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.


Previous codes

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.

Legal notice : This patch does NOT contain any cryptographic codes.


Other SSH clients having a heartbeat (keepalive) function

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.

Here is a heartbeat patch for ssh-1.2.31, ssh-1.2.32, and ssh-1.2.33. This patch adds a new option ``Heartbeat N'' just as same as the patch for OpenSSH. You can use this patch freely. The author is not responsible for any damage caused by this patch. Legal notice : This patch does NOT contain any cryptographic codes.


Related sites


All Rights Reserved, Copyright (C) Hideaki Goto 2001-2005
http://www.sc.isc.tohoku.ac.jp/~hgot/sources/openssh-watchdog.html
Other programs
E-mail : hgot_@_rd.isc.tohoku.ac.jp
(remove underscores)