Streamline VM overlays and rootfs packages

Move the default guest package list into a repo manifest and record a hash beside built rootfs images so run/make-rootfs can warn when the docker-ready image is stale.

Switch the Firecracker launch path to a single sparse root overlay per VM instead of separate /home and /var disks, so many VMs can share the same base image while still installing packages under /var and working from /root.

Keep older images bootable by masking stale home.mount and var.mount units at boot, and scrub those obsolete fstab entries when customize.sh rebuilds an image. Verified with bash -n on the updated scripts; no live VM boot was run in this environment.
This commit is contained in:
Thales Maciel 2026-03-15 19:36:54 -03:00
parent 9191b7e370
commit 3cf33d1e0a
No known key found for this signature in database
GPG key ID: 33112E6833C34679
8 changed files with 206 additions and 204 deletions

View file

@ -15,6 +15,7 @@ Minimal Firecracker launcher.
- `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
@ -25,22 +26,21 @@ Minimal Firecracker launcher.
## Run Options
```
./run.sh --name calm_otter --vcpu 4 --ram 2048 --home-size 6G
./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`).
- `--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`.
- `run.sh` seeds those `/home` and `/var` disks from the rootfs snapshot before boot so the guest sees the base image contents there on first boot.
- The base image must include `/etc/fstab` entries for `/dev/vdb``/home` and `/dev/vdc``/var`.
- 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
@ -84,6 +84,9 @@ 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
```
@ -114,6 +117,16 @@ invoke `make-rootfs.sh` to build it.
`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: