wdctl

Display the watchdog status

$ wdctl

$ wdctl [[-O|--oneline]]

$ wdctl [[-f|--flags]] [flag_list]

wdctl [OPTIONS] COMMAND [ARGUMENTS]

-d, --dev-file
    Specifies the watchdog device file, e.g., /dev/watchdog. Overrides the default or configuration file setting.

-p, --pid-file
    Specifies the PID file used by the watchdog daemon. Useful if watchdogd is running with a non-standard PID file.

-c, --config-file
    Specifies an alternative configuration file for watchdogd. Note that wdctl itself uses this to connect, not to configure watchdogd directly.

-f, --force
    Forces the execution of certain commands, overriding safety checks.

-n, --no-action
    Prints what action would be performed without actually executing it. Useful for dry runs.

-v, --verbose
    Enables verbose output, providing more detailed information about the command's execution.

-h, --help
    Displays a short help message and exits.

-V, --version
    Displays the version information for wdctl and exits.

status
    Queries and displays the current status of the watchdog daemon, including its health, timeout, and last ping time.

settimeout
    Sets the watchdog timeout to the specified number of seconds. The watchdog daemon will reset the system if it does not receive a ping within this period.

ping
    Sends a 'keep-alive' ping to the watchdog daemon, instructing it to refresh its internal timer for the hardware watchdog.

gettimeout
    Retrieves and displays the currently configured watchdog timeout value in seconds.

getbootavg
    Displays the system load average when the system last booted. Requires watchdogd to be configured to capture this.

gettemp
    Retrieves and displays the current CPU temperature if watchdogd is configured to monitor it.

gettempwarn
    Displays the temperature warning threshold configured for the watchdog daemon.

gettempradio
    Displays the temperature shutdown (reboot) threshold configured for the watchdog daemon.

settempwarn
    Sets the temperature warning threshold to temp degrees Celsius. The watchdog daemon may log warnings if this is exceeded.

settempradio
    Sets the temperature shutdown (reboot) threshold to temp degrees Celsius. The system will reboot if this temperature is exceeded.

wdctl is a command-line utility used to interact with the Linux watchdog daemon, watchdogd. A watchdog timer is a hardware or software timer used to detect and recover from computer malfunctions. If the system stops responding, the watchdog timer will automatically reboot the system, preventing extended downtime.

wdctl allows system administrators to query the current status of the watchdog timer, set its timeout period, or perform other control operations. It can check if the watchdog daemon is alive, verify its configured timeout, and even read sensor data like CPU temperature if configured in watchdogd. This tool is crucial for monitoring the health and ensuring the reliability of critical systems where uninterrupted operation is paramount. It communicates with watchdogd via its control interface, typically through a Unix domain socket.

wdctl requires the watchdogd daemon to be running and accessible, usually with root privileges. It interacts with watchdogd via an IPC mechanism (Unix domain socket or shared memory), not directly with the hardware watchdog device. Incorrectly configuring or using watchdog timers can lead to unintended system reboots.

The Linux kernel exposes hardware watchdog timers through a character device, typically /dev/watchdog. watchdogd opens and "pings" this device periodically to prevent a system reboot. If watchdogd fails to ping the device within the configured timeout, the hardware timer will expire, and the system will automatically reboot.

Many wdctl commands, particularly those that modify settings (e.g., settimeout) or query sensitive information (e.g., temperature), require root privileges to execute successfully, as they interact with system-level processes and hardware interfaces.

The concept of a watchdog timer dates back to early computing to ensure system reliability by automatically recovering from malfunctions. In Linux, the watchdogd daemon implements this functionality, primarily interacting with hardware watchdog timers. wdctl was developed as a complementary utility to provide a simple command-line interface for querying and controlling the running watchdogd instance, making it easier for administrators to monitor and manage system resilience. Its development has closely tracked that of watchdogd, focusing on providing accessible control over its features.

watchdogd(8), watchdog(4), sysctl(8)