Linux (edge)

L'agent edge (ongrid-edge) tourne sur chaque host que vous voulez qu'Ongrid observe. Sur Linux, il s'installe comme service systemd via une seule commande curl-pipe. L'agent est un binaire Go statique unique plus quatre binaires de plugin (promtail, node_exporter, process-exporter, otelcol-contrib).

Architectures

GOOS	GOARCH	Statut
linux	amd64	première classe
linux	arm64	première classe

L'installer lit uname -m et choisit le binaire matchant, téléchargé depuis le chemin statique /edge/ du manager :

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

Distributions supportées

Nous testons contre le même ensemble que pour le serveur. En pratique, tout ce qui a systemd 245+ (pour que StateDirectory= marche) et glibc 2.31+ fait tourner l'agent correctement.

Distribution	Testée sur
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 votre distribution utilise encore sysvinit, OpenRC ou runit, voir la section « non-systemd » ci-dessous.

Ce que l'installer dépose

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 dépose ce qui suit sur disque :

Chemin	Rôle
/usr/local/bin/ongrid-edge	le binaire agent
/usr/local/lib/ongrid-edge/promtail	plugin logs
/usr/local/lib/ongrid-edge/otelcol-contrib	plugin traces
/usr/local/lib/ongrid-edge/node_exporter	plugin host-metrics
/usr/local/lib/ongrid-edge/process_exporter	plugin proc-metrics
/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh	hook de swap staged-bundle ADR-024
/etc/ongrid-edge/ongrid-edge.env	clé access/secret, cloud addr (mode 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	l'unit systemd
/var/lib/ongrid-edge/	StateDirectory : staging d'upgrade en attente, état de dédoublonnage
/var/log/ongrid-edge/	répertoire de log local (mode 750, owned par ongrid-edge)

Un utilisateur système ongrid-edge est créé (pas de shell, pas de home) et ajouté à deux groupes : adm (pour que promtail puisse lire /var/log/* dont le mode est 640 root:adm) et systemd-journal (pour qu'il puisse lire le journal).

L'unit systemd

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

Points forts à connaître :

• ProtectSystem=strict rend /usr, /boot et /etc en lecture seule. L'agent n'écrit jamais hors de StateDirectory= (/var/lib/ongrid-edge) ou ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN est ce qui laisse quelques skills edge faire de l'introspection réseau en lecture seule (sondes style ss -ntlp via nft list ruleset, lectures conntrack). L'agent lui-même n'ouvre jamais de sockets bruts.
• ExecStartPre=-+ (le - ignore l'échec, le + exécute comme root) câble le swap staged-bundle ADR-024. Si un upgrade en attente a été staged au boot précédent, ce hook l'applique, puis sort 0 dans tous les cas.
• StandardOutput=journal est le contrat avec promtail — les propres logs de l'agent sont journald-lisibles, pas sur stdout-de-pid-1, et la source journal de promtail les récupère.

Source de logs : journald, pas syslog

Promtail est configuré pour scraper journald (/run/log/journal pour non-persistant, /var/log/journal pour persistant). Il ne tail pas /var/log/syslog ou /var/log/messages. Si votre distribution livre rsyslog et que vous avez désactivé le journal persistant, activez-le :

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

Sans journal persistant, le plugin logs marche encore mais son historique est borné par la RAM (le journal runtime à /run/log/journal).

Linux non-systemd (sysvinit / OpenRC / runit)

L'installer curl-pipe fail dur sur un systemctl manquant. Vous pouvez encore exécuter l'agent — déposez le binaire dans /usr/local/bin/ongrid-edge, écrivez votre propre script init qui exporte les trois envs requis (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) et exec le binaire, et c'est fait. Vous perdez :

• L'auto-restart sur crash (remplacez par ce que votre init system offre).
• Le hook apply-pending-upgrade.sh, donc les upgrades distantes de bundle entier (ADR-024) sont silencieusement no-op.
• Les binaires de plugin (l'installer les fetch aussi, voir ci-dessus).

Ces quatre binaires de plugin sont aussi joignables à https://<manager>/edge/<name>-linux-<arch> ; téléchargez-les à la main dans un répertoire de votre choix et pointez ONGRID_EDGE_PLUGIN_BIN_DIR dessus.

Capabilities dont l'agent N'A PAS besoin

• Il n'a pas besoin de root au runtime (il tourne comme utilisateur ongrid-edge).
• Il n'a pas besoin de CAP_SYS_ADMIN, CAP_NET_RAW ou CAP_SYS_PTRACE. Si un skill demande l'un d'eux, le gate cmdpolicy refuse.
• Il n'a pas besoin de Docker. Le runtime de plugin est un superviseur de sous-processus simple, pas des conteneurs.

Ports que l'agent ouvre

Port	Bind	Pourquoi
9101	localhost	/metrics et /healthz propres à l'agent
9102	localhost	node_exporter (quand le plugin hostmetrics est activé)
9256	localhost	process-exporter (quand le plugin procmetrics est activé)

Seule la connexion sortante du tunnel vers le port 40012 du manager a besoin de traverser votre firewall. Aucun port entrant n'a besoin d'être ouvert sur l'host edge.

Désinstaller

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

Ceci arrête le service, retire le binaire, le fichier env et l'unit systemd. Il laisse délibérément /var/log/ongrid-edge/ en place — purgez-le à la main si vous le voulez disparu.