Linux (edge)

Edge-агент (ongrid-edge) запускается на каждом хосте, который вы хотите, чтобы Ongrid наблюдал. На Linux он устанавливается как systemd-сервис через единую curl-pipe команду. Агент — это единый статический Go-бинарь плюс четыре plugin-бинаря (promtail, node_exporter, process-exporter, otelcol-contrib).

Архитектуры

GOOS	GOARCH	Статус
linux	amd64	first-class
linux	arm64	first-class

Installer читает uname -m и выбирает соответствующий бинарь, скачиваемый из static-пути /edge/ manager'а:

x86_64 / amd64  → amd64
aarch64 / arm64 → arm64
anything else   → error: "unsupported arch"

Поддерживаемые дистрибутивы

Мы тестируем против того же набора, что и сервер. На практике всё, что имеет systemd 245+ (чтобы StateDirectory= работал) и glibc 2.31+, запускает агент нормально.

Дистрибутив	Тестируется на
Ubuntu	20.04 LTS, 22.04 LTS, 24.04 LTS
Debian	11 (bullseye), 12 (bookworm)
RHEL	8, 9
Rocky Linux	8, 9
AlmaLinux	8, 9
Amazon Linux	2023

Если ваш дистрибутив всё ещё использует sysvinit, OpenRC или runit, см. раздел «non-systemd» ниже.

Что installer кладёт

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 укладывает следующее на диск:

Путь	Назначение
/usr/local/bin/ongrid-edge	бинарь агента
/usr/local/lib/ongrid-edge/promtail	logs-плагин
/usr/local/lib/ongrid-edge/otelcol-contrib	traces-плагин
/usr/local/lib/ongrid-edge/node_exporter	host-metrics плагин
/usr/local/lib/ongrid-edge/process_exporter	proc-metrics плагин
/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh	ADR-024 staged-bundle swap-hook
/etc/ongrid-edge/ongrid-edge.env	access/secret key, cloud addr (mode 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	systemd-юнит
/var/lib/ongrid-edge/	StateDirectory: pending-upgrade staging, dedupe state
/var/log/ongrid-edge/	локальная log-директория (mode 750, owned by ongrid-edge)

Системный пользователь ongrid-edge создаётся (без shell, без home) и добавляется в две группы: adm (чтобы promtail мог читать /var/log/*, у которых mode 640 root:adm) и systemd-journal (чтобы мог читать journal).

Systemd-юнит

Дословно из deploy/install/edge/install.sh:

[Unit]
Description=ongrid edge agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/ongrid-edge/ongrid-edge.env
ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge
Restart=always
RestartSec=5
User=ongrid-edge
Group=ongrid-edge
AmbientCapabilities=CAP_NET_ADMIN
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
StateDirectory=ongrid-edge
StateDirectoryMode=0755
ReadWritePaths=/var/log/ongrid-edge
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Хайлайты, которые стоит знать:

• ProtectSystem=strict делает /usr, /boot и /etc read-only. Агент никогда не пишет вне StateDirectory= (/var/lib/ongrid-edge) или ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN — это то, что позволяет нескольким edge-скиллам делать read-only network introspection (ss -ntlp-style probes через nft list ruleset, conntrack reads). Сам агент никогда не открывает raw sockets.
• ExecStartPre=-+ (- игнорирует failure, + запускает как root) подключает ADR-024 staged-bundle swap. Если pending апгрейд был stage'нут на предыдущей загрузке, этот hook его применяет, потом выходит 0 в любом случае.
• StandardOutput=journal — контракт с promtail — собственные логи агента journald-readable, не на stdout-of-pid-1, и journal-source promtail их подхватывает.

Источник логов: journald, не syslog

Promtail сконфигурирован скрейпить journald (/run/log/journal для non-persistent, /var/log/journal для persistent). Он не tail'ит /var/log/syslog или /var/log/messages. Если ваш дистрибутив отгружает rsyslog, и вы отключили persistent journal, включите его:

mkdir -p /var/log/journal
systemd-tmpfiles --create --prefix /var/log/journal
systemctl restart systemd-journald

Без persistent journal logs-плагин всё ещё работает, но его история ограничена RAM (runtime journal на /run/log/journal).

Non-systemd Linux (sysvinit / OpenRC / runit)

Curl-pipe installer hard-fails на отсутствующий systemctl. Вы всё ещё можете запустить агента — положите бинарь в /usr/local/bin/ongrid-edge, напишите свой init-script, который экспортирует три обязательных env (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) и exec'ит бинарь, и вы готовы. Вы теряете:

• Auto-restart при падении (замените тем, что предлагает ваш init-система).
• Hook apply-pending-upgrade.sh, так что remote whole-bundle апгрейды (ADR-024) молча no-op'ят.
• Plugin-бинари (installer тоже их fetch'ит, см. выше).

Эти четыре plugin-бинаря также достижимы на https://<manager>/edge/<name>-linux-<arch>; скачайте их вручную в директорию по вашему выбору и направьте ONGRID_EDGE_PLUGIN_BIN_DIR на неё.

Capabilities, которые агенту НЕ нужны

• Ему не нужен root в рантайме (он работает как пользователь ongrid-edge).
• Ему не нужен CAP_SYS_ADMIN, CAP_NET_RAW или CAP_SYS_PTRACE. Если скилл просит что-либо из этого, cmdpolicy-гейт отказывает.
• Ему не нужен Docker. Plugin runtime — простой supervisor subprocess'ов, не контейнеры.

Порты, которые агент открывает

Порт	Bind	Зачем
9101	localhost	собственные /metrics и /healthz агента
9102	localhost	node_exporter (когда hostmetrics плагин включён)
9256	localhost	process-exporter (когда procmetrics плагин включён)

Только исходящее tunnel-соединение к порту 40012 manager'а должно проходить через ваш firewall. Никакие входящие порты не нужно открывать на edge-хосте.

Деинсталляция

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

Это останавливает сервис, удаляет бинарь, env-файл и systemd-юнит. Намеренно оставляет /var/log/ongrid-edge/ на месте — очистите вручную, если хотите, чтобы это ушло.