Linux (Edge)

Der Edge-Agent (ongrid-edge) läuft auf jedem Host, den Sie von Ongrid beobachten lassen wollen. Auf Linux installiert er sich als systemd-Service via einen einzigen curl-pipe-Befehl. Der Agent ist ein einzelnes statisches Go-Binary plus vier Plugin-Binaries (promtail, node_exporter, process-exporter, otelcol-contrib).

Architekturen

GOOS	GOARCH	Status
linux	amd64	erstklassig
linux	arm64	erstklassig

Der Installer liest uname -m und wählt das passende Binary, heruntergeladen vom statischen /edge/-Pfad des Managers:

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

Unterstützte Distributionen

Wir testen gegen die gleiche Menge wie der Server. In der Praxis läuft alles mit systemd 245+ (sodass StateDirectory= funktioniert) und glibc 2.31+ den Agenten gut.

Distribution	Getestet auf
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

Wenn Ihre Distribution noch sysvinit, OpenRC oder runit verwendet, siehe den „Non-systemd"-Abschnitt unten.

Was der Installer ablegt

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 legt Folgendes auf die Disk:

Pfad	Zweck
/usr/local/bin/ongrid-edge	das Agent-Binary
/usr/local/lib/ongrid-edge/promtail	Logs-Plugin
/usr/local/lib/ongrid-edge/otelcol-contrib	Traces-Plugin
/usr/local/lib/ongrid-edge/node_exporter	Host-Metriken-Plugin
/usr/local/lib/ongrid-edge/process_exporter	Proc-Metriken-Plugin
/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-Adresse (Mode 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	die systemd-Unit
/var/lib/ongrid-edge/	StateDirectory: Pending-Upgrade-Staging, Dedupe-State
/var/log/ongrid-edge/	lokales Log-Verzeichnis (Mode 750, Eigentümer ongrid-edge)

Ein System-User ongrid-edge wird erstellt (keine Shell, kein Home) und zu zwei Gruppen hinzugefügt: adm (damit promtail /var/log/* lesen kann, deren Mode 640 root:adm ist) und systemd-journal (damit es das Journal lesen kann).

Die systemd-Unit

Wörtlich aus 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, die zu kennen sich lohnt:

• ProtectSystem=strict macht /usr, /boot und /etc read-only. Der Agent schreibt nie außerhalb von StateDirectory= (/var/lib/ongrid-edge) oder ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN ist, was ein paar Edge-Skills Read-only-Netzwerk-Introspektion erlaubt (ss -ntlp-style Probes via nft list ruleset, conntrack-Reads). Der Agent selbst öffnet nie Raw-Sockets.
• ExecStartPre=-+ (das - ignoriert Fehlschlag, + läuft als root) verdrahtet den ADR-024 Staged-Bundle-Swap. Wenn ein ausstehendes Upgrade beim vorherigen Boot gelagert wurde, wendet dieser Hook es an, dann exitt er so oder so mit 0.
• StandardOutput=journal ist der Vertrag mit promtail — die eigenen Logs des Agenten sind journald-lesbar, nicht auf stdout-of-pid-1, und promtails journal-Quelle nimmt sie auf.

Log-Quelle: journald, nicht syslog

Promtail ist konfiguriert, journald zu scrapen (/run/log/journal für nicht-persistent, /var/log/journal für persistent). Es tailt nicht /var/log/syslog oder /var/log/messages. Wenn Ihre Distribution rsyslog ausliefert und Sie das persistente Journal deaktiviert haben, aktivieren Sie es:

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

Ohne ein persistentes Journal funktioniert das Logs-Plugin weiterhin, aber seine Historie ist von RAM begrenzt (das Runtime-Journal unter /run/log/journal).

Non-systemd-Linux (sysvinit / OpenRC / runit)

Der curl-pipe-Installer scheitert hart bei fehlendem systemctl. Sie können den Agenten weiterhin laufen lassen — legen Sie das Binary in /usr/local/bin/ongrid-edge, schreiben Sie Ihr eigenes Init-Skript, das die drei erforderlichen envs (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) exportiert und das Binary execkt, und Sie sind fertig. Sie verlieren:

• Auto-Restart bei Crash (ersetzen Sie mit dem, was Ihr Init-System bietet).
• Den apply-pending-upgrade.sh-Hook, sodass Remote-Whole-Bundle-Upgrades (ADR-024) stillschweigend no-op werden.
• Plugin-Binaries (der Installer fetcht die auch, siehe oben).

Diese vier Plugin-Binaries sind auch unter https://<manager>/edge/<name>-linux-<arch> erreichbar; laden Sie sie von Hand in ein Verzeichnis Ihrer Wahl herunter und richten Sie ONGRID_EDGE_PLUGIN_BIN_DIR darauf aus.

Capabilities, die der Agent NICHT braucht

• Er braucht zur Laufzeit kein root (er läuft als der ongrid-edge-User).
• Er braucht weder CAP_SYS_ADMIN, CAP_NET_RAW noch CAP_SYS_PTRACE. Wenn ein Skill nach einem davon fragt, verweigert das cmdpolicy-Gate.
• Er braucht kein Docker. Die Plugin-Runtime ist ein einfacher Subprocess-Supervisor, keine Container.

Ports, die der Agent öffnet

Port	Bind	Warum
9101	localhost	das eigene /metrics und /healthz des Agenten
9102	localhost	node_exporter (wenn das Hostmetrics-Plugin aktiviert ist)
9256	localhost	process-exporter (wenn das Procmetrics-Plugin aktiviert ist)

Nur die ausgehende Tunnel-Verbindung zum Port 40012 des Managers muss Ihre Firewall durchqueren. Keine eingehenden Ports müssen auf dem Edge-Host geöffnet werden.

Deinstallation

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

Das stoppt den Service, entfernt das Binary, die env-Datei und die systemd-Unit. Es lässt absichtlich /var/log/ongrid-edge/ an Ort und Stelle — räumen Sie es von Hand auf, wenn Sie es weg haben wollen.