Installation and First Run

Watchdog is designed for Linux systems with Bash 4.3 or newer. Before installing it, ensure that the host has curl, flock, GNU timeout and base64 from GNU coreutils, and Mike Farah yq v4. The unrelated Python package named yq is not compatible. 1 2

Run the installer as root only after you have reviewed the repository version you intend to deploy. It installs a system-level script and scheduler units.

Prerequisites

On Debian or Ubuntu, install the required operating-system packages first. Install Mike Farah yq v4 using its official package or release instructions, and verify that yq --version reports a v4 release. 1

sudo apt-get update
sudo apt-get install -y bash curl util-linux coreutils unzip

yq --version

Requirement	Why Watchdog needs it
Linux and Bash 4.3+	The script uses Bash features and Linux runtime interfaces.
Mike Farah yq v4	Parses and validates YAML configuration.
curl	Performs HTTP checks and SMTP delivery.
flock	Prevents concurrent Watchdog runs.
GNU timeout and base64	Bounds command execution and encodes UTF-8 mail subjects.
systemctl	Required only by the supplied installer and packaged systemd units. 2 3

Install with the supplied installer

Clone the desired repository revision, review the configuration example, and execute the installer with sudo. The installer verifies dependencies, creates the runtime directories, installs the script and unit files, reloads systemd, and preserves an existing configuration rather than overwriting it. 3

git clone https://github.com/tigusigalpa/watchdog.git
cd watchdog

git checkout v1.0.6
sudo ./install.sh

The installer uses the following paths unless its environment-variable overrides are set before it runs. 3

Purpose	Default path	Permission intent
Executable	/opt/service-watchdog/service-watchdog.sh	Executable by the service.
Configuration	/etc/service-watchdog/config.yaml	Installed with mode 0640; keep it administrator-controlled.
Log directory	/var/log/service-watchdog	Created with mode 0750.
State directory	/var/lib/service-watchdog	Created with mode 0750.
systemd service	/etc/systemd/system/service-watchdog.service	Installed by the script.
systemd timer	/etc/systemd/system/service-watchdog.timer	Installed by the script.

Edit the generated configuration before enabling the timer. Start with a dry run: it performs checks and writes operational logs, but it does not run remediation commands, execute hooks, or write state. 2

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

If validation succeeds and the check results match expectations, enable the packaged timer.

sudo systemctl enable --now service-watchdog.timer
systemctl list-timers service-watchdog.timer
sudo journalctl -u service-watchdog.service -n 50 --no-pager

The supplied unit executes as root, uses /etc/service-watchdog/environment as an optional environment file, and treats Watchdog exit code 1 as an expected service outcome. See Scheduling with systemd and cron before changing its privilege model or schedule. 4

Manual installation

Use manual installation when you do not want to install the supplied unit files or need a non-standard path. Create the target directory, install the executable and configuration with restrictive modes, then invoke the script with the -c option.

sudo install -d -m 0755 /opt/service-watchdog /etc/service-watchdog
sudo install -d -m 0750 /var/log/service-watchdog /var/lib/service-watchdog
sudo install -d -m 0755 /run/lock

sudo install -m 0755 service-watchdog.sh /opt/service-watchdog/
sudo install -m 0640 config.example.yaml /etc/service-watchdog/config.yaml

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

The configuration must provide absolute paths for settings.log_file, settings.lock_file, and settings.state_directory. The process creates their parent directories when it starts, but the account that runs Watchdog must be allowed to create and write them. 2

Upgrade safely

To upgrade, review CHANGELOG.md, compare the new config.example.yaml with the deployed configuration, and validate the updated configuration in dry-run mode before restoring the schedule. The installer preserves the existing config, so it will not automatically introduce newly available settings. 3 5

sudo systemctl disable --now service-watchdog.timer
# Install the reviewed new release here.
sudo /opt/service-watchdog/service-watchdog.sh \
  -c /etc/service-watchdog/config.yaml \
  -n
sudo systemctl enable --now service-watchdog.timer

Continue with Configuration Reference to create a valid production configuration.

References