Установка агента (systemd / Docker)

LAN-агент - это небольшой процесс на Python, который работает на вашем Linux-устройстве во внутренней сети и проверяет службы, недоступные из интернета (внутренний DNS, интранет, ERP, NAS, принтеры). Он обращается наружу по HTTPS, поэтому не требует никаких открытых портов внутрь сети.

Вкратце: Создайте агента в панели управления, скопируйте токен и выполните одну команду установки на целевом устройстве. Весь процесс занимает 2-3 минуты.

Что вам понадобится

Любой Linux с доступом root (Debian, Ubuntu, Raspberry Pi OS, Fedora, Alma/Rocky, Arch, openSUSE, Alpine)
Архитектура x86_64, aarch64 (Raspberry Pi 4/5), armv7l (Raspberry Pi 3) или armv6l (RPi Zero)
Исходящее HTTPS-соединение к epulz.io (порт 443)
Python 3.8 или новее (если его нет, установщик добавит его из менеджера пакетов)

Агент занимает примерно 20 МБ ОЗУ и в состоянии покоя менее 1 % ЦП. Он также работает в контейнере LXC, в виртуальной машине (Proxmox, VMware) или в контейнере Docker. Помимо systemd он поддерживает и OpenRC (Alpine).

Полностью проверяемый: весь агент - это один файл на Python (~600 строк, только стандартная библиотека), а установщик - публичный скрипт. Перед запуском вы можете прочитать каждую строку: epulzio-agent.py и install-agent.sh.

1. Создайте агента и скопируйте токен

Откройте Панель - LAN-агенты.
Введите понятное имя (например, "Серверная Москва" или "RPi в магазине") и нажмите + Создать агента.
Панель отобразит токен агента (epulzio_...) и готовые команды установки для копирования.

Токен отображается только один раз. Скопируйте его сразу. Не передавайте его публично и не публикуйте на GitHub. Если вы его потеряете или он утечёт, отзовите агента в панели (Revoke) и создайте нового.

2. Выполните команду установки

На целевом устройстве в терминале (токен замените своим):

curl -fsSL https://epulz.io/install-agent.sh | sudo bash -s epulzio_ВАШ_ТОКЕН

Более осторожный подход (рекомендуем при первой установке): сначала скачайте скрипт и прочитайте его:

curl -fsSL https://epulz.io/install-agent.sh -o install-agent.sh
less install-agent.sh        # прочитайте, что он делает (1 мин)
sudo bash install-agent.sh epulzio_ВАШ_ТОКЕН

Установщик автоматически:

Распознаёт архитектуру и дистрибутив (apt / dnf / apk / pacman / zypper)
Проверяет наличие Python 3.8+ и утилиты ping, при необходимости устанавливает их
Проверяет соединение с epulz.io
Загружает агента в /opt/epulzio-agent/
Создаёт службу epulzio-agent (systemd, на Alpine - OpenRC) и запускает её
Включает автоматический запуск при перезагрузке системы

Вся установка занимает примерно 30 секунд.

3. Убедитесь, что агент работает

Состояние службы на устройстве:

sudo systemctl status epulzio-agent

Вы должны увидеть active (running).

Список LAN-агентов со статусом онлайн в панели ePulz.io — Панель - LAN-агенты: статус, последний контакт и версия агента

В Панель - LAN-агенты статус появится в течение 30 секунд:

онлайн - последний сигнал жизни (heartbeat) пришёл менее 2 минут назад
метка времени - последний heartbeat был 2-10 минут назад
офлайн - последний heartbeat старше 10 минут (уведомление приходит уже после 5 минут тишины)

Вариант через Docker

Если у вас нет systemd (TrueNAS, Synology, Unraid, k3s) или вы предпочитаете контейнер, используйте команду из панели:

docker run -d --name epulzio-agent --restart unless-stopped \
  --network host \
  -e EPULZIO_AGENT_TOKEN=epulzio_ВАШ_ТОКЕН \
  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"

Параметр --network host важен - агент должен видеть вашу сеть LAN, а не только внутренний мост Docker. При каждом перезапуске контейнера загружается актуальная версия агента.

macOS и Windows

Для macOS (10.15+, Intel и Apple Silicon):

curl -fsSL https://epulz.io/install-agent-macos.sh -o install-agent-macos.sh
sudo bash install-agent-macos.sh epulzio_ВАШ_ТОКЕН

Для Windows (10+ / Server 2016+, PowerShell от имени администратора):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
$env:EPULZIO_AGENT_TOKEN="epulzio_ВАШ_ТОКЕН"; iwr -useb https://epulz.io/install-agent.ps1 | iex

Устранение неполадок

Установщик сообщает "Missing agent token"

В команде отсутствует токен. Запустите её с токеном в конце: ... | sudo bash -s epulzio_ВАШ_ТОКЕН.

Установщик сообщает "must run as root"

Запустите её через sudo; root нужен только для установки (служба systemd, запись в /opt).

"Cannot reach epulz.io"

У устройства нет исходящего HTTPS-соединения. Проверьте вручную командой curl https://epulz.io/health. Если не получится, проверьте брандмауэр, DNS и NAT.

"Python 3.8+ required"

Очень старая система. Обновите дистрибутив или установите более новый Python (на Debian, например, apt install python3.9 из backports).

"Neither systemd nor OpenRC detected"

Система без поддерживаемой системы инициализации. Используйте вариант с Docker выше.

Агент остаётся офлайн в панели даже через 2 минуты

Посмотрите логи: sudo journalctl -u epulzio-agent -n 50.
Самые частые причины: неправильно вставленный токен (проверьте, что он скопирован целиком, включая префикс epulzio_), HTTPS заблокирован на брандмауэре или неверное системное время (проверьте его командой date - проверка SSL-сертификата требует правильного времени).

Обновление агента

Выполните ту же команду установки снова с тем же токеном. Установщик перезапишет файлы в /opt/epulzio-agent/ и перезапустит службу, токен остаётся действительным.

Удаление

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

В панели дополнительно отметьте агента как Revoked, чтобы аннулировать его токен.

Следующий шаг

Создание первого LAN-монитора (ping, TCP, HTTP).

Первый LAN-монитор