Watchdog: Agenten einrichten

Agenten für Host- und Remote-Server einrichten: Token anlegen, Compose-Dienst, Remote-Image, Umgebungsvariablen, Mounts und pid-Namespace sowie Funktionsweise und Verwaltung.

English Version

Zurück zur Übersicht

Watchdog: Agenten einrichten

Watchdog kennt zwei Arten, Checks auszuführen:

Dashboard-Checks laufen im Worker-Container des Watchdog-Servers. Sie prüfen, was von dort übers Netz erreichbar ist, etwa HTTP, SSL, TCP oder DNS.
Agenten-Checks laufen in einem kleinen Container auf der überwachten Maschine. Er hat Zugriff auf Dateisystem, /proc, Prozessliste und den Docker-Socket.

Welche Art ein Check-Typ erlaubt, steht in der Check-Typen-Übersicht.

Der Agent verbindet sich von sich aus zum Dashboard und holt Checks ab. Auf der überwachten Maschine muss kein eingehender Port offen sein.

Schritt 1: Agenten anlegen

Melde Dich an und öffne in der Navigation Agents.
Klicke auf + Register Agent und vergib einen Namen, etwa host-server oder kunde-acme.
Kopiere das angezeigte Token sofort. Die Oberfläche zeigt es nur einmal, danach liegt nur noch ein Hash in der Datenbank.

Jede überwachte Maschine bekommt einen eigenen Agenten und ein eigenes Token.

Host-Agent im Compose-Stack

Die Dateien compose.yml, compose.stage.yml und compose.live.yml enthalten bereits einen Dienst agent. Er wird aus demselben Dockerfile gebaut (Ziel agent), läuft als Benutzer www-data und startet php bin/console watchdog:agent:run. Er erreicht das Dashboard über das interne Docker-Netz unter http://app:80.

Token in die Env-Datei eintragen: WATCHDOG_AGENT_TOKEN=... in .env.stage bzw. .env.live. Im lokalen Stack liest compose.yml die Variable aus der Shell-Umgebung oder der Datei .env neben der Compose-Datei, .env.local liest Docker Compose nicht.
Den Dienst (neu) starten:

docker compose -f compose.stage.yml up -d agent

Auf Live verwendest Du compose.live.yml, lokal docker compose up -d agent.

Der Dienst im Überblick (Stage):

agent:
  build:
    context: .
    target: agent
  environment:
    WATCHDOG_DASHBOARD_URL: http://app:80
    HOST_ROOT: /host/root
    TZ: Europe/Berlin
  env_file: .env.stage            # enthält WATCHDOG_AGENT_TOKEN
  pid: host                       # für den Prozess-Check
  volumes:
    - /:/host/root:ro             # für Festplatten-, Datei- und Log-Checks
    # - /var/run/docker.sock:/var/run/docker.sock:ro   # für Docker-Checks
  restart: unless-stopped

Docker-Checks auf dem Agenten

Der Docker-Socket ist in den Compose-Dateien auskommentiert. Aktiviere die Zeile, damit Docker und Docker Exec auf dem Agenten laufen. Da der Agent als www-data läuft, muss er den Socket lesen dürfen. Worker und Scheduler lösen das in den Compose-Dateien über group_add mit der Gruppen-ID des Sockets (DOCKER_GID, Standard 995). Für den Agenten brauchst Du denselben Eintrag, wenn der Socket nur für die Docker-Gruppe zugänglich ist.

Dashboard-Checks vom Typ Docker laufen im Worker-Container, der den Socket schon eingebunden hat.

Remote-Agent auf einem anderen Server

Für einen anderen Server (etwa beim Kunden) gibt es ein fertiges Image, das die CI für den Zweig main und für Release-Tags baut und veröffentlicht: ghcr.io/markus-michalski/watchdog/agent:latest (Architekturen amd64 und arm64).

Als Vorlage dient docker-compose.agent.yml aus dem Repository:

services:
  watchdog-agent:
    image: ghcr.io/markus-michalski/watchdog/agent:latest
    restart: unless-stopped
    environment:
      WATCHDOG_DASHBOARD_URL: https://watchdog.example.com
      WATCHDOG_AGENT_TOKEN: your-agent-token-here
      HOST_ROOT: /host/root
      TZ: Europe/Berlin
    pid: host
    volumes:
      - /:/host/root:ro

docker compose -f docker-compose.agent.yml up -d

Die Vorlage im Repository setzt HOST_ROOT nicht. Ohne HOST_ROOT: /host/root liest der Agent die Pfade im eigenen Container statt im Host-Dateisystem. Ergänze die Zeile deshalb, sobald Du Festplatten-, Datei- oder Log-Checks nutzt.

Der Server muss die Dashboard-URL erreichen können, am besten per HTTPS. WATCHDOG_DASHBOARD_URL hat keinen abschließenden Schrägstrich.

Umgebungsvariablen

Variable	Pflicht	Bedeutung
`WATCHDOG_DASHBOARD_URL`	ja	Basis-URL des Dashboards ohne abschließenden Schrägstrich. `http://app:80` im Compose-Stack, bei Remote-Agenten die öffentliche HTTPS-URL
`WATCHDOG_AGENT_TOKEN`	ja	Token aus dem Dialog Register Agent
`HOST_ROOT`	für Datei-, Festplatten- und Log-Checks	Präfix, das vor die konfigurierten Pfade gesetzt wird, üblicherweise `/host/root`
`TZ`	empfohlen	Zeitzone, für Zeiten in den Meldungen und die tägliche Ausführungszeit

Voraussetzungen je Check-Typ

Check-Typ	Nötig auf dem Agenten
Festplatte, Datei-Alter, Dateigröße, Log-Datei	Volume `/:/host/root:ro` und `HOST_ROOT=/host/root`
Prozess	`pid: host`
Docker, Docker Exec	Volume `/var/run/docker.sock:/var/run/docker.sock:ro` und Leserecht auf den Socket
Load Average	nichts, liest `/proc/loadavg`
TCP-Port, Redis, Datenbank, DNS	nichts, die Prüfung läuft von der Maschine des Agenten aus

HTTP, HTTP-Inhalt und SSL-Zertifikat sind reine Dashboard-Checks und lassen sich keinem Agenten zuweisen.

Funktionsweise

Beim Start holt der Agent seine Check-Liste von /api/v1/agent/config.
Alle 30 Sekunden (Tick) fragt er /api/v1/agent/run-now nach manuell angeforderten Läufen und führt alle fälligen Checks aus.
Die Ergebnisse eines Ticks sendet er gesammelt an /api/v1/agent/results.
Alle 5 Minuten lädt der Agent die Check-Liste neu und übernimmt so neue oder geänderte Checks.
Scheitert das Laden der Check-Liste fünfmal hintereinander (etwa bei widerrufenem Token oder nicht erreichbarem Dashboard), leert der Agent seine Liste, statt mit veralteter Konfiguration weiterzuarbeiten. Sobald das Dashboard wieder antwortet, macht er automatisch weiter.

Der Agent beendet sich bei SIGTERM und SIGINT geordnet. Einen Testlauf ohne Dauerbetrieb startest Du mit --run-once:

docker compose -f docker-compose.agent.yml run --rm watchdog-agent --run-once

Ein Agent bekommt nur aktive Checks von aktiven Clients, die ihm zugewiesen sind und deren Runner Agent (Local) ist. Das Intervall und die tägliche Uhrzeit gelten wie bei Dashboard-Checks, der Agent prüft sie aber lokal und startet einen Check frühestens nach Ablauf des Intervalls minus 5 Sekunden.

Verwaltung

Aktion	Wirkung
Edit Name	Benennt den Agenten um
Regenerate Token	Erzeugt ein neues Token. Das alte funktioniert sofort nicht mehr, der Agent braucht das neue Token
Delete Agent	Entfernt den Agenten. Seine Checks bleiben bestehen, werden aber vom Agenten gelöst und auf den Runner Dashboard (Network) umgestellt

Nach dem Löschen eines Agenten laufen seine Checks im Worker-Container des Dashboards weiter. Agenten-Typen wie Festplatte oder Prozess messen dann den Dashboard-Container statt der überwachten Maschine. Weise sie vor dem Löschen einem anderen Agenten zu oder deaktiviere sie.

Der Status des Agenten in der Oberfläche ist Online, wenn er in den letzten 10 Minuten Kontakt hatte. Bei Ausfall des Agenten sendet Watchdog keine Benachrichtigung, siehe Benachrichtigungen.

Weitere Hinweise zu Berechtigungen stehen unter Sicherheit und Datenschutz, Fehlerbilder unter Fehlerbehebung.