Linux (edge)

El agente edge (ongrid-edge) corre en cada host que quieras que Ongrid observe. En Linux, se instala como un servicio systemd vía un único comando curl-pipe. El agente es un único binario Go estático más cuatro binarios de plugin (promtail, node_exporter, process-exporter, otelcol-contrib).

Arquitecturas

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

El installer lee uname -m y elige el binario matcheante, descargado del path estático /edge/ del manager:

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

Distribuciones soportadas

Testeamos contra el mismo set que el server. En la práctica cualquier cosa con systemd 245+ (para que StateDirectory= funcione) y glibc 2.31+ corre el agente bien.

Distribución	Testeado en
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

Si tu distribución sigue usando sysvinit, OpenRC o runit, ver la sección "non-systemd" abajo.

Qué deja el 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 deja lo siguiente en disco:

Ruta	Propósito
/usr/local/bin/ongrid-edge	el binario del agente
/usr/local/lib/ongrid-edge/promtail	plugin de logs
/usr/local/lib/ongrid-edge/otelcol-contrib	plugin de trazas
/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 del bundle staged de ADR-024
/etc/ongrid-edge/ongrid-edge.env	access/secret key, cloud addr (modo 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	la unit systemd
/var/lib/ongrid-edge/	StateDirectory: staging de pending-upgrade, estado de dedupe
/var/log/ongrid-edge/	directorio de logs local (modo 750, owned by ongrid-edge)

Se crea un usuario de sistema ongrid-edge (sin shell, sin home) y se añade a dos grupos: adm (para que promtail pueda leer /var/log/* cuyo modo es 640 root:adm) y systemd-journal (para que pueda leer el journal).

La 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

Highlights que vale conocer:

• ProtectSystem=strict hace /usr, /boot y /etc read-only. El agente nunca escribe fuera de StateDirectory= (/var/lib/ongrid-edge) o ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN es lo que permite a algunos skills de edge hacer introspección read-only de red (probes estilo ss -ntlp vía nft list ruleset, reads de conntrack). El propio agente nunca abre raw sockets.
• ExecStartPre=-+ (el - ignora fallo, el + corre como root) cablea el swap de bundle staged de ADR-024. Si un upgrade pendiente fue staged en el boot previo, este hook lo aplica, luego sale 0 de cualquier forma.
• StandardOutput=journal es el contrato con promtail — los propios logs del agente son journald-legibles, no en stdout-of-pid-1, y el source journal de promtail los recoge.

Log source: journald, no syslog

Promtail está configurado para scrapear journald (/run/log/journal para non-persistent, /var/log/journal para persistent). No sigue /var/log/syslog o /var/log/messages. Si tu distribución trae rsyslog y has deshabilitado el journal persistente, habilítalo:

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

Sin un journal persistente el plugin de logs sigue funcionando pero su historia está acotada por RAM (el journal de runtime en /run/log/journal).

Linux non-systemd (sysvinit / OpenRC / runit)

El installer curl-pipe falla duro ante un systemctl faltante. Aún puedes correr el agente — deja el binario en /usr/local/bin/ongrid-edge, escribe tu propio script init que exporte los tres envs requeridos (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) y haga exec del binario, y terminaste. Pierdes:

• Auto-restart ante crash (reemplaza con lo que tu sistema init ofrezca).
• El hook apply-pending-upgrade.sh, así que los upgrades remotos de whole-bundle (ADR-024) hacen silenciosamente no-op.
• Los binarios de plugin (el installer también fetchea esos, ver arriba).

Esos cuatro binarios de plugin también son alcanzables en https://<manager>/edge/<name>-linux-<arch>; descárgalos a mano a un directorio de tu elección y apunta ONGRID_EDGE_PLUGIN_BIN_DIR a él.

Capabilities que el agente NO necesita

• No necesita root en runtime (corre como el usuario ongrid-edge).
• No necesita CAP_SYS_ADMIN, CAP_NET_RAW o CAP_SYS_PTRACE. Si un skill pide alguno, el gate cmdpolicy rehúsa.
• No necesita Docker. El runtime de plugin es un supervisor de subproceso plano, no contenedores.

Puertos que abre el agente

Puerto	Bind	Por qué
9101	localhost	el propio /metrics y /healthz del agente
9102	localhost	node_exporter (cuando el plugin hostmetrics está habilitado)
9256	localhost	process-exporter (cuando el plugin procmetrics está habilitado)

Solo la conexión saliente del túnel al puerto 40012 del manager necesita atravesar tu firewall. No se necesitan puertos entrantes abiertos en el host edge.

Desinstalando

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

Esto detiene el servicio, elimina el binario, el archivo env y la unit systemd. Deliberadamente deja /var/log/ongrid-edge/ en su lugar — púrgalo a mano si lo quieres ido.