man: explain various qemu booting options

diff --git a/man/mkosi.1 b/man/mkosi.1
index 3e7f30d6ea932eb5bfaef2965e9077f0a6c62d94..07312db19d41f5a3b4e3141b42d629f369711c51 100644 (file)
--- a/man/mkosi.1
+++ b/man/mkosi.1
@@ -88,8 +88,8 @@ Similar to \f[V]boot\f[R], but uses \f[V]qemu\f[R] to boot up the image,
 i.e.\ instead of container virtualization virtual machine virtualization
 is used.
 This verb is only supported for disk images that contain a boot loader.
-Any options specified after the \f[V]qemu\f[R] verb are appended to the
-\f[V]qemu\f[R] invocation.
+Any arguments specified after the \f[V]qemu\f[R] verb are appended to
+the \f[V]qemu\f[R] invocation.
 .TP
 \f[V]ssh\f[R]
 When the image is built with the \f[V]Ssh=yes\f[R] option, this command
@@ -1440,6 +1440,67 @@ EOF
 # systemd-nspawn -bi image.raw
 \f[R]
 .fi
+.SS Different ways to boot with \f[V]qemu\f[R]
+.PP
+The easiest way to boot a virtual machine is to build an image with the
+required components and let \f[V]mkosi\f[R] call \f[V]qemu\f[R] with all
+the right options:
+.IP
+.nf
+\f[C]
+$ mkosi -d fedora \[rs]
+    --autologin \[rs]
+    -p systemd-udev,systemd-boot,dracut,kernel-core \[rs]
+    build
+$ mkosi -d fedora qemu
+\&...
+fedora login: root (automatic login)
+[root\[at]fedora \[ti]]#
+\f[R]
+.fi
+.PP
+The default is to boot with a text console only.
+To boot with a graphical window, add \f[V]--qemu-qui\f[R]:
+.IP
+.nf
+\f[C]
+$ mkosi -d fedora --qemu-gui qemu
+\f[R]
+.fi
+.PP
+A kernel may be booted directly with
+\f[V]mkosi qemu -kernel ... -initrd ... -append \[aq]...\[aq]\f[R].
+This is a bit faster because no boot loader is used, and it is also
+easier to experiment with different kernels and kernel commandlines.
+Note that despite the name, qemu\[cq]s \f[V]-append\f[R] option replaces
+the default kernel commandline embedded in the kernel and any previous
+\f[V]-append\f[R] specifications.
+.PP
+\f[V]mkosi\f[R] builds a Unified Kernel Image (UKI).
+It is also copied into the output directory and may be booted directly:
+.IP
+.nf
+\f[C]
+# mkosi qemu -kernel mkosi.output/fedora\[ti]38/image.efi
+\f[R]
+.fi
+.PP
+When booting using an external kernel, we don\[cq]t need the kernel
+\f[I]in\f[R] the image, but we would still want the kernel modules to be
+installed.
+.PP
+It is also possible to do a \[lq]direct kernel boot\[rq] into a boot
+loader, taking advantage of the fact that \f[V]systemd-boot(7)\f[R] is a
+valid UEFI binary:
+.IP
+.nf
+\f[C]
+# mkosi qemu -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
+\f[R]
+.fi
+.PP
+In this scenario, the kernel is loaded from the ESP in the image by
+\f[V]systemd-boot\f[R].
 .SH REQUIREMENTS
 .PP
 mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux,

diff --git a/mkosi.md b/mkosi.md
index 115854a179ccfec39b705472e4ac9293558a9be6..76d31dacca35159049059480b7647c2d7cf64b98 100644 (file)
--- a/mkosi.md
+++ b/mkosi.md
@@ -74,8 +74,8 @@ The following command line verbs are known:
 
 : Similar to `boot`, but uses `qemu` to boot up the image, i.e. instead of
   container virtualization virtual machine virtualization is used. This verb is
-  only supported for disk images that contain a boot loader. Any options specified
-  after the `qemu` verb are appended to the `qemu` invocation.
+  only supported for disk images that contain a boot loader. Any arguments
+  specified after the `qemu` verb are appended to the `qemu` invocation.
 
 `ssh`
 
@@ -1331,6 +1331,51 @@ EOF
 # systemd-nspawn -bi image.raw
 ```
 
+## Different ways to boot with `qemu`
+
+The easiest way to boot a virtual machine is to build an image with the
+required components and let `mkosi` call `qemu` with all the right options:
+```console
+$ mkosi -d fedora \
+    --autologin \
+    -p systemd-udev,systemd-boot,dracut,kernel-core \
+    build
+$ mkosi -d fedora qemu
+...
+fedora login: root (automatic login)
+[root@fedora ~]#
+```
+
+The default is to boot with a text console only.
+To boot with a graphical window, add `--qemu-qui`:
+```console
+$ mkosi -d fedora --qemu-gui qemu
+```
+
+A kernel may be booted directly with
+`mkosi qemu -kernel ... -initrd ... -append '...'`.
+This is a bit faster because no boot loader is used, and it is also
+easier to experiment with different kernels and kernel commandlines.
+Note that despite the name, qemu's `-append` option replaces
+the default kernel commandline embedded in the kernel
+and any previous `-append` specifications.
+
+`mkosi` builds a Unified Kernel Image (UKI).
+It is also copied into the output directory and may be booted directly:
+```console
+# mkosi qemu -kernel mkosi.output/fedora~38/image.efi
+```
+
+When booting using an external kernel, we don't need the kernel *in* the image,
+but we would still want the kernel modules to be installed.
+
+It is also possible to do a "direct kernel boot" into a boot loader,
+taking advantage of the fact that `systemd-boot(7)` is a valid UEFI binary:
+```console
+# mkosi qemu -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
+```
+In this scenario, the kernel is loaded from the ESP in the image by `systemd-boot`.
+
 # REQUIREMENTS
 
 mkosi is packaged for various distributions: Debian, Ubuntu, Arch