diff --git a/CHANGELOG.md b/CHANGELOG.md index 61ab7cd..2865941 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,41 @@ All notable changes to **felhom-agent** are recorded here. Update on every code change that gets pushed. +## v0.43.0 — canonical systemd unit + binary published to Gitea (BUNDLE slice) (2026-06-28) + +Day-0 no longer needs a hand-installed agent. The agent binary is now PUBLISHED to Gitea as a generic +package and the host-bootstrap script fetches → verifies (sha256 vs the hub-vouched manifest) → +installs it. This commit adds the **canonical systemd unit** (was hand-made per host) and the publish +tooling; the binary itself is a version-only rebuild (no behavioural change). + +- **`configs/felhom-agent.service` (NEW, canonical):** `User=felhom-agent`/`Group=felhom-agent` (the + documented non-root production model — README "Process model"; `privileged.mode: "sudo"` + the + narrow sudoers allowlist), `ExecStart=/usr/local/bin/felhom-agent --config + /etc/felhom-agent/agent.json`, `After=network-online.target pve-cluster.service pveproxy.service`, + `Restart=on-failure`, `StateDirectory=felhom-agent`. **Deliberately NO sandboxing**, with the reasons + documented inline: + - `NoNewPrivileges` is NOT set — it would block the setuid `sudo` the agent needs for every host-root + op (mount/format/pct/dnsmasq), silently killing all privileged capability. + - NO mount-namespacing hardening (`ProtectHome`/`ProtectSystem`/`PrivateTmp`/…) — any of those give the + unit a PRIVATE mount namespace, and the intermediary-mount drive model relies on `mount + --make-shared`/`--bind` propagating into the running guest; in a private namespace every drive + enrollment would silently break. The agent shares the host mount namespace; the sudoers allowlist is + the security boundary. +- **`scripts/publish-agent.sh` (NEW):** builds (optional) + PUTs the binary to + `/api/packages/admin/generic/felhom-agent//felhom-agent` (Gitea generic), prints + `AGENT_VERSION` + `AGENT_SHA256`, and does a GET round-trip (re-fetch + sha256 re-check) to prove the + artifact is fetchable + intact. Pinned to a version (never `:latest`); idempotent (delete-then-PUT); + asserts the binary's `--version` matches the publish version. Creds via `GITEA_USER/GITEA_TOKEN` + (falls back to `REGISTRY_USER/REGISTRY_TOKEN`). +- **`configs/build-golden.sh`:** after the vzdump archive is produced, computes its sha256 and PUTs it + to `/api/packages/admin/generic/felhom-golden//golden.tar.zst` (`` = + the baked controller version), printing `GOLDEN_VERSION` + `GOLDEN_SHA256`. Opt-in (only when the + Gitea creds are set); the local-golden auto-discovery stays as a fallback. +- **`cmd/felhom-agent/main.go`:** `version` 0.42.0 → 0.43.0. +- The operator records the printed agent + golden version+sha256 in the hub (Configs → "Day-0 + artifacts"); the host-bootstrap script verifies fetched artifacts against those before installing. +- `go build/vet/test ./...` green. + ## build-golden.sh — default controller image bumped to current; golden rebuilt at 0.85.1 (2026-06-27) **Operational + a default fix (no agent binary change — version stays v0.42.0).** diff --git a/README.md b/README.md index 9770c75..6d19acd 100644 --- a/README.md +++ b/README.md @@ -205,11 +205,27 @@ so cleanly if the token/endpoint isn't configured. `--selftest=task --vmid N` (explicitly gated) exercises `WaitTask` on a **reversible** op (snapshot → rollback → delete-snapshot) against guest `N`. Default `--selftest` never mutates. -## Process model (proposed, not finalized — see 03 §3/§12) +## Process model -Native Go binary, systemd service, **non-root** service user holding the scoped token, with a -**narrow sudoers allowlist** for the three fenced ops. `privileged.mode: "sudo"` matches this; -`"direct"` is for dev/CI where the agent is already root. +Native Go binary, systemd service, **non-root** `felhom-agent` service user holding the scoped token, +with a **narrow sudoers allowlist** for the fenced host-root ops. `privileged.mode: "sudo"` matches +this; `"direct"` is for dev/CI where the agent is already root. + +The canonical artifacts (BUNDLE slice): +- **`configs/felhom-agent.service`** — the canonical unit (`User=felhom-agent`, + `ExecStart=/usr/local/bin/felhom-agent --config /etc/felhom-agent/agent.json`). It deliberately sets + **no** `NoNewPrivileges` and **no** mount-namespacing hardening (`ProtectHome`/`PrivateTmp`/…): the + first would block the `sudo` the agent needs, the second would put the agent in a private mount + namespace so its `mount --bind` drive enrollments wouldn't propagate into the running guest. The + security boundary is the sudoers allowlist, not systemd sandboxing. +- **`configs/felhom-agent.sudoers`** → `/etc/sudoers.d/felhom-agent` (0440, `visudo -cf`-validated). +- **`scripts/publish-agent.sh`** publishes the binary to Gitea as a generic package + (`/api/packages/admin/generic/felhom-agent//felhom-agent`), printing the sha256 the operator + records in the hub artifact manifest. + +**Install is automated.** The host-bootstrap script (`felhom.eu/scripts/felhom-host-install.sh`) fetches +the binary from Gitea, verifies its sha256 against the hub-vouched manifest, then installs the user + +binary + sudoers + unit + config — no manual agent install step. ## Test diff --git a/cmd/felhom-agent/main.go b/cmd/felhom-agent/main.go index 49b4cc8..30804c5 100644 --- a/cmd/felhom-agent/main.go +++ b/cmd/felhom-agent/main.go @@ -44,7 +44,7 @@ import ( // version is the agent version. Overridable at build time with // -ldflags "-X main.version="; defaults to the in-repo CHANGELOG version. -var version = "0.42.0" +var version = "0.43.0" // runGuestHook is the PVE pre-start hook body (`felhom-agent guest-hook `). On the // pre-start phase it creates placeholder dirs for any absent bind-mount source so the guest always boots diff --git a/configs/build-golden.sh b/configs/build-golden.sh index 2198d8f..72597b5 100644 --- a/configs/build-golden.sh +++ b/configs/build-golden.sh @@ -269,4 +269,50 @@ grep -q "including mount point mp1" /tmp/golden-vzdump.log \ VOLID=$(pvesm list "$ARCHIVE_STORAGE" --content backup 2>/dev/null | awk -v v="$VMID" '$1 ~ ("vzdump-lxc-" v "-") {print $1}' | sort | tail -1) echo "[golden] DONE. golden archive volid: ${VOLID:-} (rootfs ${OS_SIZE_GB}G + Docker-data ${GOLDEN_DOCKER_GB}G + user-data ${GOLDEN_SYSDATA_GB}G, all in the archive)" + +#------------------------------------------------------------------------------- +# Publish to Gitea (BUNDLE slice) — make this golden fetchable by the host-bootstrap script. +#------------------------------------------------------------------------------- +# The host-install script fetches the golden from Gitea +# (/api/packages/admin/generic/felhom-golden//golden.tar.zst) and verifies its sha256 +# against the hub-vouched artifact manifest before importing it. = the BAKED +# controller version (so the golden's published version tracks what it ships). Publishing is OPT-IN: +# only runs when GITEA_USER + GITEA_TOKEN (or REGISTRY_USER/REGISTRY_TOKEN) are set. The local-golden +# auto-discovery in the host-install script stays as a fallback either way. +GITEA_BASE="${GITEA_BASE:-https://gitea.dooplex.hu}" +GITEA_OWNER="${GITEA_OWNER:-admin}" +PUB_USER="${GITEA_USER:-${REGISTRY_USER:-}}" +PUB_TOKEN="${GITEA_TOKEN:-${REGISTRY_TOKEN:-}}" +# Golden version = the baked controller tag's version (strip the image path + any leading 'v'). +GOLDEN_VERSION="${GOLDEN_VERSION:-${CONTROLLER_IMAGE##*:}}"; GOLDEN_VERSION="${GOLDEN_VERSION#v}" + +if [ -z "$VOLID" ]; then + echo "[golden] WARN: could not resolve the archive volid — skipping Gitea publish." +elif [ -z "$PUB_USER" ] || [ -z "$PUB_TOKEN" ]; then + echo "[golden] Gitea publish SKIPPED (set GITEA_USER+GITEA_TOKEN or REGISTRY_USER+REGISTRY_TOKEN to enable)." + echo "[golden] would publish version=$GOLDEN_VERSION from volid $VOLID" +else + # Resolve the archive's on-disk path (pvesm path turns a volid into a filesystem path). + ARCHIVE_PATH="$(pvesm path "$VOLID" 2>/dev/null || true)" + if [ -z "$ARCHIVE_PATH" ] || [ ! -f "$ARCHIVE_PATH" ]; then + echo "[golden] WARN: cannot resolve archive path for $VOLID — skipping publish." + else + GOLDEN_SHA256="$(sha256sum "$ARCHIVE_PATH" | awk '{print $1}')" + PUB_URL="${GITEA_BASE}/api/packages/${GITEA_OWNER}/generic/felhom-golden/${GOLDEN_VERSION}/golden.tar.zst" + echo "[golden] publishing golden ($(wc -c < "$ARCHIVE_PATH") bytes, sha256 ${GOLDEN_SHA256:0:16}…) → $PUB_URL" + # Delete-then-PUT so re-publishing the same version overwrites cleanly (idempotent). + dcode="$(curl -fsS -o /dev/null -w '%{http_code}' -u "${PUB_USER}:${PUB_TOKEN}" -X DELETE "$PUB_URL" 2>/dev/null || true)" + echo "[golden] pre-delete existing: HTTP ${dcode} (404/204 expected)" + ucode="$(curl -sS -o /dev/null -w '%{http_code}' -u "${PUB_USER}:${PUB_TOKEN}" -X PUT --upload-file "$ARCHIVE_PATH" "$PUB_URL")" + if [ "$ucode" = "201" ] || [ "$ucode" = "200" ]; then + echo "[golden] upload OK (HTTP $ucode)" + echo "GOLDEN_VERSION=${GOLDEN_VERSION}" + echo "GOLDEN_SHA256=${GOLDEN_SHA256}" + echo "[golden] Record in the hub operator UI (Configs → Day-0 artifacts): golden ${GOLDEN_VERSION} / ${GOLDEN_SHA256}" + else + echo "[golden] WARN: golden upload failed (HTTP $ucode) — the local archive is still usable via auto-discovery." + fi + fi +fi + echo "[golden] (the build guest $VMID is stopped; destroy it with: pct destroy $VMID --purge)" diff --git a/configs/felhom-agent.service b/configs/felhom-agent.service new file mode 100644 index 0000000..1d0cc53 --- /dev/null +++ b/configs/felhom-agent.service @@ -0,0 +1,50 @@ +# felhom-agent.service — canonical systemd unit for the Felhom host agent. +# +# Install as /etc/systemd/system/felhom-agent.service (the host-bootstrap script installs this from +# the Gitea-published binary; previously this unit was hand-made on each host). The agent runs as the +# NON-root `felhom-agent` service user (the documented production model — README "Process model"; +# `privileged.mode: "sudo"`) and shells the few host-root ops out via `sudo -n` against the fixed-arg +# allowlist in /etc/sudoers.d/felhom-agent (configs/felhom-agent.sudoers). The User= here and the +# sudoers `felhom-agent ALL=(root) NOPASSWD: …` MUST name the SAME user. +# +# Paths MUST match what the sudoers / host-install script expect: +# binary /usr/local/bin/felhom-agent +# config /etc/felhom-agent/agent.json (0600 felhom-agent:felhom-agent — secrets live here) +# state /var/lib/felhom-agent (nonces, local-api cert/key/tokens, staged units, guests) +# +# === DELIBERATELY NO SANDBOXING — read before adding any hardening directive === +# +# 1. NoNewPrivileges is NOT set. It is INCOMPATIBLE with the agent's privilege model: it blocks the +# setuid `sudo` the agent relies on for EVERY host-root op (mount, format, pct, dnsmasq …), so the +# agent would silently lose all privileged capability. The narrow surface comes from the sudoers +# fixed-arg allowlist + the agent's in-process fine validation (internal/storage/validate.go), NOT +# from NoNewPrivileges. Do not add it. +# +# 2. NO mount-namespacing hardening (ProtectHome, ProtectSystem, PrivateTmp, ReadOnlyPaths, +# ProtectControlGroups, …). Any of these give the unit a PRIVATE mount namespace — and the agent's +# intermediary-mount drive model does `mount --make-shared /mnt/felhom-drives` + `mount --bind` and +# relies on those propagating into the RUNNING customer guest. In a private namespace the binds +# would be invisible to the host/guest and every external-drive enrollment would silently break. +# The agent MUST share the host mount namespace. The security boundary is the sudoers allowlist. + +[Unit] +Description=Felhom host agent (Proxmox host tier; hub control loop + PBS verify + storage watchdog) +Documentation=https://gitea.dooplex.hu/admin/felhom-agent +After=network-online.target pve-cluster.service pveproxy.service +Wants=network-online.target + +[Service] +Type=simple +User=felhom-agent +Group=felhom-agent +ExecStart=/usr/local/bin/felhom-agent --config /etc/felhom-agent/agent.json +Restart=on-failure +RestartSec=5s + +# State dir: created 0750 felhom-agent:felhom-agent on start if absent (local-api cert/key/tokens, +# nonces, staged .mount units, per-guest bootstrap dirs all live here). +StateDirectory=felhom-agent +StateDirectoryMode=0750 + +[Install] +WantedBy=multi-user.target diff --git a/scripts/publish-agent.sh b/scripts/publish-agent.sh new file mode 100644 index 0000000..618ce2c --- /dev/null +++ b/scripts/publish-agent.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# publish-agent.sh — build (optional) + publish the felhom-agent binary to Gitea as a generic package. +# +# Part of the BUNDLE slice: the host-bootstrap script fetches the agent binary from Gitea +# (/api/packages/admin/generic/felhom-agent//felhom-agent) and verifies its sha256 against the +# hub-vouched artifact manifest before installing it. This script PUTs that binary and prints the +# version + sha256 the operator records in the hub (Configs → "Day-0 artifacts"). +# +# The binary is PINNED to a version (never :latest). The published path encodes the version. +# +# Usage: +# GITEA_USER=admin GITEA_TOKEN= ./publish-agent.sh [binary-path] +# +# bare semver, e.g. 0.43.0 (MUST match the binary's `--version`) +# [binary-path] path to a prebuilt felhom-agent binary. If omitted, the script builds one with +# `go build -ldflags "-X main.version="` from the repo (needs a Go toolchain). +# +# Env: +# GITEA_USER / GITEA_TOKEN Gitea credentials with package write (the build-server's admin creds). +# Falls back to REGISTRY_USER / REGISTRY_TOKEN if those are unset. +# GITEA_BASE Gitea base URL (default https://gitea.dooplex.hu) +# GITEA_OWNER package owner (default admin) +# +# Output (stdout, machine-greppable): +# AGENT_VERSION= +# AGENT_SHA256= +set -euo pipefail + +GITEA_BASE="${GITEA_BASE:-https://gitea.dooplex.hu}" +GITEA_OWNER="${GITEA_OWNER:-admin}" +GITEA_USER="${GITEA_USER:-${REGISTRY_USER:-}}" +GITEA_TOKEN="${GITEA_TOKEN:-${REGISTRY_TOKEN:-}}" + +die() { echo "[publish-agent] ERROR: $*" >&2; exit 1; } +log() { echo "[publish-agent] $*" >&2; } + +VERSION="${1:-}" +BIN="${2:-}" +[[ -n "$VERSION" ]] || die "version required (usage: GITEA_USER=.. GITEA_TOKEN=.. $0 [binary-path])" +[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "version must be bare semver X.Y.Z (got '$VERSION')" +[[ -n "$GITEA_USER" && -n "$GITEA_TOKEN" ]] || die "GITEA_USER + GITEA_TOKEN (or REGISTRY_USER/REGISTRY_TOKEN) required" + +# Resolve repo root from this script's location (scripts/ lives at the repo root). +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +# Build the binary if no prebuilt path was given. +CLEANUP_BIN="" +if [[ -z "$BIN" ]]; then + command -v go >/dev/null || die "no binary-path given and no 'go' toolchain to build one" + BIN="$(mktemp -t felhom-agent.XXXXXX)" + CLEANUP_BIN="$BIN" + log "building felhom-agent $VERSION from $REPO_ROOT …" + ( cd "$REPO_ROOT" && CGO_ENABLED=0 go build -ldflags "-X main.version=${VERSION}" -o "$BIN" ./cmd/felhom-agent ) +fi +[[ -f "$BIN" ]] || die "binary not found: $BIN" +trap '[[ -n "$CLEANUP_BIN" ]] && rm -f "$CLEANUP_BIN"' EXIT + +# Sanity: the binary's self-reported version MUST match the publish version (catch a stale rebuild). +BIN_VER="$("$BIN" --version 2>/dev/null | awk '{print $2}' || true)" +if [[ -n "$BIN_VER" && "$BIN_VER" != "$VERSION" ]]; then + die "binary --version is '$BIN_VER' but publishing as '$VERSION' — rebuild with the right ldflags" +fi + +SHA256="$(sha256sum "$BIN" | awk '{print $1}')" +[[ -n "$SHA256" ]] || die "failed to compute sha256" + +URL="${GITEA_BASE}/api/packages/${GITEA_OWNER}/generic/felhom-agent/${VERSION}/felhom-agent" +log "publishing $BIN ($(wc -c < "$BIN") bytes, sha256 ${SHA256:0:16}…) → $URL" + +# Generic packages reject re-upload of an existing version+file with 409/400. Delete-then-put makes +# re-publishing a version idempotent (so a rebuild of the same version overwrites cleanly). +code="$(curl -fsS -o /dev/null -w '%{http_code}' -u "${GITEA_USER}:${GITEA_TOKEN}" -X DELETE "$URL" 2>/dev/null || true)" +log "pre-delete existing artifact: HTTP ${code} (404/204 expected)" + +code="$(curl -sS -o /dev/null -w '%{http_code}' -u "${GITEA_USER}:${GITEA_TOKEN}" -X PUT --upload-file "$BIN" "$URL")" +[[ "$code" == "201" || "$code" == "200" ]] || die "upload failed: HTTP $code" +log "upload OK (HTTP $code)" + +# GET round-trip: re-fetch and confirm the stored bytes hash to the same sha256 (proves fetchable + +# intact end-to-end, the same path the host-install script will take). +TMP_GET="$(mktemp -t felhom-agent-get.XXXXXX)" +trap '[[ -n "$CLEANUP_BIN" ]] && rm -f "$CLEANUP_BIN"; rm -f "$TMP_GET"' EXIT +curl -fsS -u "${GITEA_USER}:${GITEA_TOKEN}" -o "$TMP_GET" "$URL" || die "round-trip GET failed" +GOT_SHA="$(sha256sum "$TMP_GET" | awk '{print $1}')" +[[ "$GOT_SHA" == "$SHA256" ]] || die "round-trip sha256 mismatch (put $SHA256, got $GOT_SHA)" +log "round-trip GET verified (sha256 matches)" + +echo "AGENT_VERSION=${VERSION}" +echo "AGENT_SHA256=${SHA256}" +log "DONE. Record in the hub operator UI (Configs → Day-0 artifacts): agent ${VERSION} / ${SHA256}"