68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# hive-priv
|
|
|
|
The minimal **root privileged-helper** for hive-c0re. It runs as root and
|
|
exposes a narrow unix socket at `/run/hive/priv.sock` that accepts `PrivRequest`
|
|
JSON lines and performs only the handful of operations that genuinely require
|
|
root — bind-mount edits, `nsenter` into a container, btrfs subvolume ops. All
|
|
coordination logic (broker, HTTP, scheduling) stays in the _unprivileged_
|
|
`hive-c0re` process, which delegates here.
|
|
|
|
## Why it exists
|
|
|
|
Privsep. `hive-c0re` runs as the unprivileged `hive-core` user so a bug or a
|
|
prompt-injection in the large daemon can't directly wield root. The few root
|
|
operations it needs are funnelled through this small, auditable helper instead.
|
|
See `docs/2-handbook/hives/boundary.md` and `docs/4-implementation/trust-boundary/hive-c0re-privilege.md` for the privilege boundary.
|
|
|
|
## Security model
|
|
|
|
- **Strict allowlist.** hive-priv checks every request against a container-name
|
|
allowlist before any filesystem or process operation, and accepts only names
|
|
matching the hive convention (`h-*`, the manager container included).
|
|
- **No pass-through.** Every `PrivRequest` variant maps to a single known
|
|
operation; there is no arbitrary-command escape hatch.
|
|
- **Socket-activated, always.** systemd binds `/run/hive/priv.sock`
|
|
(`SocketGroup=hive-core`, `0660`) and passes the listener as fd 3
|
|
(`LISTEN_FDS`); the helper requires this and has no self-bind fallback, so dev
|
|
and prod take the identical path and the group grant always holds.
|
|
|
|
The wire contract (`PrivRequest` / response types) lives in the separate
|
|
`hive-priv-sock` crate so this root binary depends on just the protocol shapes,
|
|
not the whole daemon-shared crate.
|
|
|
|
## Layout
|
|
|
|
`src/main.rs` holds the socket loop and the dispatch table, one arm per
|
|
`PrivRequest` variant. Each op family, with its validation, has its own module:
|
|
`container` (lifecycle), `container_config` (nspawn flags, systemd drop-ins),
|
|
`storage` (btrfs subvolumes, quotas, snapshots, disk measurement), `files`
|
|
(pause marker, socket dir, legacy tmpfiles) and `infra` (gateway nginx, forge
|
|
admin, infra containers). Helpers more than one family calls live in `shared`.
|
|
Each module's `//!` header lists its ops.
|
|
|
|
## Implementation notes
|
|
|
|
### Container toplevels (create/update)
|
|
|
|
`container_toplevel_action` (in `src/container.rs`) applies a closure that is
|
|
already in the store; hive-priv builds nothing. hive-c0re names the closure
|
|
(`toplevel` on `CreateContainer` / `UpdateContainer`), pulled beforehand by
|
|
hive-c0re through the nix daemon. hive-priv applies a path only when
|
|
`nix store verify --no-contents --sigs-needed 1`, with the key in root-owned
|
|
`/run/hyperhive-priv/attic/public-key`, finds the swarm cache's signature on it.
|
|
It refuses a path that is absent, unsigned, signed by another key or not a store
|
|
path, and logs an error naming the agent and the path. hive-priv keeps no record
|
|
of what was pulled, so a restart between the pull and the apply loses nothing.
|
|
`RefreshCacheFacts` starts the root unit that refreshes the cache facts.
|
|
|
|
`create` passes the path to `nixos-container create --system-path`, so
|
|
`nixos-container`'s own `buildFlake()` never runs. Without the flag, it builds
|
|
to a hardcoded relative `.tmp` out-link: `$systemPath` stays `undef` and
|
|
`"$systemPath.tmp"` interpolates to the bare string `.tmp` in the caller's cwd.
|
|
With `services.hyperhive.deploy.hive-controller.buildSlots > 1`, two concurrent
|
|
calls could share that one `.tmp`, and one agent's container got another
|
|
agent's closure.
|
|
|
|
`update` points the container's profile at the path with `nix-env --set` and
|
|
reloads the unit if it runs, because `nixos-container update` dies on its
|
|
version probe before it honors `--system-path`.
|