Skip to content

Docker watchdog

The image entrypoint (docker/entrypoint.sh) supervises the daemon. Its reaction depends on the daemon's exit status:

Daemon exit status Watchdog reaction
0, 129, 130, 143 Clean exit or signal termination: the watchdog stops with status 0.
78 Permanent configuration error: the watchdog parks.
Any other non-zero Restart with exponential backoff until WATCHDOG_MAX_RESTARTS consecutive failures; then the watchdog exits with the last status so Compose or another orchestrator applies its restart policy.

Settings

Variable Default Valid range / meaning
WATCHDOG_RESTART_DELAY 10 Initial delay in seconds; max 3600.
WATCHDOG_MAX_RESTART_DELAY 300 Backoff cap in seconds; max 86400.
WATCHDOG_MAX_RESTARTS 10 Consecutive failures before giving up; max 1000.
WATCHDOG_BACKOFF_RESET_AFTER 3600 Stable runtime in seconds before counters reset; max 604800.
WATCHDOG_SHUTDOWN_TIMEOUT 35 Grace period before SIGKILL; max 300.

All values must be positive integers (0, 00, ... are rejected; leading zeros are read as decimal). The daemon needs up to 25 seconds to shut down (5 s for in-flight FRITZ!Box requests, 10 s to drain the queue, 10 s for the final database flush) plus a 5 second reserve, so keep the shutdown timeout above 30 and the Compose stop_grace_period (40 s) above the shutdown timeout. If the initial delay exceeds the cap, the cap is used.

Python cannot cancel a running worker thread. FRITZ!Box requests check an elapsed-time budget of at most 10 seconds (the lower of four times connect_timeout and 10 s) while reading the response, so continuously trickling bodies eventually time out. A read already in progress can add its remaining read timeout; discovery or login can also involve several sequential requests. The watchdog owns the hard process deadline and sends SIGKILL when it expires. The daemon uses neither os._exit nor a replacement executor; a source run without the watchdog has no hard process-exit guarantee for permanently stuck I/O.

Parked state after a configuration error

Exit status 78 means the configuration is invalid, so a restart cannot help. This includes credentials or permissions rejected by the FRITZ!Box or the database, a missing InfluxDB database, organization or bucket, and TR-064 access switched off in the FRITZ!Box (see Startup preflight). The watchdog logs the error once, removes the daemon PID file and idles without using CPU. The retry counter and backoff do not apply. The watchdog stays alive on purpose: if it exited, restart: unless-stopped would restart the container in a loop.

Aspect Behaviour
Container state Running; the Compose healthcheck probes the PID file, so it reports unhealthy.
docker stop, SIGTERM, SIGINT End the parked watchdog immediately with status 0.
Corrected .env Not applied automatically. Restart explicitly, for example docker compose restart fritzfluxdb.