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 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).
• --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

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.

./customize.sh rootfs-docker.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.

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
• ./ubuntu-noble-rootfs/rootfs.ext4
• ./ubuntu-lts/rootfs.ext4

VM Info File

Each VM writes:

• state/vms/<id>/vm.json: raw /vm/config response from Firecracker.
• state/vms/<id>/meta.json: local metadata (id, name, pid, created_at, guest_ip, tap, api_sock, log, rootfs, kernel, snapshot info).

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.