Thales Maciel
59e48e830b
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.
103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](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:
|
|
|
|
```bash
|
|
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`](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:
|
|
|
|
```bash
|
|
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.
|