Linux (edge)

O edge agent (ongrid-edge) roda em cada host que você quer que o Ongrid observe. No Linux, ele instala como um serviço systemd via um único comando curl-pipe. O agent é um único binário Go estático mais quatro binários de plugin (promtail, node_exporter, process-exporter, otelcol-contrib).

Arquiteturas

GOOS	GOARCH	Status
linux	amd64	first-class
linux	arm64	first-class

O instalador lê uname -m e escolhe o binário correspondente, baixado do path estático /edge/ do manager:

x86_64 / amd64  → amd64
aarch64 / arm64 → arm64
qualquer outro  → erro: "unsupported arch"

Distribuições suportadas

Testamos contra o mesmo conjunto que o servidor. Na prática qualquer coisa com systemd 245+ (para que StateDirectory= funcione) e glibc 2.31+ roda o agent bem.

Distribuição	Testado em
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

Se sua distribuição ainda usa sysvinit, OpenRC, ou runit, veja a seção "não-systemd" abaixo.

O que o instalador coloca

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 coloca o seguinte em disco:

Path	Propósito
/usr/local/bin/ongrid-edge	o binário do agent
/usr/local/lib/ongrid-edge/promtail	plugin de logs
/usr/local/lib/ongrid-edge/otelcol-contrib	plugin de traces
/usr/local/lib/ongrid-edge/node_exporter	plugin de host-metrics
/usr/local/lib/ongrid-edge/process_exporter	plugin de proc-metrics
/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh	hook de swap staged-bundle do ADR-024
/etc/ongrid-edge/ongrid-edge.env	access/secret key, cloud addr (mode 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	a unit systemd
/var/lib/ongrid-edge/	StateDirectory: staging de pending-upgrade, estado de dedupe
/var/log/ongrid-edge/	diretório local de logs (mode 750, owned por ongrid-edge)

Um user de sistema ongrid-edge é criado (sem shell, sem home) e adicionado a dois grupos: adm (para que o promtail possa ler /var/log/* cujo mode é 640 root:adm) e systemd-journal (para poder ler o journal).

A unit systemd

Verbatim de 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

Destaques que valem conhecer:

• ProtectSystem=strict torna /usr, /boot, e /etc read-only. O agent nunca escreve fora de StateDirectory= (/var/lib/ongrid-edge) ou ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN é o que permite a algumas skills do edge fazer network introspection read-only (probes estilo ss -ntlp via nft list ruleset, leituras de conntrack). O próprio agent nunca abre raw sockets.
• ExecStartPre=-+ (o - ignora falha, + roda como root) conecta o swap de staged-bundle do ADR-024. Se um upgrade pending foi staged no boot anterior, esse hook o aplica, então sai 0 de qualquer jeito.
• StandardOutput=journal é o contrato com o promtail — os próprios logs do agent são journald-readable, não no stdout-do-pid-1, e a fonte journal do promtail os pega.

Fonte de log: journald, não syslog

O Promtail é configurado para raspar journald (/run/log/journal para não-persistente, /var/log/journal para persistente). Ele não faz tail em /var/log/syslog ou /var/log/messages. Se sua distribuição distribui rsyslog e você desabilitou o journal persistente, habilite:

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

Sem um journal persistente o plugin de logs ainda funciona mas seu histórico é limitado por RAM (o journal de runtime em /run/log/journal).

Linux não-systemd (sysvinit / OpenRC / runit)

O instalador curl-pipe falha duro num systemctl faltante. Você ainda pode rodar o agent — coloque o binário em /usr/local/bin/ongrid-edge, escreva seu próprio script de init que exporta as três envs requeridas (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) e executa o binário, e está pronto. Você perde:

• Auto-restart em crash (substitua pelo que seu sistema de init oferece).
• O hook apply-pending-upgrade.sh, então upgrades remotos de whole-bundle (ADR-024) silenciosamente no-op.
• Binários de plugin (o instalador também os fetcha, veja acima).

Esses quatro binários de plugin também estão alcançáveis em https://<manager>/edge/<name>-linux-<arch>; baixe-os à mão para um diretório de sua escolha e aponte ONGRID_EDGE_PLUGIN_BIN_DIR para ele.

Capabilities que o agent NÃO precisa

• Ele não precisa de root em runtime (roda como o user ongrid-edge).
• Ele não precisa de CAP_SYS_ADMIN, CAP_NET_RAW, ou CAP_SYS_PTRACE. Se uma skill pedir qualquer um desses, o gate da cmdpolicy recusa.
• Ele não precisa de Docker. O plugin runtime é um supervisor de subprocesso puro, não containers.

Portas que o agent abre

Porta	Bind	Por quê
9101	localhost	o próprio /metrics e /healthz do agent
9102	localhost	node_exporter (quando o plugin de hostmetrics está habilitado)
9256	localhost	process-exporter (quando o plugin de procmetrics está habilitado)

Apenas a conexão de tunnel outbound à porta 40012 do manager precisa atravessar seu firewall. Nenhuma porta inbound precisa ser aberta no host do edge.

Desinstalando

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

Isso para o serviço, remove o binário, o arquivo env, e a unit systemd. Deliberadamente deixa /var/log/ongrid-edge/ no lugar — purge à mão se quiser que se vá.