Instalación agent (systemd / Docker)

El agente LAN es un pequeño proceso de Python que se ejecuta en su dispositivo Linux dentro de la red interna y comprueba servicios a los que no se puede llegar desde internet (DNS interno, intranet, ERP, NAS, impresoras). Se comunica hacia el exterior por HTTPS, así que no necesita ningún puerto abierto hacia el interior de la red.

En resumen: Cree un agente en el panel, copie el token y ejecute un único comando de instalación en el dispositivo de destino. Todo el proceso lleva de 2 a 3 minutos.

Qué necesitará

Cualquier Linux con acceso root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Arquitectura x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) o armv6l (RPi Zero)
Conexión HTTPS saliente a epulz.io (puerto 443)
Python 3.8 o más reciente (si falta, el instalador lo añade desde el gestor de paquetes)

El agente ocupa unos 20 MB de RAM y menos del 1 % de CPU en reposo. También funciona en un contenedor LXC, en una máquina virtual (Proxmox, VMware) o en un contenedor Docker. Además de systemd, también admite OpenRC (Alpine).

Totalmente auditable: todo el agente es un único archivo de Python (~600 líneas, solo biblioteca estándar) y el instalador es un script público. Antes de ejecutarlo puede leer cada línea: epulzio-agent.py e install-agent.sh.

1. Cree un agente y copie el token

Abra Panel - Agentes LAN.
Introduzca un nombre comprensible (por ejemplo "Sala de servidores Madrid" o "RPi en la tienda") y haga clic en + Crear agente.
El panel muestra el token del agente (epulzio_...) y comandos de instalación listos para copiar.

El token se muestra solo una vez. Cópielo de inmediato. No lo comparta públicamente ni lo publique en GitHub. Si lo pierde o se filtra, revoque el agente en el panel (Revoke) y cree uno nuevo.

2. Ejecute el comando de instalación

En el dispositivo de destino, en una terminal (sustituya el token por el suyo):

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

Enfoque más prudente (recomendado en la primera instalación): descargue primero el script y léalo:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # lea qué hace (1 min)
sudo bash install-agent.sh epulzio_SU_TOKEN

El instalador automáticamente:

Detecta la arquitectura y la distribución (apt / dnf / apk / pacman / zypper)
Comprueba la presencia de Python 3.8+ y de la herramienta ping, y los instala si es necesario
Prueba la conexión a epulz.io
Descarga el agente en /opt/epulzio-agent/
Crea el servicio epulzio-agent (systemd, OpenRC en Alpine) y lo inicia
Activa el inicio automático al reiniciar el sistema

Toda la instalación dura unos 30 segundos.

3. Verifique que el agente se está ejecutando

Estado del servicio en el dispositivo:

sudo systemctl status epulzio-agent

Debería ver active (running).

Lista de agentes LAN con estado en línea en el panel de ePulz.io — Panel - Agentes LAN: estado, último contacto y versión del agente

En Panel - Agentes LAN, el estado aparece en 30 segundos:

en línea - la última señal de vida (heartbeat) llegó hace menos de 2 minutos
marca de tiempo - el último heartbeat fue hace 2 a 10 minutos
desconectado - el último heartbeat tiene más de 10 minutos (la alerta llega ya tras 5 minutos de silencio)

Variante con Docker

Si no tiene systemd (TrueNAS, Synology, Unraid, k3s) o prefiere un contenedor, use el comando del panel:

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

El parámetro --network host es importante - el agente debe ver su red LAN, no solo el bridge interno de Docker. En cada reinicio del contenedor se descarga la versión actual del agente.

macOS y Windows

Para macOS (10.15+, Intel y Apple Silicon):

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

Para Windows (10+ / Server 2016+, PowerShell como administrador):

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

Resolución de problemas

El instalador informa "Missing agent token"

Al comando le falta el token. Ejecútelo con el token al final: ... | sudo bash -s epulzio_SU_TOKEN.

El instalador informa "must run as root"

Ejecútelo con sudo; root solo es necesario para la instalación (servicio systemd, escritura en /opt).

"Cannot reach epulz.io"

El dispositivo no tiene conexión HTTPS saliente. Pruébela manualmente con curl https://epulz.io/health. Si falla, compruebe el cortafuegos, el DNS y el NAT.

"Python 3.8+ required"

Sistema muy antiguo. Actualice la distribución o instale un Python más reciente (en Debian por ejemplo apt install python3.9 desde backports).

"Neither systemd nor OpenRC detected"

Sistema sin un sistema de init compatible. Use la variante de Docker de arriba.

El agente sigue desconectado en el panel incluso después de 2 minutos

Revise los logs: sudo journalctl -u epulzio-agent -n 50.
Causas más frecuentes: token mal pegado (compruebe que se copió completo, incluido el prefijo epulzio_), HTTPS bloqueado en el cortafuegos u hora del sistema incorrecta (compruébela con el comando date - la verificación del certificado SSL requiere la hora correcta).

Actualización del agente

Ejecute de nuevo el mismo comando de instalación con el mismo token. El instalador sobrescribe los archivos en /opt/epulzio-agent/ y reinicia el servicio, el token sigue siendo válido.

Desinstalación

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

En el panel, marque además el agente como Revoked para invalidar su token.

Siguiente paso

Crear su primer monitor LAN (ping, TCP, HTTP).

Primer monitor LAN