01/01: doc: Show how to boot result of 'vm-image'.

[Leo Famulari]

lfam pushed a commit to branch master
in repository guix.

commit 97d76250e18009e7ef3d0df2ccc15d34432f6bc2
Author: Leo Famulari <address@hidden>
Date:   Sun Jan 24 16:04:35 2016 -0500

    doc: Show how to boot result of 'vm-image'.
    
    * doc/guix.texi (Running GuixSD in a VM): New node.
    (Invoking guix system): Add reference to 'Running GuixSD in a VM'.
---
 doc/guix.texi |   60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 8476408..a6ba948 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -15,8 +15,8 @@ Copyright @copyright{} 2013, 2014 Andreas address@hidden
 Copyright @copyright{} 2013 Nikita address@hidden
 Copyright @copyright{} 2015 Mathieu address@hidden
 Copyright @copyright{} 2014 Pierre-Antoine address@hidden
-Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
-Copyright @copyright{} 2015 Leo Famulari
+Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/address@hidden
+Copyright @copyright{} 2015, 2016 Leo Famulari
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -175,6 +175,7 @@ System Configuration
 * Initial RAM Disk::            Linux-Libre bootstrapping.
 * GRUB Configuration::          Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
+* Running GuixSD in a VM::      How to run GuixSD in a virtual machine.
 * Defining Services::           Adding new service definitions.
 
 Services
@@ -5694,6 +5695,7 @@ instance to support new system services.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
 * GRUB Configuration::          Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
+* Running GuixSD in a VM::      How to run GuixSD in a virtual machine.
 * Defining Services::           Adding new service definitions.
 @end menu
 
@@ -9195,7 +9197,8 @@ 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.
+the QEMU emulator can efficiently use. @xref{Running GuixSD in a VM},
+for more information on how to run the image in a virtual machine.
 
 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
@@ -9334,6 +9337,57 @@ graph} of dmd services of the operating system defined 
in @var{file}.
 
 @end table
 
address@hidden Running GuixSD in a VM
address@hidden Running GuixSD in a virtual machine
+
+One way to run GuixSD in a virtual machine (VM) is to build a GuixSD
+virtual machine image using @command{guix system vm-image}
+(@pxref{Invoking guix system}).  The returned image is in qcow2 format,
+which the @uref{http://qemu.org/, QEMU emulator} can efficiently use.
+
+To run the image in QEMU, copy it out of the store (@pxref{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 the result
+of @command{guix system vm-image} on x86_64 hardware:
+
address@hidden
+$ qemu-system-x86_64 \
+   -net user -net nic,model=virtio \
+   -enable-kvm -m 256 /tmp/qemu-image
address@hidden example
+
+Here is what each of these options means:
+
address@hidden @code
address@hidden qemu-system-x86_64
+This specifies the hardware platform to emulate.  This should match the
+host.
+
address@hidden -net user
+Enable the unprivileged user-mode network stack.  The guest OS can
+access the host but not vice versa.  This is the simplest way to get the
+guest OS online.  If you don't choose a network stack, the boot will
+fail.
+
address@hidden -net nic,model=virtio
+You must create a network interface of a given model.  If you don't
+create a NIC, the boot will fail.  Assuming your hardware platform is
+x86_64, you can get a list of available NIC models by running
address@hidden -net nic,model=help}.
+
address@hidden -enable-kvm
+If your system has hardware virtualization extensions, enabling the
+Linux kernel's virtual machine support (KVM) will make things run
+faster.
+
address@hidden -m 256
+RAM available to the guest OS, in mebibytes.  Defaults to address@hidden,
+which may be insufficent for some operations.
+
address@hidden /tmp/qemu-image
+The file name of the qcow2 image.
address@hidden table
 
 @node Defining Services
 @subsection Defining Services