Instalação agent (systemd / Docker)

O agente LAN é um pequeno processo Python que corre no seu dispositivo Linux dentro da rede interna e verifica serviços inacessíveis a partir da internet (DNS interno, intranet, ERP, NAS, impressoras). Comunica para o exterior através de HTTPS, pelo que não precisa de quaisquer portas abertas para o interior da rede.

Em resumo: Crie um agente no painel, copie o token e execute um único comando de instalação no dispositivo de destino. Todo o processo demora 2 a 3 minutos.

O que vai precisar

Qualquer Linux com acesso root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Arquitetura x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) ou armv6l (RPi Zero)
Ligação HTTPS de saída para epulz.io (porta 443)
Python 3.8 ou mais recente (se faltar, o instalador adiciona-o a partir do gestor de pacotes)

O agente ocupa cerca de 20 MB de RAM e menos de 1 % de CPU em repouso. Funciona também num contentor LXC, numa máquina virtual (Proxmox, VMware) ou num contentor Docker. Além do systemd, suporta também o OpenRC (Alpine).

Totalmente auditável: todo o agente é um único ficheiro Python (~600 linhas, apenas biblioteca padrão) e o instalador é um script público. Antes de o executar pode ler cada linha: epulzio-agent.py e install-agent.sh.

1. Crie um agente e copie o token

Abra Painel - Agentes LAN.
Introduza um nome compreensível (por exemplo "Sala de servidores Lisboa" ou "RPi na loja") e clique em + Criar agente.
O painel mostra o token do agente (epulzio_...) e comandos de instalação prontos a copiar.

O token é mostrado apenas uma vez. Copie-o de imediato. Não o partilhe publicamente nem o publique no GitHub. Se o perder ou ele vazar, revogue o agente no painel (Revoke) e crie um novo.

2. Execute o comando de instalação

No dispositivo de destino, num terminal (substitua o token pelo seu):

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

Abordagem mais prudente (recomendada na primeira instalação): primeiro descarregue o script e leia-o:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # leia o que faz (1 min)
sudo bash install-agent.sh epulzio_SEU_TOKEN

O instalador automaticamente:

Deteta a arquitetura e a distribuição (apt / dnf / apk / pacman / zypper)
Verifica a presença do Python 3.8+ e da ferramenta ping, instalando-os se necessário
Testa a ligação a epulz.io
Descarrega o agente para /opt/epulzio-agent/
Cria o serviço epulzio-agent (systemd, no Alpine OpenRC) e inicia-o
Ativa o arranque automático no reinício do sistema

Toda a instalação demora cerca de 30 segundos.

3. Verifique que o agente está a correr

Estado do serviço no dispositivo:

sudo systemctl status epulzio-agent

Deverá ver active (running).

Lista de agentes LAN com estado online no painel da ePulz.io — Painel - Agentes LAN: estado, último contacto e versão do agente

Em Painel - Agentes LAN o estado aparece em 30 segundos:

online - o último sinal de vida (heartbeat) chegou há menos de 2 minutos
marca temporal - o último heartbeat foi há 2 a 10 minutos
offline - o último heartbeat tem mais de 10 minutos (o alerta chega já após 5 minutos de silêncio)

Variante via Docker

Se não tiver systemd (TrueNAS, Synology, Unraid, k3s) ou preferir um contentor, use o comando do painel:

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

A opção --network host é importante - o agente tem de ver a sua rede LAN, não apenas a bridge interna do Docker. Em cada reinício do contentor é descarregada a versão atual do agente.

macOS e Windows

Para 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_SEU_TOKEN

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

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

Resolução de problemas

O instalador reporta "Missing agent token"

Falta o token ao comando. Execute-o com o token no fim: ... | sudo bash -s epulzio_SEU_TOKEN.

O instalador reporta "must run as root"

Execute-o através de sudo; o root só é necessário para a instalação (serviço systemd, escrita em /opt).

"Cannot reach epulz.io"

O dispositivo não tem ligação HTTPS de saída. Teste-a manualmente com curl https://epulz.io/health. Se falhar, verifique a firewall, o DNS e o NAT.

"Python 3.8+ required"

Sistema muito antigo. Atualize a distribuição ou instale um Python mais recente (no Debian, por exemplo apt install python3.9 a partir dos backports).

"Neither systemd nor OpenRC detected"

Sistema sem um sistema init suportado. Use a variante Docker acima.

O agente permanece offline no painel mesmo após 2 minutos

Veja os logs: sudo journalctl -u epulzio-agent -n 50.
Causas mais frequentes: token colado incorretamente (verifique se foi copiado por inteiro, incluindo o prefixo epulzio_), HTTPS bloqueado na firewall ou relógio do sistema incorreto (verifique-o com o comando date - a verificação do certificado SSL requer a hora correta).

Atualização do agente

Execute novamente o mesmo comando de instalação com o mesmo token. O instalador sobrescreve os ficheiros em /opt/epulzio-agent/ e reinicia o serviço, o token mantém-se válido.

Desinstalação

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

No painel, marque adicionalmente o agente como Revoked para invalidar o seu token.

Próximo passo

Criar o seu primeiro monitor LAN (ping, TCP, HTTP).

Primeiro monitor LAN