85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# banger
|
|
|
|
Minimal Firecracker launcher.
|
|
|
|
## Requirements
|
|
- Linux host with KVM (`/dev/kvm` access)
|
|
- `sudo`, `ip`, `curl`, `ssh`
|
|
- `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 a metadata file at `state/vms/<id>/info` with the following fields:
|
|
- `id`: unique identifier for the VM instance.
|
|
- `name`: VM name.
|
|
- `pid`: Firecracker process ID.
|
|
- `created_at`: timestamp when the VM was launched.
|
|
- `rootfs`: root filesystem image path used to launch the VM.
|
|
- `kernel`: kernel image path used to launch the VM.
|
|
- `guest_ip`: IP address assigned to the guest.
|
|
- `tap`: host TAP interface name attached to the bridge.
|
|
- `api_sock`: path to the Firecracker API socket (stored under `$XDG_RUNTIME_DIR/banger/` when available).
|
|
- `log`: path to the Firecracker log file.
|
|
- `base_loop`: loop device backing the base rootfs (if present).
|
|
- `cow_file`: copy-on-write image file (if present).
|
|
- `cow_loop`: loop device for the COW image (if present).
|
|
- `dm_name`: device-mapper name for the merged rootfs (if present).
|
|
- `dm_dev`: device-mapper device path for the merged rootfs (if present).
|
|
|
|
## 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.
|