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