Agent-Installation (systemd / Docker)

Der LAN-Agent ist ein kleiner Python-Prozess, der auf Ihrem Linux-Gerät im internen Netzwerk läuft und Dienste prüft, die aus dem Internet nicht erreichbar sind (internes DNS, Intranet, ERP, NAS, Drucker). Er kommuniziert ausgehend über HTTPS, benötigt also keine ins Netzwerk hinein geöffneten Ports.

Kurz gesagt: Legen Sie im Dashboard einen Agenten an, kopieren Sie den Token und führen Sie auf dem Zielgerät einen einzigen Installationsbefehl aus. Der ganze Vorgang dauert 2 bis 3 Minuten.

Was Sie benötigen

Beliebiges Linux mit Root-Zugriff (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Architektur x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) oder armv6l (RPi Zero)
Ausgehende HTTPS-Verbindung zu epulz.io (Port 443)
Python 3.8 oder neuer (fehlt es, installiert es der Installer über den Paketmanager nach)

Der Agent benötigt rund 20 MB RAM und im Leerlauf weniger als 1 % CPU. Er funktioniert auch in einem LXC-Container, in einer virtuellen Maschine (Proxmox, VMware) oder in einem Docker-Container. Neben systemd unterstützt er auch OpenRC (Alpine).

Vollständig nachvollziehbar: Der gesamte Agent ist eine einzige Python-Datei (~600 Zeilen, nur Standardbibliothek) und der Installer ist ein öffentliches Skript. Vor der Ausführung können Sie jede Zeile lesen: epulzio-agent.py und install-agent.sh.

1. Agenten anlegen und Token kopieren

Öffnen Sie Dashboard - LAN-Agenten.
Geben Sie einen verständlichen Namen ein (zum Beispiel "Serverraum Bratislava" oder "RPi im Geschäft") und klicken Sie auf + Agenten erstellen.
Das Dashboard zeigt den Agenten-Token (epulzio_...) und fertige Installationsbefehle zum Kopieren an.

Der Token wird nur einmal angezeigt. Kopieren Sie ihn sofort. Geben Sie ihn nicht öffentlich weiter und veröffentlichen Sie ihn nicht auf GitHub. Wenn Sie ihn verlieren oder er durchsickert, widerrufen Sie den Agenten im Dashboard (Revoke) und erstellen Sie einen neuen.

2. Installationsbefehl ausführen

Auf dem Zielgerät im Terminal (ersetzen Sie den Token durch Ihren eigenen):

curl -fsSL https://epulz.io/install-agent.sh | sudo bash -s epulzio_IHR_TOKEN

Vorsichtigeres Vorgehen (empfohlen bei der ersten Installation): Laden Sie das Skript zuerst herunter und lesen Sie es:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # lesen Sie, was es tut (1 Min.)
sudo bash install-agent.sh epulzio_IHR_TOKEN

Der Installer erledigt automatisch:

Erkennt Architektur und Distribution (apt / dnf / apk / pacman / zypper)
Prüft das Vorhandensein von Python 3.8+ und des Tools ping und installiert sie bei Bedarf nach
Testet die Verbindung zu epulz.io
Lädt den Agenten nach /opt/epulzio-agent/ herunter
Erstellt den Dienst epulzio-agent (systemd, unter Alpine OpenRC) und startet ihn
Aktiviert den automatischen Start beim Neustart des Systems

Die gesamte Installation dauert etwa 30 Sekunden.

3. Prüfen, dass der Agent läuft

Dienststatus auf dem Gerät:

sudo systemctl status epulzio-agent

Sie sollten active (running) sehen.

Liste der LAN-Agenten mit Status online im ePulz.io-Dashboard — Dashboard - LAN-Agenten: Status, letzter Kontakt und Agenten-Version

In Dashboard - LAN-Agenten erscheint der Status innerhalb von 30 Sekunden:

online - das letzte Lebenszeichen (Heartbeat) kam vor weniger als 2 Minuten
Zeitstempel - der letzte Heartbeat war vor 2 bis 10 Minuten
offline - der letzte Heartbeat ist älter als 10 Minuten (eine Warnung kommt bereits nach 5 Minuten Stille)

Variante über Docker

Wenn Sie kein systemd haben (TrueNAS, Synology, Unraid, k3s) oder einen Container bevorzugen, verwenden Sie den Befehl aus dem Dashboard:

docker run -d --name epulzio-agent --restart unless-stopped \
  --network host \
  -e EPULZIO_AGENT_TOKEN=epulzio_IHR_TOKEN \
  python:3.12-alpine sh -c "apk add -q --no-cache iputils && wget -qO /agent.py https://epulz.io/static/agent/epulzio-agent.py && python /agent.py"

Der Schalter --network host ist wichtig - der Agent muss Ihr LAN sehen, nicht nur die interne Docker-Bridge. Bei jedem Neustart des Containers wird die aktuelle Agenten-Version heruntergeladen.

macOS und Windows

Für macOS (10.15+, Intel und Apple Silicon):

curl -fsSL https://epulz.io/install-agent-macos.sh -o install-agent-macos.sh
sudo bash install-agent-macos.sh epulzio_IHR_TOKEN

Für Windows (10+ / Server 2016+, PowerShell als Administrator):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
$env:EPULZIO_AGENT_TOKEN="epulzio_IHR_TOKEN"; iwr -useb https://epulz.io/install-agent.ps1 | iex

Problembehebung

Der Installer meldet "Missing agent token"

Dem Befehl fehlt der Token. Führen Sie ihn mit dem Token am Ende aus: ... | sudo bash -s epulzio_IHR_TOKEN.

Der Installer meldet "must run as root"

Führen Sie ihn über sudo aus; Root wird nur für die Installation benötigt (systemd-Dienst, Schreiben nach /opt).

"Cannot reach epulz.io"

Das Gerät hat keine ausgehende HTTPS-Verbindung. Testen Sie es manuell mit curl https://epulz.io/health. Schlägt das fehl, prüfen Sie Firewall, DNS und NAT.

"Python 3.8+ required"

Sehr altes System. Aktualisieren Sie die Distribution oder installieren Sie ein neueres Python (unter Debian zum Beispiel apt install python3.9 aus den Backports).

"Neither systemd nor OpenRC detected"

System ohne unterstütztes Init-System. Verwenden Sie die Docker-Variante oben.

Der Agent bleibt im Dashboard auch nach 2 Minuten offline

Sehen Sie sich die Logs an: sudo journalctl -u epulzio-agent -n 50.
Häufigste Ursachen: falsch eingefügter Token (prüfen Sie, dass der gesamte Token inklusive Präfix epulzio_ kopiert wurde), HTTPS auf der Firewall blockiert oder falsche Systemzeit (prüfen Sie sie mit dem Befehl date - die Überprüfung des SSL-Zertifikats erfordert die korrekte Zeit).

Agenten aktualisieren

Führen Sie denselben Installationsbefehl erneut mit demselben Token aus. Der Installer überschreibt die Dateien in /opt/epulzio-agent/ und startet den Dienst neu, der Token bleibt gültig.

Deinstallation

sudo systemctl stop epulzio-agent
sudo systemctl disable epulzio-agent
sudo rm -rf /opt/epulzio-agent /etc/systemd/system/epulzio-agent.service
sudo systemctl daemon-reload

Markieren Sie den Agenten im Dashboard zusätzlich als Revoked, um seinen Token ungültig zu machen.

Nächster Schritt

Erstellen des ersten LAN-Monitors (Ping, TCP, HTTP).

Erster LAN-Monitor