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 March 5, 2013 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.Sh DESCRIPTION 50The 51.Nm 52utility interfaces with the kernel's watchdog facility to ensure 53that the system is in a working state. 54If 55.Nm 56is unable to interface with the kernel over a specific timeout, 57the kernel will take actions to assist in debugging or restarting the computer. 58.Pp 59If 60.Fl e Ar cmd 61is specified, 62.Nm 63will attempt to execute this command with 64.Xr system 3 , 65and only if the command returns with a zero exit code will the 66watchdog be reset. 67If 68.Fl e Ar cmd 69is not specified, the daemon will perform a trivial file system 70check instead. 71.Pp 72The 73.Fl n 74argument 'dry-run' will cause watchdog not to arm the system watchdog and 75instead only run the watchdog function and report on failures. 76This is useful for developing new watchdogd scripts as the system will not 77reboot if there are problems with the script. 78.Pp 79The 80.Fl s Ar sleep 81argument can be used to control the sleep period between each execution 82of the check and defaults to one second. 83.Pp 84The 85.Fl t Ar timeout 86specifies the desired timeout period in seconds. 87The default timeout is 16 seconds. 88.Pp 89One possible circumstance which will cause a watchdog timeout is an interrupt 90storm. 91If this occurs, 92.Nm 93will no longer execute and thus the kernel's watchdog routines will take 94action after a configurable timeout. 95.Pp 96The 97.Fl T Ar script_timeout 98specifies the threshold (in seconds) at which the watchdogd will complain 99that its script has run for too long. 100If unset 101.Ar script_timeout 102defaults to the value specified by the 103.Fl s Ar sleep 104option. 105.Pp 106Upon receiving the 107.Dv SIGTERM 108or 109.Dv SIGINT 110signals, 111.Nm 112will first instruct the kernel to no longer perform watchdog checks and then 113will terminate. 114.Pp 115The 116.Nm 117utility recognizes the following runtime options: 118.Bl -tag -width ".Fl -softtimeout-action Ar action " 119.It Fl I Ar file 120Write the process ID of the 121.Nm 122utility in the specified file. 123.It Fl d Fl -debug 124Do not fork. 125When this option is specified, 126.Nm 127will not fork into the background at startup. 128.Pp 129.It Fl S 130Do not send a message to the system logger when the watchdog command takes 131longer than expected to execute. 132The default behaviour is to log a warning via the system logger with the 133LOG_DAEMON facility, and to output a warning to standard error. 134.Pp 135.It Fl w 136Complain when the watchdog script takes too long. 137This flag will cause watchdogd to complain when the amount of time to 138execute the watchdog script exceeds the threshold of 'sleep' option. 139.Pp 140.It Fl -pretimeout Ar timeout 141Set a "pretimeout" watchdog. 142At "timeout" seconds before the watchdog will fire attempt an action. 143The action is set by the --pretimeout-action flag. 144The default is just to log a message (WD_SOFT_LOG) via 145.Xr log 9 . 146.Pp 147.It Fl -pretimeout-action Ar action 148Set the timeout action for the pretimeout. 149See the section 150.Sx Timeout Actions . 151.Pp 152.It Fl -softtimeout 153Instead of arming the various hardware watchdogs, only use a basic software 154watchdog. 155The default action is just to 156.Xr log 9 157a message (WD_SOFT_LOG). 158.Pp 159.It Fl -softtimeout-action Ar action 160Set the timeout action for the softtimeout. 161See the section 162.Sx Timeout Actions . 163.Pp 164.El 165.Sh Timeout Actions 166The following timeout actions are available via the 167.Fl -pretimeout-action 168and 169.Fl -softtimeout-action 170flags: 171.Bl -tag -width ".Ar printf " 172.It Ar panic 173Call 174.Xr panic 9 175when the timeout is reached. 176.Pp 177.It Ar ddb 178Enter the kernel debugger via 179.Xr kdb_enter 9 180when the timeout is reached. 181.Pp 182.It Ar log 183Log a message using 184.Xr log 9 185when the timeout is reached. 186.Pp 187.It Ar printf 188call the kernel 189.Xr printf 9 190to display a message to the console and 191.Xr dmesg 8 192buffer. 193.Pp 194.El 195Actions can be combined in a comma separated list as so: 196.Ar log,printf 197which would both 198.Xr printf 9 199and 200.Xr log 9 201which will send messages both to 202.Xr dmesg 8 203and the kernel 204.Xr log 4 205device for 206.Xr syslog 8 . 207.Sh FILES 208.Bl -tag -width ".Pa /var/run/watchdogd.pid" -compact 209.It Pa /var/run/watchdogd.pid 210.El 211.Sh SEE ALSO 212.Xr watchdog 4 , 213.Xr watchdog 8 , 214.Xr watchdog 9 215.Sh HISTORY 216The 217.Nm 218utility appeared in 219.Fx 5.1 . 220.Sh AUTHORS 221.An -nosplit 222The 223.Nm 224utility and manual page were written by 225.An Sean Kelly Aq smkelly@FreeBSD.org 226and 227.An Poul-Henning Kamp Aq phk@FreeBSD.org . 228.Pp 229Some contributions made by 230.An Jeff Roberson Aq jeff@FreeBSD.org . 231.Pp 232The pretimeout and softtimeout action system was added by 233.An Alfred Perlstein Aq alfred@freebsd.org . 234