Instalacja agenta (systemd / Docker)

Agent LAN to mały proces Pythona, który działa na Twoim urządzeniu z systemem Linux w sieci wewnętrznej i sprawdza usługi, do których nie da się dotrzeć z internetu (wewnętrzny DNS, intranet, ERP, NAS, drukarki). Komunikuje się na zewnątrz przez HTTPS, więc nie potrzebuje żadnych otwartych portów do wnętrza sieci.

W skrócie: Utwórz agenta w panelu, skopiuj token i uruchom jedno polecenie instalacyjne na urządzeniu docelowym. Cały proces zajmuje 2 do 3 minut.

Czego będziesz potrzebować

Dowolny Linux z dostępem root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Architektura x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) lub armv6l (RPi Zero)
Wychodzące połączenie HTTPS do epulz.io (port 443)
Python 3.8 lub nowszy (jeśli go brakuje, instalator doinstaluje go z menedżera pakietów)

Agent zajmuje około 20 MB RAM i w stanie spoczynku mniej niż 1 % CPU. Działa także w kontenerze LXC, na maszynie wirtualnej (Proxmox, VMware) lub w kontenerze Docker. Oprócz systemd obsługuje również OpenRC (Alpine).

W pełni audytowalny: cały agent to jeden plik Pythona (~600 wierszy, tylko biblioteka standardowa), a instalator to publiczny skrypt. Przed uruchomieniem możesz przeczytać każdy wiersz: epulzio-agent.py i install-agent.sh.

1. Utwórz agenta i skopiuj token

Otwórz Panel - Agenci LAN.
Wpisz zrozumiałą nazwę (na przykład "Serwerownia Warszawa" lub "RPi w sklepie") i kliknij + Utwórz agenta.
Panel wyświetli token agenta (epulzio_...) oraz gotowe polecenia instalacyjne do skopiowania.

Token wyświetla się tylko raz. Skopiuj go od razu. Nie udostępniaj go publicznie ani nie publikuj na GitHubie. Jeśli go zgubisz lub wycieknie, unieważnij agenta w panelu (Revoke) i utwórz nowego.

2. Uruchom polecenie instalacyjne

Na urządzeniu docelowym w terminalu (token zastąp swoim):

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

Ostrożniejsze podejście (zalecane przy pierwszej instalacji): najpierw pobierz skrypt i przeczytaj go:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # przeczytaj, co robi (1 min)
sudo bash install-agent.sh epulzio_TWOJ_TOKEN

Instalator automatycznie:

Rozpoznaje architekturę i dystrybucję (apt / dnf / apk / pacman / zypper)
Sprawdza obecność Pythona 3.8+ oraz narzędzia ping, w razie potrzeby je doinstalowuje
Testuje połączenie z epulz.io
Pobiera agenta do /opt/epulzio-agent/
Tworzy usługę epulzio-agent (systemd, na Alpine OpenRC) i uruchamia ją
Włącza automatyczne uruchamianie po restarcie systemu

Cała instalacja trwa około 30 sekund.

3. Sprawdź, czy agent działa

Stan usługi na urządzeniu:

sudo systemctl status epulzio-agent

Powinieneś zobaczyć active (running).

Lista agentów LAN ze stanem online w panelu ePulz.io — Panel - Agenci LAN: stan, ostatni kontakt i wersja agenta

W Panel - Agenci LAN w ciągu 30 sekund pojawi się stan:

online - ostatni sygnał życia (heartbeat) przyszedł mniej niż 2 minuty temu
znacznik czasu - ostatni heartbeat 2 do 10 minut temu
offline - ostatni heartbeat starszy niż 10 minut (powiadomienie przychodzi już po 5 minutach ciszy)

Wariant przez Docker

Jeśli nie masz systemd (TrueNAS, Synology, Unraid, k3s) lub wolisz kontener, użyj polecenia z panelu:

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

Przełącznik --network host jest ważny - agent musi widzieć Twoją sieć LAN, nie tylko wewnętrzny mostek Docker. Przy każdym restarcie kontenera pobierana jest aktualna wersja agenta.

macOS i Windows

Dla macOS (10.15+, Intel i Apple Silicon):

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

Dla Windows (10+ / Server 2016+, PowerShell jako administrator):

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

Rozwiązywanie problemów

Instalator zgłasza "Missing agent token"

Poleceniu brakuje tokena. Uruchom je z tokenem na końcu: ... | sudo bash -s epulzio_TWOJ_TOKEN.

Instalator zgłasza "must run as root"

Uruchom je przez sudo, root jest potrzebny tylko do instalacji (usługa systemd, zapis do /opt).

"Cannot reach epulz.io"

Urządzenie nie ma wychodzącego połączenia HTTPS. Przetestuj je ręcznie poleceniem curl https://epulz.io/health. Jeśli się nie powiedzie, sprawdź firewall, DNS i NAT.

"Python 3.8+ required"

Bardzo stary system. Zaktualizuj dystrybucję lub doinstaluj nowszego Pythona (na Debianie na przykład apt install python3.9 z backports).

"Neither systemd nor OpenRC detected"

System bez obsługiwanego systemu init. Użyj wariantu Docker powyżej.

Agent pozostaje w panelu offline nawet po 2 minutach

Sprawdź logi: sudo journalctl -u epulzio-agent -n 50.
Najczęstsze przyczyny: nieprawidłowo wklejony token (sprawdź, czy skopiował się cały wraz z prefiksem epulzio_), HTTPS zablokowany na firewallu lub nieprawidłowy czas systemowy (sprawdź go poleceniem date - weryfikacja certyfikatu SSL wymaga poprawnego czasu).

Aktualizacja agenta

Uruchom to samo polecenie instalacyjne ponownie z tym samym tokenem. Instalator nadpisze pliki w /opt/epulzio-agent/ i zrestartuje usługę, token pozostaje ważny.

Odinstalowanie

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

W panelu dodatkowo oznacz agenta jako Revoked, aby unieważnić jego token.

Następny krok

Utworzenie pierwszego monitora LAN (ping, TCP, HTTP).

Pierwszy monitor LAN