How to Inspect and Configure Hardware Watchdog Timers in Linux Using wdctl

In mission-critical servers, edge computing nodes, and embedded Linux deployments, hardware reliability and automated failure recovery are paramount. Hardware watchdog timers provide an autonomous fail-safe mechanism: an onboard microcontroller or motherboard chip expects the operating system to send periodic heartbeat signals (“petting the dog”). If the Linux kernel hangs, enters an unrecoverable kernel panic, or suffers a deadlocked driver thread, the heartbeat lapses, triggering the hardware watchdog to forcefully cycle power or reset the system without human intervention. The wdctl utility, included in the standard util-linux package, allows system administrators to inspect, audit, and configure active watchdog devices directly from the terminal.

Role of the Watchdog Subsystem and /dev/watchdog

The Linux kernel exposes hardware watchdog interfaces through device nodes, typically /dev/watchdog (or numbered instances such as /dev/watchdog0 and /dev/watchdog1). Dedicated watchdog daemons, as well as systemd’s integrated watchdog support (RuntimeWatchdogSec), periodically write heartbeat pulses to this device node.

The wdctl tool queries the kernel’s ioctl interface on the watchdog device to extract hardware driver identity, firmware options, timeout thresholds, and pretimeout warning support without interrupting ongoing heartbeats.

Auditing Active Watchdog Hardware with wdctl

To inspect the primary watchdog hardware on your Linux machine, execute wdctl with root or administrative privileges:

sudo wdctl

If a hardware or emulated watchdog device is present, wdctl returns structured hardware telemetry similar to the following:

Device:        /dev/watchdog0
Identity:      iTCO_wdt [version 0]
Timeout:       30 seconds
Timeleft:      18 seconds
FLAG           DESCRIPTION                   STATUS  BOOT-STATUS
KEEPALIVEPING  Keep alive ping reply              1            0
MAGICCLOSE     Allow close without rebooting      1            0
SETTIMEOUT     Set timeout (in seconds)           1            0

Key information displayed in this report includes:

• Device: The active character device path queried by the utility.
• Identity: The hardware driver module managing the physical watchdog chip (such as iTCO_wdt for Intel chipset controllers or sp5100_tco for AMD platforms).
• Timeout: The countdown duration (in seconds) before the watchdog fires a system reset if no heartbeat is received.
• Timeleft: The current remaining countdown time before the pending reset occurs.
• Status Flags: Hardware capabilities supported by the controller, such as MAGICCLOSE (allowing software to close the file handle without triggering an immediate reboot) and SETTIMEOUT (support for variable runtime timeouts).

Inspecting Specific Devices and Raw Output Formats

When multiple watchdog devices exist on multi-socket server motherboards or IPMI management cards, specify the target node explicitly:

sudo wdctl /dev/watchdog1

For automated shell scripts and infrastructure monitoring tools, format the output into clean key-value pairs or JSON using formatting flags:

sudo wdctl --noheadings --raw --output FLAG,STATUS

To verify if the system rebooted due to a watchdog reset during the previous power cycle, inspect the BOOT-STATUS column in the flag table. A non-zero flag under WDIOF_CARDRESET confirms that the last reboot was initiated directly by watchdog hardware intervention.

Configuring Watchdog Timeouts in systemd

Modern Linux distributions utilizing systemd provide integrated hardware watchdog supervisors. Rather than running a standalone third-party daemon, you can configure systemd to supervise both system health and hardware timers directly via /etc/systemd/system.conf.

Open the configuration file in an administrative editor:

sudo nano /etc/systemd/system.conf

Locate and uncomment the following directives to define your preferred timeout thresholds:

RuntimeWatchdogSec=20s
RebootWatchdogSec=5min
KExecWatchdogSec=5min

Save the file and reload systemd to apply the new timeout parameters:

sudo systemctl daemon-reload

Re-running sudo wdctl confirms that the active timeout period has been synchronised with the newly configured hardware interval, guaranteeing automated recovery from kernel hangs.