Installation#

Voraussetzungen#

Um unseren Go Agent zu installieren benötigen Sie:

  • API Token Ihrer Organisation: Zu finden oder neu zu generieren im Reiter Organisation

  • Agent ID: Wird nach der Erstellung eines neuen Agenten im Dashboard angezeigt

  • Netzwerkverbindung: Das Zielsystem muss ausgehende HTTP/HTTPS-Requests an unseren Server senden können

  • Unterstütztes Betriebssystem: Das Betriebssystem sowie die Architektur müssen unterstützt sein (siehe Voraussetzungen)

  • Root- / Sudo-Rechte: Zur Einrichtung und Ausführung des systemd-Dienstes auf dem Zielsystem

Hintergrund & Funktionsweise#

Der Agent erleichtert das Monitoring eines Systems, indem Basismetriken automatisch gesammelt werden. Weitere Metriken sowie die Konfiguration des Agenten können bequem im Dashboard verwaltet werden.

Die gesammelten Basismetriken & Systeminformationen sind:

  • Betriebssystem inkl. Version

  • Hostname

  • Architektur (arm64, amd64, etc.)

  • Hardware-Spezifikationen (Anzahl CPU-Kerne, RAM-Gesamtkapazität in GB, Gesamtkapazität der Festplatte)

  • CPU-Auslastung (%)

  • RAM-Auslastung (%)

  • Nutzung der Festplatte (%)

  • Uptime des Systems

Schritt-für-Schritt-Einrichtung#

Schritt 1: API-Token der Organisation erstellen / kopieren#

  1. Navigieren Sie im WatchGrid-Dashboard zum Reiter Organisation.

  2. Falls Sie bereits ein aktives API-Token besitzen und gesichert haben, können Sie dieses verwenden (WG_TOKEN).

  3. Neues API-Token erstellen / neu generieren: Um ein neues Token zu erstellen (z. B. für den ersten Agenten oder falls kein Token vorliegt), löschen Sie das bestehende Token in der Liste und erstellen Sie anschließend ein neues Token.

    Wichtig

    Das neu erstellte API-Token wird nur einmalig für kurze Zeit in einer Systembenachrichtigung (Message/Toast) im Dashboard angezeigt! Kopieren Sie den Token-Wert sofort und speichern Sie ihn sicher ab.

    Warnung

    Wenn Sie ein bestehendes Token löschen, verlieren bereits installierte Agenten, die dieses Token nutzen, ihre Berechtigung. Diese müssen anschließend mit dem neuen Token aktualisiert werden (siehe API-Token austauschen).

Schritt 2: Ersten Agenten im Dashboard anlegen#

  1. Wechseln Sie in die Agenten-Übersicht im Dashboard.

  2. Klicken Sie oben rechts auf die Schaltfläche „Agent hinzufügen“.

  3. Geben Sie einen aussagekräftigen Namen für den Server/Agenten ein (z. B. web-server-01).

  4. Nach dem Speichern wird Ihnen die eindeutige Agent ID (UUID) angezeigt. Kopieren Sie diese Agent ID (WG_AGENT).

Schritt 3: Einzeiler-Installation auf dem Zielsystem ausführen#

Öffnen Sie ein Terminal/SSH auf Ihrem Zielserver und führen Sie den Einzeiler-Befehl aus. Ersetzen Sie dabei <AGENT_ID> und <API_TOKEN> durch die Werte aus den Schritten 1 und 2:

curl -sfL https://wgri.de/install | WG_AGENT="<AGENT_ID>" WG_TOKEN="<API_TOKEN>" sh -

Beispiel:

curl -sfL https://wgri.de/install | WG_AGENT="123e4567-e89b-12d3-a456-426614174000" WG_TOKEN="wg_live_abc123xyz..." sh -

Schritt 4: Installation verifizieren#

Nach erfolgreicher Ausführung wird der Agent automatisch als systemd-Dienst (watchgrid.service) eingerichtet und gestartet.

  • Prüfen Sie den Dienststatus auf dem Server:

    systemctl status watchgrid.service

  • Im Dashboard wechselt der Status des neuen Agenten nach wenigen Sekunden auf Online, und die ersten Metriken werden dargestellt.

Detail-Konfiguration & Architektur#

Systemd-Service Betrieb#

Der Go-Agent wird standardmäßig als systemd-Dienst betrieben (watchgrid.service). Er startet automatisch bei jedem Systemstart neu und überwacht kontinuierlich im Hintergrund.

Lokaler Konfigurations-Cache#

Der Agent kommuniziert nach dem Pull-Prinzip mit dem WatchGrid-Server. Bei jedem Start (oder periodisch bei der Metrik-Erfassung) ruft der Agent die neueste Konfiguration vom Server ab. Diese Konfiguration wird lokal als Cache-Datei unter /etc/watchgrid/config.json (bzw. ./config/config.json in der Entwicklungsumgebung) gespeichert.

Sollte der WatchGrid-Server vorübergehend nicht erreichbar sein, greift der Agent automatisch auf diese lokal gecachte Konfigurationsdatei zurück. Dadurch ist ein unterbrechungsfreier Betrieb gewährleistet.

Service- und Port-Monitoring#

Zusätzlich zu den Basismetriken (CPU, RAM, Festplatte) kann der Agent auch spezifische Netzwerk-Ports und systemd-Dienste überwachen. Diese Überwachung wird zentral im Dashboard oder über die API konfiguriert und an den Agenten übermittelt.

  • Port-Überwachung: Der Agent liest /proc/net/tcp und /proc/net/tcp6 aus, um offene Listening-Ports zu ermitteln. Falls offene Ports gefunden werden, die nicht in der vom Server bereitgestellten Whitelist (erlaubte Ports) enthalten sind, wird dies als Anomalie/Fehler erfasst und an den Server gemeldet (localhost-Verbindungen auf 127.0.0.1 oder ::1 werden ignoriert).

  • Dienst-Überwachung: Der Agent nutzt das Systemtool systemctl is-active --quiet <dienst_name>, um den Status spezifizierter systemd-Dienste zu überprüfen. Wenn ein konfigurierter Dienst gestoppt ist, wird dieser als fehlerhafter Dienst markiert und gemeldet.