Agent installatie (systemd / Docker)

De LAN-agent is een klein Python-proces dat op uw Linux-apparaat in het interne netwerk draait en services controleert die vanaf internet niet bereikbaar zijn (interne DNS, intranet, ERP, NAS, printers). Hij communiceert uitgaand via HTTPS, dus hij heeft geen open poorten naar het netwerk toe nodig.

Kort samengevat: Maak een agent aan in het dashboard, kopieer het token en voer een enkele installatieopdracht uit op het doelapparaat. Het hele proces duurt 2 tot 3 minuten.

Wat u nodig hebt

Elke Linux met root-toegang (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Architectuur x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) of armv6l (RPi Zero)
Uitgaande HTTPS-verbinding naar epulz.io (poort 443)
Python 3.8 of nieuwer (ontbreekt het, dan installeert de installer het via de pakketbeheerder)

De agent gebruikt ongeveer 20 MB RAM en in rust minder dan 1 % CPU. Hij werkt ook in een LXC-container, in een virtuele machine (Proxmox, VMware) of in een Docker-container. Naast systemd ondersteunt hij ook OpenRC (Alpine).

Volledig controleerbaar: de hele agent is een enkel Python-bestand (~600 regels, alleen de standaardbibliotheek) en de installer is een openbaar script. Voor u het uitvoert, kunt u elke regel lezen: epulzio-agent.py en install-agent.sh.

1. Maak een agent aan en kopieer het token

Open Dashboard - LAN-agenten.
Voer een begrijpelijke naam in (bijvoorbeeld "Serverruimte Amsterdam" of "RPi in de winkel") en klik op + Agent aanmaken.
Het dashboard toont het token van de agent (epulzio_...) en kant-en-klare installatieopdrachten om te kopiëren.

Het token wordt maar één keer getoond. Kopieer het meteen. Deel het niet openbaar en publiceer het niet op GitHub. Als u het kwijtraakt of het lekt, trek de agent dan in het dashboard in (Revoke) en maak een nieuwe aan.

2. Voer de installatieopdracht uit

Op het doelapparaat in een terminal (vervang het token door uw eigen token):

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

Voorzichtigere aanpak (aanbevolen bij de eerste installatie): download het script eerst en lees het:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # lees wat het doet (1 min)
sudo bash install-agent.sh epulzio_UW_TOKEN

De installer doet automatisch het volgende:

Herkent de architectuur en distributie (apt / dnf / apk / pacman / zypper)
Controleert de aanwezigheid van Python 3.8+ en de tool ping en installeert ze indien nodig
Test de verbinding naar epulz.io
Downloadt de agent naar /opt/epulzio-agent/
Maakt de service epulzio-agent aan (systemd, op Alpine OpenRC) en start die
Schakelt automatisch starten bij het herstarten van het systeem in

De hele installatie duurt ongeveer 30 seconden.

3. Controleer dat de agent draait

Servicestatus op het apparaat:

sudo systemctl status epulzio-agent

U zou active (running) moeten zien.

Lijst met LAN-agenten met status online in het ePulz.io-dashboard — Dashboard - LAN-agenten: status, laatste contact en agentversie

In Dashboard - LAN-agenten verschijnt de status binnen 30 seconden:

online - het laatste levensteken (heartbeat) kwam minder dan 2 minuten geleden binnen
tijdstempel - de laatste heartbeat was 2 tot 10 minuten geleden
offline - de laatste heartbeat is ouder dan 10 minuten (een melding komt al na 5 minuten stilte)

Variant via Docker

Als u geen systemd hebt (TrueNAS, Synology, Unraid, k3s) of een container verkiest, gebruik dan de opdracht uit het dashboard:

docker run -d --name epulzio-agent --restart unless-stopped \
  --network host \
  -e EPULZIO_AGENT_TOKEN=epulzio_UW_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"

De schakelaar --network host is belangrijk - de agent moet uw LAN-netwerk zien, niet alleen de interne Docker-bridge. Bij elke herstart van de container wordt de actuele versie van de agent gedownload.

macOS en Windows

Voor macOS (10.15+, Intel en Apple Silicon):

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

Voor Windows (10+ / Server 2016+, PowerShell als administrator):

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

Problemen oplossen

De installer meldt "Missing agent token"

De opdracht mist het token. Voer hem uit met het token aan het eind: ... | sudo bash -s epulzio_UW_TOKEN.

De installer meldt "must run as root"

Voer hem uit via sudo; root is alleen nodig voor de installatie (systemd-service, schrijven naar /opt).

"Cannot reach epulz.io"

Het apparaat heeft geen uitgaande HTTPS-verbinding. Test handmatig met curl https://epulz.io/health. Mislukt dat, controleer dan firewall, DNS en NAT.

"Python 3.8+ required"

Zeer oud systeem. Werk de distributie bij of installeer een nieuwere Python (op Debian bijvoorbeeld apt install python3.9 uit backports).

"Neither systemd nor OpenRC detected"

Systeem zonder ondersteund init-systeem. Gebruik de Docker-variant hierboven.

De agent blijft in het dashboard offline, zelfs na 2 minuten

Bekijk de logs: sudo journalctl -u epulzio-agent -n 50.
Meest voorkomende oorzaken: verkeerd geplakt token (controleer of het volledige token is gekopieerd, inclusief het voorvoegsel epulzio_), HTTPS geblokkeerd op de firewall of een verkeerde systeemklok (controleer die met het commando date - de verificatie van het SSL-certificaat vereist de juiste tijd).

De agent bijwerken

Voer dezelfde installatieopdracht opnieuw uit met hetzelfde token. De installer overschrijft de bestanden in /opt/epulzio-agent/ en herstart de service, het token blijft geldig.

Verwijderen

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

Markeer de agent in het dashboard daarnaast als Revoked om zijn token ongeldig te maken.

Volgende stap

Uw eerste LAN-monitor aanmaken (ping, TCP, HTTP).

Eerste LAN-monitor