Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
WATCHDOGD(8)		  BSD System Manager's Manual		  WATCHDOGD(8)

     watchdogd -- watchdog daemon

     watchdogd [-dnSw] [--debug] [--softtimeout] [--softtimeout-action action]
	       [--pretimeout timeout] [--pretimeout-action action] [-e cmd]
	       [-I file] [-s sleep] [-t	timeout] [-T script_timeout]
	       [-x exit_timeout]

     The watchdogd utility interfaces with the kernel's	watchdog facility to
     ensure that the system is in a working state.  If watchdogd is unable to
     interface with the	kernel over a specific timeout,	the kernel will	take
     actions to	assist in debugging or restarting the computer.

     If	-e cmd is specified, watchdogd will attempt to execute this command
     with system(3), and only if the command returns with a zero exit code
     will the watchdog be reset.  If -e	cmd is not specified, the daemon will
     perform a trivial file system check instead.

     The -n argument 'dry-run' will cause watchdog not to arm the system
     watchdog and instead only run the watchdog	function and report on fail-
     ures.  This is useful for developing new watchdogd	scripts	as the system
     will not reboot if	there are problems with	the script.

     The -s sleep argument can be used to control the sleep period between
     each execution of the check and defaults to 10 seconds.

     The -t timeout specifies the desired timeout period in seconds.  The de-
     fault timeout is 128 seconds.

     One possible circumstance which will cause	a watchdog timeout is an in-
     terrupt storm.  If	this occurs, watchdogd will no longer execute and thus
     the kernel's watchdog routines will take action after a configurable

     The -T script_timeout specifies the threshold (in seconds)	at which the
     watchdogd will complain that its script has run for too long.  If unset
     script_timeout defaults to	the value specified by the -s sleep option.

     The -x exit_timeout argument is the timeout period	(in seconds) to	leave
     in	effect when the	program	exits.	Using -x with a	non-zero value pro-
     tects against lockup during a reboot by triggering	a hardware reset if
     the software reboot doesn't complete before the given timeout expires.

     Upon receiving the	SIGTERM	or SIGINT signals, watchdogd will terminate,
     after first instructing the kernel	to either disable the timeout or reset
     it	to the value given by -x exit_timeout.

     The watchdogd utility recognizes the following runtime options:

     -I	file			     Write the process ID of the watchdogd
				     utility in	the specified file.

     -d	--debug			     Do	not fork.  When	this option is speci-
				     fied, watchdogd will not fork into	the
				     background	at startup.

     -S				     Do	not send a message to the system log-
				     ger when the watchdog command takes
				     longer than expected to execute.  The de-
				     fault behaviour is	to log a warning via
				     the system	logger with the	LOG_DAEMON fa-
				     cility, and to output a warning to	stan-
				     dard error.

     -w				     Complain when the watchdog	script takes
				     too long.	This flag will cause watchdogd
				     to	complain when the amount of time to
				     execute the watchdog script exceeds the
				     threshold of 'sleep' option.

     --pretimeout timeout	     Set a "pretimeout"	watchdog.  At "time-
				     out" seconds before the watchdog will
				     fire attempt an action.  The action is
				     set by the	--pretimeout-action flag.  The
				     default is	just to	log a message
				     (WD_SOFT_LOG) via log(9).

     --pretimeout-action action	     Set the timeout action for	the pretime-
				     out.  See the section Timeout Actions.

     --softtimeout		     Instead of	arming the various hardware
				     watchdogs,	only use a basic software
				     watchdog.	The default action is just to
				     log(9) a message (WD_SOFT_LOG).

     --softtimeout-action action     Set the timeout action for	the softtime-
				     out.  See the section Timeout Actions.

Timeout	Actions
     The following timeout actions are available via the --pretimeout-action
     and --softtimeout-action flags:

     panic   Call panic(9) when	the timeout is reached.

     ddb     Enter the kernel debugger via kdb_enter(9)	when the timeout is

     log     Log a message using log(9)	when the timeout is reached.

     printf  call the kernel printf(9) to display a message to the console and
	     dmesg(8) buffer.

     Actions can be combined in	a comma	separated list as so: log,printf which
     would both	printf(9) and log(9) which will	send messages both to dmesg(8)
     and the kernel log(4) device for syslogd(8).


   Debugging watchdogd and/or your watchdog script.
     This is a useful recipe for debugging watchdogd and your watchdog script.

     (Note that	^C works oddly because watchdogd calls system(3) so the	first
     ^C	will terminate the "sleep" command.)

     Explanation of options used:
	   1.	Set Debug on (--debug)
	   2.	Set the	watchdog to trip at 30 seconds.	(-t 30)
	   3.	Use of a softtimeout:
		      3.1.   Use a softtimeout (do not arm the hardware	watch-
			     dog).  (--softtimeout)
		      3.2.   Set the softtimeout action	to do both kernel
			     printf(9) and log(9) when it trips.  (--softtime-
			     out-action	log,printf)
	   4.	Use of a pre-timeout:
		      4.1.   Set a pre-timeout of 15 seconds (this will	later
			     trigger a panic/dump).  (--pretimeout 15)
		      4.2.   Set the action to also kernel printf(9) and
			     log(9) when it trips.  (--pretimeout-action
	   5.	Use of a script:
		      5.1.   Run "sleep	60" as a shell command that acts as
			     the watchdog (-e 'sleep 60')
		      5.2.   Warn us when the script takes longer than 1 sec-
			     ond to run	(-w)

     watchdogd --debug -t 30 \
       --softtimeout --softtimeout-action log,printf \
       --pretimeout 15 --pretimeout-action log,printf \
       -e 'sleep 60' -w

   Production use of example
	   1.	Set hard timeout to 120	seconds	(-t 120)
	   2.	Set a panic to happen at 60 seconds (to	trigger	a crash(8) for
		dump analysis):
		      2.1.   Use of pre-timeout	(--pretimeout 60)
		      2.2.   Specify pre-timeout action	(--pretimeout-action
			     log,printf,panic )
	   3.	Use of a script:
		      3.1.   Run your script (-e '/path/to/your/script 60')
		      3.2.   Log if your script	takes a	longer than 15 seconds
			     to	run time. (-w -T 15)

     watchdogd	-t 120 \
       --pretimeout 60 --pretimeout-action log,printf,panic \
       -e '/path/to/your/script	60' -w -T 15

     watchdog(4), watchdog(8), watchdog(9)

     The watchdogd utility appeared in FreeBSD 5.1.

     The watchdogd utility and manual page were	written	by Sean	Kelly
     <> and Poul-Henning Kamp <>.

     Some contributions	made by	Jeff Roberson <>.

     The pretimeout and	softtimeout action system was added by Alfred
     Perlstein <>.

BSD				 May 11, 2015				   BSD


Want to link to this manual page? Use this URL:

home | help