Check Types

Every enabled service needs one check map with a type of http, tcp, or command. Watchdog applies the shared timeout, attempts, and retry_delay controls to all three types. It stops retrying as soon as one attempt succeeds; otherwise it treats the service as unavailable after the final failed attempt. 1

Type	Best used for	Success condition
http	Web applications, APIs, reverse proxies, and health endpoints.	curl completes and the final response status is in success_status, or is any 2xx response when no allow-list is set.
tcp	Databases, brokers, caches, and other services that should accept connections.	A TCP connection to host:port opens before the configured timeout.
command	Local services with an authoritative CLI health signal.	Every command in check.commands returns zero, in order. 1

A successful network connection is not necessarily an application-health signal. Prefer a dedicated HTTP health endpoint or a command that verifies the specific condition you care about.

HTTP and HTTPS checks

An HTTP check requires a complete HTTP(S) URL without spaces. method may be only GET or HEAD; Watchdog follows redirects by default, with a maximum of five redirects. When success_status is omitted, the final HTTP status must match 2xx. Explicit statuses must be a non-empty array of three-digit numbers from 100 through 599. 1

Field	Required	Default	Meaning
type	Yes	None	Must be http.
url	Yes	None	HTTP or HTTPS endpoint.
method	No	GET	GET or HEAD.
follow_redirects	No	true	Whether to follow HTTP redirects.
success_status	No	Any 2xx	Explicit accepted final response codes.
timeout	No	Global default	Connection and total request timeout in seconds.
attempts	No	Global default	Number of health-check attempts.
retry_delay	No	Global default	Delay in seconds between failed attempts. 1

This check accepts only 200 or 204, tries twice, and restarts a Docker Compose service when both attempts fail.

services:
  - name: api
    check:
      type: http
      url: https://api.example.com/health
      method: GET
      follow_redirects: true
      success_status: [200, 204]
      timeout: 10
      attempts: 2
      retry_delay: 2
    actions:
      cooldown: 300
      verify_after: 5
      commands:
        - command: [docker, compose, restart, api]
          working_directory: /srv/api
          timeout: 120

A connection error, an empty response, HTTP 000, an unexpected status, or a curl error is a failed attempt. Examine the operational log for the stored detail when a check fails. 1

TCP checks

A TCP check uses Bash /dev/tcp inside a bounded command. It verifies that the specified host accepts a TCP connection; it does not perform an application protocol handshake, authenticate, or run a query. The host must be non-empty and contain no spaces. The port must be an integer from 1 through 65535. 1

Field	Required	Default	Meaning
type	Yes	None	Must be tcp.
host	Yes	None	DNS name or IP address without spaces.
port	Yes	None	TCP port from 1 through 65535.
timeout	No	Global default	Maximum connection time in seconds.
attempts	No	Global default	Number of connection attempts.
retry_delay	No	Global default	Delay in seconds between failed attempts. 1

This pattern checks a local PostgreSQL listener and restarts the matching systemd unit after an outage.

services:
  - name: local-postgresql
    check:
      type: tcp
      host: 127.0.0.1
      port: 5432
      timeout: 10
      attempts: 3
      retry_delay: 2
    actions:
      cooldown: 300
      verify_after: 3
      commands:
        - command: [systemctl, restart, postgresql]
          timeout: 60

Command checks

A command check is useful when the process exposes a local, authoritative status command. check.commands is required and must be a non-empty sequence. Commands run sequentially; Watchdog stops at the first non-zero command result. Each command can set an existing working_directory and an individual positive timeout. 1

Field	Required	Default	Meaning
type	Yes	None	Must be command.
commands	Yes	None	Non-empty command sequence using YAML argument arrays.
timeout	No	Global default	Shared check-setting field; command items may also define their own timeout.
attempts	No	Global default	Number of times to repeat the entire command sequence.
retry_delay	No	Global default	Delay in seconds before a new sequence attempt. 1

For example, use systemctl is-active --quiet to check a service and a separate direct command array to restart it. 2

services:
  - name: background-worker
    check:
      type: command
      attempts: 1
      commands:
        - command: [systemctl, is-active, --quiet, example-worker]
          timeout: 30
    actions:
      cooldown: 300
      verify_after: 2
      commands:
        - command: [systemctl, restart, example-worker]
          timeout: 60

Selecting a type

Situation	Recommended type	Rationale
Public API with /health or /readyz	http	Tests the endpoint that clients actually use and can enforce an expected response code.
PostgreSQL, Redis, or a message broker port	tcp	Provides a low-cost listener check when a protocol-specific probe is not required.
Local process supervised by systemd	command	Lets the service manager report its own state.
Docker Compose application	http plus Docker Compose remediation	Separates customer-facing readiness from the restart action.

Continue with Remediation, State, and Exit Codes to understand what happens after a check fails.

References