Installazione agent (systemd / Docker)

L'agente LAN è un piccolo processo Python che gira sul vostro dispositivo Linux all'interno della rete interna e controlla i servizi non raggiungibili da internet (DNS interno, intranet, ERP, NAS, stampanti). Comunica verso l'esterno tramite HTTPS, quindi non richiede alcuna porta aperta verso l'interno della rete.

In breve: Create un agente nella dashboard, copiate il token ed eseguite un singolo comando di installazione sul dispositivo di destinazione. L'intero processo richiede 2-3 minuti.

Cosa vi servirà

Qualsiasi Linux con accesso root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Architettura x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) o armv6l (RPi Zero)
Connessione HTTPS in uscita verso epulz.io (porta 443)
Python 3.8 o più recente (se manca, l'installer lo aggiunge dal gestore dei pacchetti)

L'agente occupa circa 20 MB di RAM e meno dell'1 % di CPU a riposo. Funziona anche in un container LXC, in una macchina virtuale (Proxmox, VMware) o in un container Docker. Oltre a systemd supporta anche OpenRC (Alpine).

Completamente verificabile: l'intero agente è un singolo file Python (~600 righe, solo libreria standard) e l'installer è uno script pubblico. Prima di eseguirlo potete leggere ogni riga: epulzio-agent.py e install-agent.sh.

1. Create un agente e copiate il token

Aprite Dashboard - Agenti LAN.
Inserite un nome comprensibile (ad esempio "Sala server Milano" o "RPi nel negozio") e fate clic su + Crea agente.
La dashboard mostra il token dell'agente (epulzio_...) e comandi di installazione pronti da copiare.

Il token viene mostrato una sola volta. Copiatelo subito. Non condividetelo pubblicamente e non pubblicatelo su GitHub. Se lo perdete o trapela, revocate l'agente nella dashboard (Revoke) e createne uno nuovo.

2. Eseguite il comando di installazione

Sul dispositivo di destinazione, in un terminale (sostituite il token con il vostro):

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

Approccio più prudente (consigliato alla prima installazione): scaricate prima lo script e leggetelo:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # leggete cosa fa (1 min)
sudo bash install-agent.sh epulzio_IL_TUO_TOKEN

L'installer automaticamente:

Riconosce l'architettura e la distribuzione (apt / dnf / apk / pacman / zypper)
Verifica la presenza di Python 3.8+ e dello strumento ping, installandoli se necessario
Testa la connessione verso epulz.io
Scarica l'agente in /opt/epulzio-agent/
Crea il servizio epulzio-agent (systemd, OpenRC su Alpine) e lo avvia
Attiva l'avvio automatico al riavvio del sistema

L'intera installazione dura circa 30 secondi.

3. Verificate che l'agente sia in esecuzione

Stato del servizio sul dispositivo:

sudo systemctl status epulzio-agent

Dovreste vedere active (running).

Elenco degli agenti LAN con stato online nella dashboard di ePulz.io — Dashboard - Agenti LAN: stato, ultimo contatto e versione dell'agente

In Dashboard - Agenti LAN lo stato compare entro 30 secondi:

online - l'ultimo segnale di vita (heartbeat) è arrivato meno di 2 minuti fa
timestamp - l'ultimo heartbeat è stato 2-10 minuti fa
offline - l'ultimo heartbeat è più vecchio di 10 minuti (l'avviso arriva già dopo 5 minuti di silenzio)

Variante tramite Docker

Se non avete systemd (TrueNAS, Synology, Unraid, k3s) o preferite un container, usate il comando della dashboard:

docker run -d --name epulzio-agent --restart unless-stopped \
  --network host \
  -e EPULZIO_AGENT_TOKEN=epulzio_IL_TUO_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'opzione --network host è importante - l'agente deve vedere la vostra rete LAN, non solo il bridge interno di Docker. A ogni riavvio del container viene scaricata la versione attuale dell'agente.

macOS e Windows

Per macOS (10.15+, Intel e Apple Silicon):

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

Per Windows (10+ / Server 2016+, PowerShell come amministratore):

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

Risoluzione dei problemi

L'installer segnala "Missing agent token"

Al comando manca il token. Eseguitelo con il token alla fine: ... | sudo bash -s epulzio_IL_TUO_TOKEN.

L'installer segnala "must run as root"

Eseguitelo tramite sudo; root serve solo per l'installazione (servizio systemd, scrittura in /opt).

"Cannot reach epulz.io"

Il dispositivo non ha una connessione HTTPS in uscita. Testatela manualmente con curl https://epulz.io/health. Se fallisce, controllate firewall, DNS e NAT.

"Python 3.8+ required"

Sistema molto vecchio. Aggiornate la distribuzione o installate un Python più recente (su Debian ad esempio apt install python3.9 dai backports).

"Neither systemd nor OpenRC detected"

Sistema senza un sistema init supportato. Usate la variante Docker qui sopra.

L'agente resta offline nella dashboard anche dopo 2 minuti

Guardate i log: sudo journalctl -u epulzio-agent -n 50.
Cause più frequenti: token incollato in modo errato (verificate che sia stato copiato per intero, incluso il prefisso epulzio_), HTTPS bloccato sul firewall oppure orario di sistema errato (verificatelo con il comando date - la verifica del certificato SSL richiede l'orario corretto).

Aggiornamento dell'agente

Eseguite di nuovo lo stesso comando di installazione con lo stesso token. L'installer sovrascrive i file in /opt/epulzio-agent/ e riavvia il servizio, il token resta valido.

Disinstallazione

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

Nella dashboard, contrassegnate inoltre l'agente come Revoked per invalidare il suo token.

Passo successivo

Creazione del vostro primo monitor LAN (ping, TCP, HTTP).

Primo monitor LAN