Installation agent (systemd / Docker)

L'agent LAN est un petit processus Python qui s'exécute sur votre appareil Linux dans le réseau interne et vérifie les services inaccessibles depuis Internet (DNS interne, intranet, ERP, NAS, imprimantes). Il communique vers l'extérieur via HTTPS, il n'a donc besoin d'aucun port ouvert vers l'intérieur du réseau.

En bref : Créez un agent dans le tableau de bord, copiez le token et exécutez une seule commande d'installation sur l'appareil cible. L'ensemble du processus prend 2 à 3 minutes.

Ce dont vous aurez besoin

N'importe quel Linux avec accès root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Architecture x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) ou armv6l (RPi Zero)
Connexion HTTPS sortante vers epulz.io (port 443)
Python 3.8 ou plus récent (s'il manque, l'installateur l'ajoute depuis le gestionnaire de paquets)

L'agent occupe environ 20 Mo de RAM et moins de 1 % de CPU au repos. Il fonctionne aussi dans un conteneur LXC, une machine virtuelle (Proxmox, VMware) ou un conteneur Docker. Outre systemd, il prend également en charge OpenRC (Alpine).

Entièrement auditable : l'agent entier est un seul fichier Python (~600 lignes, bibliothèque standard uniquement) et l'installateur est un script public. Avant de l'exécuter, vous pouvez lire chaque ligne : epulzio-agent.py et install-agent.sh.

1. Créez un agent et copiez le token

Ouvrez Tableau de bord - Agents LAN.
Saisissez un nom clair (par exemple "Salle serveur Paris" ou "RPi en magasin") et cliquez sur + Créer un agent.
Le tableau de bord affiche le token de l'agent (epulzio_...) et des commandes d'installation prêtes à copier.

Le token ne s'affiche qu'une seule fois. Copiez-le tout de suite. Ne le partagez pas publiquement et ne le publiez pas sur GitHub. Si vous le perdez ou s'il fuit, révoquez l'agent dans le tableau de bord (Revoke) et créez-en un nouveau.

2. Exécutez la commande d'installation

Sur l'appareil cible, dans un terminal (remplacez le token par le vôtre) :

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

Approche plus prudente (recommandée pour la première installation) : téléchargez d'abord le script et lisez-le :

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # lisez ce qu'il fait (1 min)
sudo bash install-agent.sh epulzio_VOTRE_TOKEN

L'installateur automatiquement :

Détecte l'architecture et la distribution (apt / dnf / apk / pacman / zypper)
Vérifie la présence de Python 3.8+ et de l'outil ping, et les installe au besoin
Teste la connexion vers epulz.io
Télécharge l'agent dans /opt/epulzio-agent/
Crée le service epulzio-agent (systemd, OpenRC sur Alpine) et le démarre
Active le démarrage automatique au redémarrage du système

L'installation complète prend environ 30 secondes.

3. Vérifiez que l'agent fonctionne

État du service sur l'appareil :

sudo systemctl status epulzio-agent

Vous devriez voir active (running).

Liste des agents LAN avec l'état en ligne dans le tableau de bord ePulz.io — Tableau de bord - Agents LAN : état, dernier contact et version de l'agent

Dans Tableau de bord - Agents LAN, l'état apparaît en 30 secondes :

en ligne - le dernier signe de vie (heartbeat) est arrivé il y a moins de 2 minutes
horodatage - le dernier heartbeat date de 2 à 10 minutes
hors ligne - le dernier heartbeat date de plus de 10 minutes (une alerte est envoyée dès 5 minutes de silence)

Variante via Docker

Si vous n'avez pas systemd (TrueNAS, Synology, Unraid, k3s) ou si vous préférez un conteneur, utilisez la commande du tableau de bord :

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

L'option --network host est importante - l'agent doit voir votre réseau LAN, pas seulement le bridge Docker interne. À chaque redémarrage du conteneur, la version actuelle de l'agent est téléchargée.

macOS et Windows

Pour macOS (10.15+, Intel et Apple Silicon) :

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

Pour Windows (10+ / Server 2016+, PowerShell en tant qu'administrateur) :

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

Résolution des problèmes

L'installateur signale "Missing agent token"

Le token manque à la commande. Exécutez-la avec le token à la fin : ... | sudo bash -s epulzio_VOTRE_TOKEN.

L'installateur signale "must run as root"

Exécutez-la via sudo ; root n'est nécessaire que pour l'installation (service systemd, écriture dans /opt).

"Cannot reach epulz.io"

L'appareil n'a pas de connexion HTTPS sortante. Testez-la manuellement avec curl https://epulz.io/health. Si cela échoue, vérifiez le pare-feu, le DNS et le NAT.

"Python 3.8+ required"

Système très ancien. Mettez à jour la distribution ou installez un Python plus récent (sur Debian par exemple apt install python3.9 depuis les backports).

"Neither systemd nor OpenRC detected"

Système sans système d'init pris en charge. Utilisez la variante Docker ci-dessus.

L'agent reste hors ligne dans le tableau de bord même après 2 minutes

Consultez les logs : sudo journalctl -u epulzio-agent -n 50.
Causes les plus fréquentes : token mal collé (vérifiez qu'il a été copié en entier, préfixe epulzio_ compris), HTTPS bloqué sur le pare-feu ou heure système incorrecte (vérifiez-la avec la commande date - la vérification du certificat SSL nécessite une heure correcte).

Mise à jour de l'agent

Exécutez à nouveau la même commande d'installation avec le même token. L'installateur écrase les fichiers dans /opt/epulzio-agent/ et redémarre le service, le token reste valide.

Désinstallation

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

Dans le tableau de bord, marquez en plus l'agent comme Revoked pour invalider son token.

Étape suivante

Création de votre premier moniteur LAN (ping, TCP, HTTP).

Premier moniteur LAN