* doc/guix.texi (Invoking guix system): Explain how to boot the QEMU
images created by vm-image.
---
doc/guix.texi | 41 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 38 insertions(+), 3 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index e583e8c..51165b4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -9058,9 +9058,6 @@ Return a virtual machine or disk image of the operating
system declared
in @var{file} that stands alone. Use the @option{--image-size} option
to specify the size of the image.
-When using @code{vm-image}, the returned image is in qcow2 format, which
-the QEMU emulator can efficiently use.
-
When using @code{disk-image}, a raw disk image is produced; it can be
copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
the device corresponding to a USB stick, one can copy the image on it
@@ -9070,6 +9067,44 @@ using the following command:
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example
+When using @code{vm-image}, the returned image is in qcow2 format, which
+the QEMU emulator can efficiently use.
+
+To run the image in QEMU, copy it out of the store and give yourself
+permission to write to the copy. When invoking QEMU, you must choose a
+system emulator that is suitable for your hardware platform. Here is a
+minimal QEMU invocation that will boot GuixSD on x86_64 hardware:
+
+@example
+$ qemu-system-x86_64 \
+-net user \
+-net nic,model=virtio \
+-enable-kvm \
+-m 256 \
+/tmp/qemu-image
+@end example
+
+And the annotated version:
+
+@example
+# Hardware platform to emulate. This should match the host.
+$ qemu-system-x86_64 \
+# Unpriviliged user mode networking. Guest can access host but not vice
+# versa. If you don't choose a network stack, the boot will fail.
+-net user \
+# You must create a network interface of a given model. If you don't
+# create a NIC, the boot will fail. You can get a list of available NIC
+# models by running `qemu-system-x86_64 -net nic,model=help`.
+-net nic,model=virtio \
+# If your system is x86 with hardware virtualization extensions,
+# enabling the kernel virtual machine will make things run faster.
+-enable-kvm \
+# RAM available to the guest OS. Defaults to 128 megabytes, which is not
+# enough for the Guix daemon.
+-m 256 \
+/tmp/qemu-image
+@end example
+
@item container
Return a script to run the operating system declared in @var{file}
within a container. Containers are a set of lightweight isolation
--
2.6.4
