Thales Maciel
2e6e64bc04
Previously /etc/ssh/sshd_config.d/99-banger.conf landed with: LogLevel DEBUG3 PermitRootLogin yes PubkeyAuthentication yes AuthorizedKeysFile /root/.ssh/authorized_keys StrictModes no DEBUG3 was debug leftover that floods journald in normal use. StrictModes no was a workaround for /root perm drift on the work disk — the real fix is to make those perms correct at provisioning time. New drop-in: PermitRootLogin prohibit-password PubkeyAuthentication yes PasswordAuthentication no KbdInteractiveAuthentication no AuthorizedKeysFile /root/.ssh/authorized_keys prohibit-password blocks password root login even if PasswordAuth gets flipped on elsewhere; KbdInteractiveAuth no closes the last interactive fallback; StrictModes is now on (sshd's default). normaliseHomeDirPerms chown/chmods /root to 0755 root:root at every work-disk mount (ensureAuthorizedKeyOnWorkDisk, seedAuthorizedKeyOnExt4Image); the .ssh dir also explicitly chown'd root:root. Verified end-to-end against a real VM: `sshd -T` reports strictmodes yes and all five directives match. Regression test (sshd_config_test.go) pins the allow-list and the deny-list (DEBUG3, StrictModes no, bare `PermitRootLogin yes`) so the next accidental reintroduction fails fast. README's Security section updated to reflect the new posture.
222 lines
6.7 KiB
Markdown
222 lines
6.7 KiB
Markdown
# banger
|
|
|
|
One-command development sandboxes on Firecracker microVMs.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
make install
|
|
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.
|
|
|
|
## Requirements
|
|
|
|
- Linux with `/dev/kvm`
|
|
- `sudo`
|
|
- Firecracker on `PATH`, or `firecracker_bin` set in config
|
|
- host tools checked by `banger doctor`
|
|
|
|
## Build + install
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
Installs `banger` (CLI), `bangerd` (daemon, auto-starts on first
|
|
CLI call), and `banger-vsock-agent` (companion, under
|
|
`$PREFIX/lib/banger/`).
|
|
|
|
To remove the binaries (and stop the daemon):
|
|
|
|
```bash
|
|
make uninstall
|
|
```
|
|
|
|
User data stays in place — the target prints the paths so you can
|
|
`rm -rf` them if you want a full purge:
|
|
|
|
- `~/.config/banger/` — config, managed SSH keys
|
|
- `~/.local/state/banger/` — VM records, rootfs images, kernels, daemon DB/log
|
|
- `~/.cache/banger/` — OCI layer cache
|
|
|
|
### Shell completion
|
|
|
|
`banger` ships completion scripts for bash, zsh, fish, and
|
|
powershell. Tab-completion covers subcommands, flags, and live
|
|
resource names (VM, image, kernel, session) looked up from the
|
|
daemon. With the daemon 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 tracked + untracked
|
|
non-ignored 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`.
|
|
- **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` and `--from` 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 daemon runs a DNS server for the `.vm` zone. With host-side
|
|
DNS routing you can `ssh root@sandbox.vm` or `curl
|
|
http://sandbox.vm:3000` from anywhere on the host — no copy-pasting
|
|
guest IPs. On systemd-resolved hosts this is auto-wired; everywhere
|
|
else there's a short recipe. See
|
|
[`docs/dns-routing.md`](docs/dns-routing.md).
|
|
|
|
## 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
|
|
`~/.config/banger/ssh/id_ed25519`.
|
|
- `firecracker_bin` — override the auto-resolved `PATH` lookup.
|
|
- `web_listen_addr` — experimental web UI; disabled by default. Set
|
|
e.g. `"127.0.0.1:7777"` to enable.
|
|
|
|
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/...`. Default is no entries — add the
|
|
ones you want.
|
|
|
|
## Advanced
|
|
|
|
The common path is `vm run`. Power-user flows (`vm create`, OCI pull
|
|
for arbitrary images, `image register`, long-lived sessions) 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.
|
|
|
|
The web UI is disabled by default. If you opt in via
|
|
`web_listen_addr`, it binds `127.0.0.1` — do not publish it to a
|
|
shared 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.
|