banger/README.md

# banger

Minimal Firecracker launcher.

## Requirements
- Linux host with KVM (`/dev/kvm` access)
- `sudo`, `ip`, `curl`, `ssh`, `jq`
- `dmsetup`, `losetup`, `blockdev` (device-mapper snapshot for rootfs)
- `e2cp`, `e2rm` (writes hostname and resolv.conf into rootfs snapshot)

## Files
- `firecracker`: Firecracker binary
- `wtf/root/boot/vmlinux-6.8.0-94-generic`: guest kernel
- `wtf/root/boot/initrd.img-6.8.0-94-generic`: guest initrd
- `wtf/root/lib/modules/6.8.0-94-generic/`: guest kernel modules
- `rootfs.ext4`: guest root filesystem (base image if present)
- `rootfs-docker.ext4`: docker-ready guest rootfs (built via `make-rootfs.sh`)
- `packages.apt`: apt packages baked into rebuilt guest images
- `id_ed25519`: SSH key for `root`
- `mapdns`: local DNS mapping CLI used to publish `<vm-name>.vm` → guest IP records

## Run
```
./run.sh
```

## Experimental Go Control Plane
There is now an XDG-based Go daemon + CLI prototype alongside the shell scripts.
It keeps persistent VM/image state in SQLite under your XDG state directory and
talks over a Unix socket under your XDG runtime directory.

Build it with:
```
make build
```

Or directly with Go:
```
go build -o ./banger ./cmd/banger
go build -o ./bangerd ./cmd/bangerd
```

Basic usage:
```
./banger daemon status
./banger tui
./banger vm list
./banger vm create --name calm-otter --disk-size 16G
./banger vm set calm-otter --memory 2048 --vcpu 4
./banger image list
```

Notes:
- `banger` auto-starts the per-user daemon when needed.
- `banger tui` launches a terminal UI for browsing, creating, editing, and operating VMs.
- VM configs are persistent by default.
- RAM, vCPU, and work-disk size edits are stopped-only.
- The Go image build path currently delegates guest customization to `customize.sh`.

## Run Options
```
./run.sh --name calm-otter --vcpu 4 --ram 2048 --overlay-size 12G
```
- `--name`: must be unique and match `[a-z0-9][a-z0-9-]{0,63}`.
- `--vcpu`: defaults to 2, max 16.
- `--ram`: MiB, defaults to 1024, max 32768.
- `--overlay-size`: writable dm-snapshot size for VM changes under `/`, including `/root` and `/var` (default: 8G).
- `--rootfs`: path to the rootfs image (default: `./rootfs-docker.ext4`).
- `--kernel`: path to the kernel image (default: `./wtf/root/boot/vmlinux-6.8.0-94-generic`).
- `--initrd`: path to the initrd image (default: `./wtf/root/boot/initrd.img-6.8.0-94-generic`).

## Storage Layout
- `rootfs.ext4` is used as the read-only origin for a per-VM device-mapper snapshot mounted as `/`.
- Each VM gets one sparse writable overlay file (`cow.ext4`) that stores its changes on top of the shared base image.
- `/root` and `/var` live inside that per-VM overlay, so VMs can install packages without copying separate disks per VM.
- `run.sh` masks stale `home.mount` and `var.mount` units at boot so older images with `/dev/vdb` and `/dev/vdc` entries in `/etc/fstab` still boot.
- `/run` and `/tmp` should be tmpfs via `/etc/fstab`.

## SSH
```
ssh -i "./id_ed25519" root@<guest_ip>
```

Shortcut:
```
./ssh.sh <vm-name-or-ip>
```

## VM DNS
- Spawned VMs register `<vm-name>.vm` → guest IP through `mapdns set`.
- VM teardown removes the mapping through `mapdns rm`.
- `mapdns` writes to `/home/thales/.local/share/mapdns/records.json`.

## Internet Access
VMs do not get internet access by default. You must enable forwarding and NAT:
```
./nat.sh up <id-or-name-prefix>
```
This enables `net.ipv4.ip_forward=1` and installs per-VM NAT rules for the VM's
guest IP and TAP device. To remove rules:
```
./nat.sh down <id-or-name-prefix>
```
Check status with:
```
./nat.sh status <id-or-name-prefix>
```

## Shutdown
```
reboot
```

## Customize Rootfs (Docker + Kernel Modules)
Use `customize.sh` to build a writable rootfs with Docker and kernel modules
preloaded so Docker works out of the box. Pass the base rootfs as a positional
argument; the output defaults to `docker-<base filename>` in the same directory
unless you pass `--out`.

Base guest packages come from `./packages.apt`. Edit that file to bake tools
like `vim` and `tmux` into rebuilt images.

```
./customize.sh ./rootfs.ext4 --size 6G --docker
```

Options:
- `--size`: optional size for the output image.
- `--kernel`: kernel path (default: `./wtf/root/boot/vmlinux-6.8.0-94-generic`).
- `--initrd`: initrd path (default: `./wtf/root/boot/initrd.img-6.8.0-94-generic`).
- `--modules`: kernel modules directory (default: `./wtf/root/lib/modules/6.8.0-94-generic`).
- `--docker`: install Docker packages into the image.
- `--out`: output rootfs path (default: `docker-<base filename>`).

After boot, enable NAT and validate Docker:
```
./nat.sh up <id-or-name-prefix>
ssh -i "./id_ed25519" root@<guest_ip> "systemctl enable --now docker"
ssh -i "./id_ed25519" root@<guest_ip> "docker run --rm hello-world"
```

## Build Rootfs On Demand
`run.sh` defaults to `./rootfs-docker.ext4`. If it is missing, `run.sh` will
invoke `make-rootfs.sh` to build it.

```
./make-rootfs.sh
```

`make-rootfs.sh` chooses the first available base image:
- `./rootfs.ext4`

If `./packages.apt` changes after `rootfs-docker.ext4` is built, `run.sh` will
warn and keep using the existing image. `make-rootfs.sh` will also warn and
exit without rebuilding while the image already exists.

To rebuild after package changes:
```
rm -f ./rootfs-docker.ext4 ./rootfs-docker.ext4.packages.sha256
./make-rootfs.sh
```

## Interactive Customization
To create a writable copy and customize it manually over SSH (no automatic
package/config changes), use:

```
./interactive.sh ./rootfs-docker.ext4
```

You can override the output path:
```
./interactive.sh ./rootfs-docker.ext4 --out ./my-rootfs.ext4
```

## VM Info File
Each VM writes:
- `state/vms/<id>/vm.json`: local metadata under `.meta` plus the raw Firecracker config under `.config`.

## Log Notes
- `PCI: Fatal: No config space access function found` and `MissingAddressRange` lines are expected with `pci=off` in `run.sh`.
- `SELinux: Could not open policy file ...` is expected in the minimal rootfs.