# 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
- `vmlinux`: guest kernel
- `rootfs.ext4`: guest root filesystem
- `id_ed25519`: SSH key for `root`

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

## Run Options
```
./run.sh --name calm_otter --vcpu 4 --ram 2048 --home-size 6G
```
- `--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.
- `--rootfs`: path to the base rootfs image (default: `./rootfs.ext4`).
- `--kernel`: path to the kernel image (default: `./vmlinux`).
- `--home-size`: M/G suffixes supported (default: 2G).
- `--var-size`: M/G suffixes supported (default: 2G).

## Storage Layout
- `rootfs.ext4` is used as the read-only origin for a per-VM device-mapper snapshot mounted as `/`.
- Each VM gets writable ext4 disks mounted at `/home` and `/var`.
- The base image must include `/etc/fstab` entries for `/dev/vdb` → `/home` and `/dev/vdc` → `/var`.
- `/run` and `/tmp` should be tmpfs via `/etc/fstab`.

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

## 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
```

## VM Info File
Each VM writes `state/vms/<id>/vm.json` with:
- `meta`: local metadata (id, name, pid, created_at, guest_ip, tap, api_sock, log, rootfs, kernel, snapshot info).
- `config`: full `/vm/config` response from Firecracker.

## 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.