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.
304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
# banger
|
|
|
|
One-command development sandboxes on Firecracker microVMs.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
make build
|
|
sudo ./build/bin/banger system install --owner "$USER"
|
|
banger vm run --name sandbox
|
|
```
|
|
|
|
That's it. `banger vm run` auto-pulls the default golden image (Debian
|
|
bookworm with systemd, sshd, Docker CE, git, jq, mise, and the usual
|
|
dev tools) and kernel, creates a VM, starts it, and drops you into
|
|
an interactive ssh session. First run takes a couple minutes (bundle
|
|
download); subsequent `vm run`s are seconds.
|
|
|
|
## Supported host path
|
|
|
|
banger's supported host/runtime path is:
|
|
|
|
- Linux on `x86_64 / amd64`
|
|
- `systemd` as the host init/service manager
|
|
- `bangerd.service` running as the installed owner user
|
|
- `bangerd-root.service` running as the privileged host helper
|
|
|
|
Other setups may work with manual adaptation, but they are not the
|
|
supported operating model for this repo.
|
|
|
|
## Requirements
|
|
|
|
- **x86_64 / amd64 Linux** — arm64 is not supported today. The companion
|
|
binaries, the published kernel catalog, and the OCI import path all
|
|
assume `linux/amd64`. `banger doctor` surfaces this as a failing
|
|
check on other architectures.
|
|
- **systemd on the host** — this is the supported service-management
|
|
path. banger's supported install/run model is the owner-user
|
|
`bangerd.service` plus the privileged `bangerd-root.service`
|
|
installed by `banger system install`.
|
|
- `/dev/kvm`
|
|
- `sudo` for the install/admin commands (`system install`,
|
|
`system restart`, `system uninstall`)
|
|
- Firecracker on `PATH`, or `firecracker_bin` set in config
|
|
- host tools checked by `banger doctor`
|
|
|
|
## Build + install
|
|
|
|
```bash
|
|
make build
|
|
sudo ./build/bin/banger system install --owner "$USER"
|
|
```
|
|
|
|
This installs two systemd units, copies the current `banger`,
|
|
`bangerd`, and `banger-vsock-agent` binaries into `/usr/local`, writes
|
|
install metadata under `/etc/banger`, and starts both services:
|
|
|
|
- `bangerd.service` runs as the configured owner user and exposes the
|
|
public CLI socket at `/run/banger/bangerd.sock`.
|
|
- `bangerd-root.service` runs as root and handles the narrow set of
|
|
privileged host operations over the private helper socket at
|
|
`/run/banger-root/bangerd-root.sock`.
|
|
|
|
After that, normal daily commands such as `banger vm run` and
|
|
`banger image pull` are unprivileged.
|
|
|
|
This `systemd` service flow is the supported path. If you're not on a
|
|
host that can run both services, you're outside the supported host
|
|
model even if some pieces happen to work.
|
|
|
|
The split matters:
|
|
|
|
- `bangerd.service` runs as the owner user, keeps its writable state in
|
|
`/var/lib/banger`, `/var/cache/banger`, and `/run/banger`, and sees
|
|
the owner home read-only.
|
|
- `bangerd-root.service` is the only process that keeps elevated host
|
|
capabilities, and that capability set is limited to the host-kernel
|
|
primitives banger actually uses (`CAP_CHOWN`, `CAP_SYS_ADMIN`,
|
|
`CAP_NET_ADMIN`).
|
|
|
|
To inspect or refresh the services:
|
|
|
|
```bash
|
|
banger system status
|
|
sudo banger system restart
|
|
```
|
|
|
|
To remove the system services:
|
|
|
|
```bash
|
|
sudo banger system uninstall
|
|
```
|
|
|
|
Add `--purge` if you also want to remove system-owned VM/image/cache
|
|
state under `/var/lib/banger`, `/var/cache/banger`, `/run/banger`, and
|
|
`/run/banger-root`. User config stays in place under your home
|
|
directory:
|
|
|
|
- `~/.config/banger/` — config, optional `ssh_config`
|
|
- `~/.local/state/banger/ssh/` — user SSH key + known_hosts
|
|
|
|
### Shell completion
|
|
|
|
`banger` ships completion scripts for bash, zsh, fish, and
|
|
powershell. Tab-completion covers subcommands, flags, and live
|
|
resource names (VM, image, kernel) looked up from the installed
|
|
services. With the services down, resource completion silently
|
|
returns nothing — no file-completion fallback.
|
|
|
|
```bash
|
|
# bash (system-wide)
|
|
banger completion bash | sudo tee /etc/bash_completion.d/banger
|
|
|
|
# zsh (user-local; ~/.zfunc must be on fpath)
|
|
banger completion zsh > ~/.zfunc/_banger
|
|
|
|
# fish
|
|
banger completion fish > ~/.config/fish/completions/banger.fish
|
|
```
|
|
|
|
`banger completion --help` shows the shell-specific loading
|
|
recipes.
|
|
|
|
## `vm run`
|
|
|
|
One command, four common shapes:
|
|
|
|
```bash
|
|
banger vm run # bare sandbox — drops into ssh
|
|
banger vm run ./repo # workspace at /root/repo — drops into ssh
|
|
banger vm run ./repo -- make test # workspace + run command, exits with its status
|
|
banger vm run --rm -- script.sh # ephemeral: VM is deleted on exit
|
|
```
|
|
|
|
- **Bare mode** gives you a clean shell.
|
|
- **Workspace mode** (path given) copies the repo's git-tracked files
|
|
into `/root/repo` and kicks off a best-effort `mise` tooling
|
|
bootstrap from the repo's `.mise.toml` / `.tool-versions`. Log:
|
|
`/root/.cache/banger/vm-run-tooling-<repo>.log`. Untracked files
|
|
(including local `.env`, scratch notes, credentials that aren't
|
|
gitignored) are skipped by default — pass `--include-untracked` to
|
|
also ship them. Pass `--dry-run` to print the exact file list and
|
|
exit without creating a VM.
|
|
- **Command mode** (`-- <cmd>`) runs the command in the guest; exit
|
|
code propagates through `banger`.
|
|
|
|
Disconnecting from an interactive session leaves the VM running. Use
|
|
`vm stop` / `vm delete` to clean up — or pass `--rm` so the VM
|
|
auto-deletes once the session / command exits.
|
|
|
|
`--branch`, `--from`, `--include-untracked`, and `--dry-run` apply
|
|
only to workspace mode. `--rm` skips the delete when the initial ssh
|
|
wait times out, so a wedged sshd leaves the VM alive for `banger vm
|
|
logs` inspection.
|
|
|
|
## Hostnames: reaching `<vm>.vm`
|
|
|
|
banger's owner daemon runs a DNS server for the `.vm` zone. With
|
|
host-side DNS routing you can `curl http://sandbox.vm:3000` from
|
|
anywhere on the host — no copy-pasting guest IPs. On
|
|
systemd-resolved hosts the owner daemon asks the root helper to
|
|
auto-wire this and that is the supported path. Everywhere else
|
|
there's a best-effort manual recipe. See
|
|
[`docs/dns-routing.md`](docs/dns-routing.md).
|
|
|
|
### Optional: `ssh <name>.vm` shortcut
|
|
|
|
`banger vm ssh <name>` works out of the box. If you'd also like plain
|
|
`ssh sandbox.vm` from any terminal (using banger's key + known_hosts),
|
|
opt in:
|
|
|
|
```bash
|
|
banger ssh-config --install # adds `Include ~/.config/banger/ssh_config`
|
|
# to ~/.ssh/config in a marker-fenced block
|
|
banger ssh-config --uninstall # reverse it
|
|
banger ssh-config # show the include line to paste manually
|
|
```
|
|
|
|
banger never touches `~/.ssh/config` on its own — the daemon keeps its
|
|
own known_hosts under `/var/lib/banger/ssh/known_hosts`, while
|
|
`banger ssh-config` keeps the user-facing file fresh at
|
|
`~/.config/banger/ssh_config`; whether and how it's
|
|
pulled into your SSH config is up to you.
|
|
|
|
## Image catalog
|
|
|
|
`banger image pull <name>` fetches a pre-built bundle from the
|
|
embedded catalog. `vm run` calls this for you on demand.
|
|
|
|
Today's catalog:
|
|
|
|
| Name | What it is |
|
|
|------|-----------|
|
|
| `debian-bookworm` | Debian 12 slim + sshd + docker + dev tools |
|
|
|
|
See [`docs/image-catalog.md`](docs/image-catalog.md) for the bundle
|
|
format and how to publish a new entry.
|
|
|
|
## Config
|
|
|
|
Config lives at `~/.config/banger/config.toml`. All keys optional.
|
|
|
|
Most commonly set:
|
|
|
|
- `default_image_name` — image used when `--image` is omitted
|
|
(default `debian-bookworm`, auto-pulled from the catalog if not
|
|
local).
|
|
- `ssh_key_path` — host SSH key. If unset, banger creates
|
|
`~/.local/state/banger/ssh/id_ed25519`. Accepts absolute paths or
|
|
`~/`-anchored paths; `~/foo` expands against `$HOME`. Relative
|
|
paths are rejected at config load.
|
|
- `firecracker_bin` — override the auto-resolved `PATH` lookup.
|
|
|
|
Full key list in `internal/config/config.go`.
|
|
|
|
### `vm_defaults` — sizing for new VMs
|
|
|
|
Every `vm run` / `vm create` prints a `spec:` line up front showing
|
|
the vCPU, RAM, and disk the VM will get. When the flags aren't set,
|
|
those values come from:
|
|
|
|
1. `[vm_defaults]` in config (if present, wins).
|
|
2. Host-derived heuristics (roughly: `cpus/4` capped at 4, `ram/8`
|
|
capped at 8 GiB, 8 GiB disk).
|
|
3. Built-in constants (floor).
|
|
|
|
`banger doctor` prints the effective defaults with provenance.
|
|
|
|
```toml
|
|
[vm_defaults]
|
|
vcpu = 4
|
|
memory_mib = 4096
|
|
disk_size = "16G"
|
|
```
|
|
|
|
All keys optional — omit whichever you want banger to decide.
|
|
|
|
### `file_sync` — host → guest file copies
|
|
|
|
```toml
|
|
[[file_sync]]
|
|
host = "~/.aws" # whole directory, recursive
|
|
guest = "~/.aws"
|
|
|
|
[[file_sync]]
|
|
host = "~/.config/gh/hosts.yml"
|
|
guest = "~/.config/gh/hosts.yml"
|
|
|
|
[[file_sync]]
|
|
host = "~/bin/my-script"
|
|
guest = "~/bin/my-script"
|
|
mode = "0755" # optional; default 0600 for files
|
|
```
|
|
|
|
Runs at `vm create` time. Each entry copies `host` → `guest` onto
|
|
the VM's work disk (mounted at `/root` in the guest). Guest paths
|
|
must live under `~/` or `/root/...`. Host paths must live under the
|
|
installed owner's home directory; `~/...` is the intended form, and
|
|
absolute paths are accepted only when they still point inside that
|
|
home. Default is no entries — add the ones you want. A top-level
|
|
symlink is followed only when its resolved target stays inside the
|
|
owner home. Symlinks encountered while recursing into a synced
|
|
directory are skipped with a warning — they'd otherwise leak files
|
|
from outside the named tree (e.g. a symlink inside `~/.aws` pointing
|
|
to an unrelated credential dir).
|
|
|
|
## Advanced
|
|
|
|
The common path is `vm run`. Power-user flows (`vm create`, OCI pull
|
|
for arbitrary images, `image register`, manual workspace prepare) are
|
|
documented in [`docs/advanced.md`](docs/advanced.md).
|
|
|
|
## Security
|
|
|
|
Guest VMs are single-user development sandboxes, not multi-tenant
|
|
servers. Each guest's sshd is configured with:
|
|
|
|
```
|
|
PermitRootLogin prohibit-password
|
|
PubkeyAuthentication yes
|
|
PasswordAuthentication no
|
|
KbdInteractiveAuthentication no
|
|
AuthorizedKeysFile /root/.ssh/authorized_keys
|
|
```
|
|
|
|
The host SSH key is the only authentication mechanism. `StrictModes`
|
|
is on (sshd's default); banger normalises `/root`, `/root/.ssh`, and
|
|
`authorized_keys` perms at provisioning time so the default passes.
|
|
|
|
VMs are reachable only through the host bridge network
|
|
(`172.16.0.0/24` by default). Do not expose the bridge interface or
|
|
guest IPs to an untrusted network.
|
|
|
|
## Further reading
|
|
|
|
- [`docs/dns-routing.md`](docs/dns-routing.md) — resolving
|
|
`<vm>.vm` hostnames from the host.
|
|
- [`docs/image-catalog.md`](docs/image-catalog.md) — bundle format
|
|
and publishing.
|
|
- [`docs/kernel-catalog.md`](docs/kernel-catalog.md) — kernel
|
|
bundles.
|
|
- [`docs/oci-import.md`](docs/oci-import.md) — pulling arbitrary
|
|
OCI images.
|
|
- [`docs/advanced.md`](docs/advanced.md) — power-user flows.
|