diff --git a/README.md b/README.md index 94e9ba0..b6579f3 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,9 @@ aarch64 For full configuration documentation, see [config.md](./docs/config.md). +For tips on creating a rootfs (if you don't want to just use your host system's +one), see [rootfs.md](./docs/rootfs.md). + ## Usage in Github CI [vmtest-action](https://github.com/danobi/vmtest-action) is a convenient diff --git a/docs/config.md b/docs/config.md index d203d04..adaa2ce 100644 --- a/docs/config.md +++ b/docs/config.md @@ -44,6 +44,12 @@ The following fields are supported: [9p](https://docs.kernel.org/filesystems/9p.html). * If a relative path is provided, it will be interpreted as relative to `vmtest.toml` + * UIDs from the host will be passed through directly; if you built your + rootfs without privileges in the host, try running `vmtest` via + `unshare -r`, so that QEMU (and hence the guest) sees UID 0. + * For tips on creating a rootfs (if you don't want to just use your host + system's one), see [rootfs.md](./docs/rootfs.md). + * `arch` (string) * Default: the architecture vmtest was built for. * Under which machine architecture to run the kernel. diff --git a/docs/rootfs.md b/docs/rootfs.md new file mode 100644 index 0000000..2945f0d --- /dev/null +++ b/docs/rootfs.md @@ -0,0 +1,52 @@ +# Getting a rootfs + +There are many ways to produce a directory to pass to the `rootfs` config field, +here are a couple of potential solutions. + +## From a container image + +OCI images can be turned into tarballs which can be extracted into a rootfs. For +example: + +```sh +❯❯ mkdir $rootfs_dir && cd $rootfs_dir +❯❯ cat > Containerfile +FROM docker.io/library/debian +RUN apt update +RUN apt install -y qemu-guest-agent + +❯❯ podman build -t deb-qga # Docker would work exactly the same +❯❯ podman export -o deb.tar $(podman create deb-qga) +❯❯ tar xf deb.tar +❯❯ rm Containerfile deb.tar +``` + +## Using mkosi + +[`mkosi`](https://github.com/systemd/mkosi) is a more advanced tool for building +OS images, as well as just producing a rootfs it can build full disk images with +a bootloader, plus many other features. You'll need to refer to the full +documentation to really understand `mkosi`, but here's a minimal example. This +will only work if you host system has `apt` (on Ubuntu you'll also need to +install the `debian-archive-keyring` package), otherwise you'll need to adapt it +for your host distro or run it in a container. + +`mkosi.conf`: + +```ini +[Output] +Format=directory + +[Distribution] +Distribution=debian +Release=bookworm + +[Content] +Packages= + mount + qemu-guest-agent +``` + +Then from the directory containing that file, run `mkosi -f`. This should +produce a directory named `image` that you can use for your `rootfs` config +field. \ No newline at end of file