Configuration Reference

Watchdog reads one YAML file. The file must contain a non-empty services array; every service name must be unique and use only letters, digits, dots, underscores, and hyphens, beginning with a letter or digit. The runtime validates the schema before it performs checks or remediation. 1

Command safety: write a command as an argument array. Do not place a shell pipeline, redirect, variable expansion, or compound command in one string and expect Watchdog to interpret it. Watchdog executes the array directly; it does not parse a shell command line. 1

Complete starting template

The example below is a compact baseline. Replace every placeholder, validate it using dry-run mode, and adapt the check-specific settings described in Check Types.

settings:
  log_file: /var/log/service-watchdog/service-watchdog.log
  lock_file: /run/lock/service-watchdog.lock
  state_directory: /var/lib/service-watchdog
  default_timeout: 10
  default_attempts: 2
  default_retry_delay: 2
  default_action_timeout: 120
  default_action_cooldown: 300

notifications:
  email:
    enabled: false

hooks:
  on_failure: []
  on_recovery: []

services:
  - name: public-api
    enabled: true
    check:
      type: http
      url: https://api.example.com/health
      timeout: 10
      attempts: 2
      retry_delay: 2
    actions:
      cooldown: 300
      verify_after: 5
      commands:
        - command: [systemctl, restart, example-api]
          timeout: 120

The shipped config.example.yaml contains a fuller configuration with HTTP, TCP, and command-check examples. 2

settings

settings supplies global paths and defaults. Its three paths must be absolute. Watchdog creates the relevant parent directories when it starts, then attempts to set the log file to mode 0640 and the state directory to mode 0750. 1

Key	Required	Default	Validation and effect
log_file	Yes	None	Absolute path to the operational log file.
lock_file	Yes	None	Absolute path to the file used by the global non-blocking lock.
state_directory	Yes	None	Absolute directory where per-service state and cooldown files are kept.
default_timeout	No	10	Positive integer seconds used by checks that do not define check.timeout.
default_attempts	No	2	Positive integer, maximum 10, used when check.attempts is absent.
default_retry_delay	No	2	Non-negative integer seconds between unsuccessful check attempts.
default_action_timeout	No	120	Positive integer seconds used by commands without their own timeout.
default_action_cooldown	No	300	Non-negative integer seconds between remediation attempts for the same service. 1

services[]

Each service is processed independently in configuration order. Set enabled: false to retain a service in the file while skipping it at runtime. 1

Key	Required	Default	Description
name	Yes	None	Unique identifier matching [A-Za-z0-9][A-Za-z0-9._-]*. It also becomes the state-file stem.
enabled	No	true	Boolean. Disabled services are logged as skipped and are not checked.
check	Yes	None	Map that defines an http, tcp, or command health check.
actions	No	No commands	Map that defines optional remediation, cooldown, and verification.

Common check fields

Every check type accepts the following controls. Type-specific fields are documented in Check Types. 1

Key	Required	Default	Rules
type	Yes	None	One of http, tcp, or command.
timeout	No	settings.default_timeout	Positive integer seconds.
attempts	No	settings.default_attempts	Positive integer.
retry_delay	No	settings.default_retry_delay	Non-negative integer seconds.

actions

actions.commands is an optional sequence. When no commands are configured, Watchdog reports the service as unavailable after a failed check but does not attempt remediation. With commands present, Watchdog respects cooldown, records an action attempt before executing the sequence, and can re-check the service after verify_after seconds. 1

Key	Required	Default	Rules
commands	No	Empty sequence	A sequence of direct command objects. An explicitly supplied empty sequence is valid.
cooldown	No	settings.default_action_cooldown	Non-negative integer seconds. Use 0 to permit remediation on every scheduled run.
verify_after	No	0	Non-negative integer seconds to wait before the verification check.

Each item in a command sequence has the following form. Commands run in order and the sequence stops at the first non-zero result. 1

commands:
  - command: [docker, compose, restart, api]
    working_directory: /srv/example-api
    timeout: 120

Command key	Required	Default	Rules
command	Yes	None	Non-empty YAML array. Each argument may be a scalar; use strings for clarity.
working_directory	No	/	Existing directory. Watchdog changes into it before execution.
timeout	No	settings.default_action_timeout	Positive integer seconds. The command is bounded with GNU timeout. 1

hooks

hooks is optional. It may contain on_failure and on_recovery, both using the same command-sequence shape as remediation. An empty array is valid. Hooks execute only on the appropriate state transition and receive a documented set of WATCHDOG_* environment variables. See Notifications and Hooks for the event timing and variable reference. 1

notifications.email

Email configuration is optional and disabled by default. When enabled, it requires an SMTP URL, sender, recipient array, and failure/recovery templates. The password can come from password_env or the less-preferred inline password, but never both. The SMTP timeout must be from 1 through 60 seconds. See Notifications and Hooks for the full field reference and secret-management pattern. 1

Validate before scheduling

A dry run validates the complete YAML document, confirms configured paths and command working directories, performs checks, and writes operational logs. It does not change state or invoke remediation, hooks, or email. 1

sudo /opt/service-watchdog/service-watchdog.sh \
  -c /etc/service-watchdog/config.yaml \
  -n

References