daemon: split owner daemon from root helper

Move the supported systemd path to two services: an owner-user bangerd for
orchestration and a narrow root helper for bridge/tap, NAT/resolver, dm/loop,
and Firecracker ownership. This removes repeated sudo from daily vm and image
flows without leaving the general daemon running as root.

Add install metadata, system install/status/restart/uninstall commands, and a
system-owned runtime layout. Keep user SSH/config material in the owner home,
lock file_sync to the owner home, and move daemon known_hosts handling out of
the old root-owned control path.

Route privileged lifecycle steps through typed privilegedOps calls, harden the
two systemd units, and rewrite smoke plus docs around the supported service
model.

Verified with make build, make test, make lint, and make smoke on the
supported systemd host path.

2026-04-26 12:43:17 -03:00

3.4 KiB

Raw Permalink Blame History

Advanced flows

banger vm run covers the common sandbox case. This doc is for the rest: scripting, arbitrary images, custom rootfs stacks, long-lived guest processes.

Host-side assumption for everything below: the supported runtime model is still the two-service systemd install:

bangerd.service running as the owner user
bangerd-root.service running as the privileged host helper

These advanced flows widen what you do with banger, not which host init systems or privilege model are supported.

`vm create` — the low-level primitive

Use when you want to provision without starting, or when you need to script VM creation piecewise.

banger vm create --image debian-bookworm --name testbox --no-start
banger vm start testbox
banger vm ssh testbox
banger vm stop testbox
banger vm delete testbox

Sweep every non-running VM (stopped, created, error) with:

banger vm prune          # interactive confirmation
banger vm prune -f       # skip the prompt

vm create is synchronous by default, but on a TTY it shows live progress until the VM is fully ready.

`image pull <oci-ref>` — arbitrary container images

For images outside banger's catalog, pull from any OCI registry:

banger image pull docker.io/library/alpine:3.20 --kernel-ref generic-6.12

Layers are flattened, ownership is fixed (setuid binaries, root-owned config preserved), banger's guest agents are injected, and a first-boot systemd service installs openssh-server via the guest's package manager so the VM is reachable on first boot.

See docs/oci-import.md for supported distros, caveats, and the internal/imagepull design.

`image register` — existing host-side stack

If you already have an ext4 rootfs, a kernel, optional initrd, and optional modules as files on disk:

banger image register --name base \
  --rootfs /abs/path/rootfs.ext4 \
  --kernel-ref generic-6.12

You can mix --kernel-ref (a cataloged kernel) with --rootfs from disk, or pass --kernel /abs/path/vmlinux for a one-off kernel.

For reproducible custom images, write a Dockerfile and publish it to an image catalog. See docs/image-catalog.md.

Workspace primitive

vm run ./repo (see README) handles the common case. For a manual flow against an already-running VM, vm workspace prepare materialises a local git checkout into the guest:

banger vm workspace prepare <vm> ./other-repo --guest-path /root/repo

Default guest path is /root/repo; default mode is a shallow metadata copy plus a tracked-files overlay. Untracked files are skipped by default — pass --include-untracked to ship untracked non-ignored files too. Pass --dry-run to list the exact file set without touching the guest. For repositories with submodules, pass --mode full_copy.

Inspecting boot failures

When a VM's create flow errors ("ssh did not come up within 90s" or similar), the VM is kept alive for inspection:

banger vm logs <name> — the firecracker serial console output, the best window into a stuck boot (systemd unit failures, kernel panics, missing modules).
banger vm ports <name> — what's listening in the guest. Works as long as banger's vsock agent has come up, even if SSH is wedged.
banger vm show <name> — daemon-side state (IP, PID, overlay paths).

--rm on vm run intentionally does NOT fire when the initial ssh wait times out, so the VM stays around for post-mortem.

3.4 KiB Raw Permalink Blame History