1.\" $OpenBSD: watchdog.4,v 1.11 2009/05/21 16:07:25 mk Exp $ 2.\" 3.\" Copyright (c) 2004-2006 Michael Knudsen <mk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd October 9, 2009 18.Dt WATCHDOG 4 19.Os 20.Sh NAME 21.Nm watchdog 22.Nd hardware timers/counters for quick crash recovery 23.Sh DESCRIPTION 24Hardware watchdog timers are devices that reboot the machine when it 25hangs. 26The kernel continually resets the watchdog clock on a regular basis. 27Thus, if the kernel halts, the clock will time out and reset the machine. 28Watchdog timers may be configured to be reset from userland 29to cause a reboot if process scheduling fails; 30see 31.Xr watchdogd 8 32for further information. 33.Pp 34A number of hardware watchdogs are supported, and all are configured 35using 36.Xr sysctl 8 37under the 38.Va kern.watchdog 39name: 40.Bl -tag -width kern.watchdog.period -offset indent 41.It Va kern.watchdog.auto 42Automatically reset 43.Pq Sq tickle 44the watchdog timer but disable it at system shutdown time. 45.It Va kern.watchdog.period 46The timeout in seconds. 47Setting it to zero disables the watchdog timer. 48.El 49.Pp 50In situations where the machine provides vital services which are not 51handled completely in kernel space, e.g. mail exchange, it may be 52desirable to reboot the machine if process scheduling fails. 53This is done by setting 54.Va kern.watchdog.auto 55to zero and running a process which repeatedly sets 56.Va kern.watchdog.period 57to the desired timeout value. 58Then, if process scheduling fails, the process resetting the timer will 59not be run, leading to the machine being rebooted. 60Note that the kernel will not automatically disable an enabled watchdog at 61system shutdown time when 62.Va kern.watchdog.auto 63is set to zero. 64.Pp 65Watchdog timers should be used in high-availability environments where 66getting machines up and running quickly after a crash is more important 67than determining the cause of the crash. 68A watchdog timer enables a crashed machine to autonomously attempt to 69recover quickly after a system failure. 70.Pp 71Note that this also means that it is unwise to combine watchdog timers 72with 73.Xr ddb 4 74since the latter may prevent the former from resetting the 75watchdog timeout before it expires. 76This means that the machine will be rebooted before any debugging 77can be done. 78In other words: For mission critical machines, disable 79.Xr ddb 4 80by adding 81.Cd options DDB_UNATTENDED 82to the kernel configuration file 83since this will give the chance to perform a crash dump and reboot. 84Simply setting the watchdog will lose the debug trace of what went 85wrong. 86.Sh SEE ALSO 87.Xr ddb 4 , 88.Xr sysctl.conf 5 , 89.Xr sysctl 8 , 90.Xr watchdogd 8 91.Sh BUGS 92For systems with multiple watchdog timers available, only a single 93one can be used at a time. 94There is currently no way of selecting which device is used; the first 95discovered by the kernel is selected. 96