1.\" Copyright (c) 2013 iXsystems.com, 2.\" author: Alfred Perlstein <alfred@freebsd.org> 3.\" Copyright (c) 2004 Poul-Henning Kamp <phk@FreeBSD.org> 4.\" Copyright (c) 2003 Sean M. Kelly <smkelly@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd May 11, 2015 31.Dt WATCHDOGD 8 32.Os 33.Sh NAME 34.Nm watchdogd 35.Nd watchdog daemon 36.Sh SYNOPSIS 37.Nm 38.Op Fl dnSw 39.Op Fl -debug 40.Op Fl -softtimeout 41.Op Fl -softtimeout-action Ar action 42.Op Fl -pretimeout Ar timeout 43.Op Fl -pretimeout-action Ar action 44.Op Fl e Ar cmd 45.Op Fl I Ar file 46.Op Fl s Ar sleep 47.Op Fl t Ar timeout 48.Op Fl T Ar script_timeout 49.Op Fl x Ar exit_timeout 50.Sh DESCRIPTION 51The 52.Nm 53utility interfaces with the kernel's watchdog facility to ensure 54that the system is in a working state. 55If 56.Nm 57is unable to interface with the kernel over a specific timeout, 58the kernel will take actions to assist in debugging or restarting the computer. 59.Pp 60If 61.Fl e Ar cmd 62is specified, 63.Nm 64will attempt to execute this command with 65.Xr system 3 , 66and only if the command returns with a zero exit code will the 67watchdog be reset. 68If 69.Fl e Ar cmd 70is not specified, the daemon will perform a trivial file system 71check instead. 72.Pp 73The 74.Fl n 75argument 'dry-run' will cause watchdog not to arm the system watchdog and 76instead only run the watchdog function and report on failures. 77This is useful for developing new watchdogd scripts as the system will not 78reboot if there are problems with the script. 79.Pp 80The 81.Fl s Ar sleep 82argument can be used to control the sleep period between each execution 83of the check and defaults to 10 seconds. 84.Pp 85The 86.Fl t Ar timeout 87specifies the desired timeout period in seconds. 88The default timeout is 128 seconds. 89.Pp 90One possible circumstance which will cause a watchdog timeout is an interrupt 91storm. 92If this occurs, 93.Nm 94will no longer execute and thus the kernel's watchdog routines will take 95action after a configurable timeout. 96.Pp 97The 98.Fl T Ar script_timeout 99specifies the threshold (in seconds) at which the watchdogd will complain 100that its script has run for too long. 101If unset 102.Ar script_timeout 103defaults to the value specified by the 104.Fl s Ar sleep 105option. 106.Pp 107The 108.Fl x Ar exit_timeout 109argument is the timeout period (in seconds) to leave in effect when the 110program exits. 111Using 112.Fl x 113with a non-zero value protects against lockup during a reboot by 114triggering a hardware reset if the software reboot doesn't complete 115before the given timeout expires. 116.Pp 117Upon receiving the 118.Dv SIGTERM 119or 120.Dv SIGINT 121signals, 122.Nm 123will terminate, after first instructing the kernel to either disable the 124timeout or reset it to the value given by 125.Fl x Ar exit_timeout . 126.Pp 127The 128.Nm 129utility recognizes the following runtime options: 130.Bl -tag -width 30m 131.It Fl I Ar file 132Write the process ID of the 133.Nm 134utility in the specified file. 135.It Fl d Fl -debug 136Do not fork. 137When this option is specified, 138.Nm 139will not fork into the background at startup. 140.It Fl S 141Do not send a message to the system logger when the watchdog command takes 142longer than expected to execute. 143The default behaviour is to log a warning via the system logger with the 144LOG_DAEMON facility, and to output a warning to standard error. 145.It Fl w 146Complain when the watchdog script takes too long. 147This flag will cause watchdogd to complain when the amount of time to 148execute the watchdog script exceeds the threshold of 'sleep' option. 149.It Fl -pretimeout Ar timeout 150Set a "pretimeout" watchdog. 151At "timeout" seconds before the watchdog will fire attempt an action. 152The action is set by the --pretimeout-action flag. 153The default is just to log a message (WD_SOFT_LOG) via 154.Xr log 9 . 155.It Fl -pretimeout-action Ar action 156Set the timeout action for the pretimeout. 157See the section 158.Sx Timeout Actions . 159.It Fl -softtimeout 160Instead of arming the various hardware watchdogs, only use a basic software 161watchdog. 162The default action is just to 163.Xr log 9 164a message (WD_SOFT_LOG). 165.It Fl -softtimeout-action Ar action 166Set the timeout action for the softtimeout. 167See the section 168.Sx Timeout Actions . 169.El 170.Sh Timeout Actions 171The following timeout actions are available via the 172.Fl -pretimeout-action 173and 174.Fl -softtimeout-action 175flags: 176.Bl -tag -width ".Ar printf " 177.It Ar panic 178Call 179.Xr panic 9 180when the timeout is reached. 181.It Ar ddb 182Enter the kernel debugger via 183.Xr kdb_enter 9 184when the timeout is reached. 185.It Ar log 186Log a message using 187.Xr log 9 188when the timeout is reached. 189.It Ar printf 190call the kernel 191.Xr printf 9 192to display a message to the console and 193.Xr dmesg 8 194buffer. 195.El 196.Pp 197Actions can be combined in a comma separated list as so: 198.Ar log,printf 199which would both 200.Xr printf 9 201and 202.Xr log 9 203which will send messages both to 204.Xr dmesg 8 205and the kernel 206.Xr log 4 207device for 208.Xr syslog 8 . 209.Sh FILES 210.Bl -tag -width ".Pa /var/run/watchdogd.pid" -compact 211.It Pa /var/run/watchdogd.pid 212.El 213.Sh EXAMPLES 214.Ss Debugging watchdogd and/or your watchdog script. 215This is a useful recipe for debugging 216.Nm 217and your watchdog script. 218.Pp 219(Note that ^C works oddly because 220.Nm 221calls 222.Xr system 3 223so the 224first ^C will terminate the "sleep" command.) 225.Pp 226Explanation of options used: 227.Bl -enum -offset indent -compact 228.It 229Set Debug on (--debug) 230.It 231Set the watchdog to trip at 30 seconds. (-t 30) 232.It 233Use of a softtimeout: 234.Bl -enum -offset indent -compact -nested 235.It 236Use a softtimeout (do not arm the hardware watchdog). 237(--softtimeout) 238.It 239Set the softtimeout action to do both kernel 240.Xr printf 9 241and 242.Xr log 9 243when it trips. 244(--softtimeout-action log,printf) 245.El 246.It 247Use of a pre-timeout: 248.Bl -enum -offset indent -compact -nested 249.It 250Set a pre-timeout of 15 seconds (this will later trigger a panic/dump). 251(--pretimeout 15) 252.It 253Set the action to also kernel 254.Xr printf 9 255and 256.Xr log 9 257when it trips. 258(--pretimeout-action log,printf) 259.El 260.It 261Use of a script: 262.Bl -enum -offset indent -compact -nested 263.It 264Run "sleep 60" as a shell command that acts as the watchdog (-e 'sleep 60') 265.It 266Warn us when the script takes longer than 1 second to run (-w) 267.El 268.El 269.Bd -literal 270watchdogd --debug -t 30 \\ 271 --softtimeout --softtimeout-action log,printf \\ 272 --pretimeout 15 --pretimeout-action log,printf \\ 273 -e 'sleep 60' -w 274.Ed 275.Ss Production use of example 276.Bl -enum -offset indent -compact 277.It 278Set hard timeout to 120 seconds (-t 120) 279.It 280Set a panic to happen at 60 seconds (to trigger a 281.Xr crash 8 282for dump analysis): 283.Bl -enum -offset indent -compact -nested 284.It 285Use of pre-timeout (--pretimeout 60) 286.It 287Specify pre-timeout action (--pretimeout-action log,printf,panic ) 288.El 289.It 290Use of a script: 291.Bl -enum -offset indent -compact -nested 292.It 293Run your script (-e '/path/to/your/script 60') 294.It 295Log if your script takes a longer than 15 seconds to run time. (-w -T 15) 296.El 297.El 298.Bd -literal 299watchdogd -t 120 \\ 300 --pretimeout 60 --pretimeout-action log,printf,panic \\ 301 -e '/path/to/your/script 60' -w -T 15 302.Ed 303.Sh SEE ALSO 304.Xr watchdog 4 , 305.Xr watchdog 8 , 306.Xr watchdog 9 307.Sh HISTORY 308The 309.Nm 310utility appeared in 311.Fx 5.1 . 312.Sh AUTHORS 313.An -nosplit 314The 315.Nm 316utility and manual page were written by 317.An Sean Kelly Aq Mt smkelly@FreeBSD.org 318and 319.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . 320.Pp 321Some contributions made by 322.An Jeff Roberson Aq Mt jeff@FreeBSD.org . 323.Pp 324The pretimeout and softtimeout action system was added by 325.An Alfred Perlstein Aq Mt alfred@freebsd.org . 326