[v2 0/1] Revised QEMU instructions for manual

[v2 0/1] Revised QEMU instructions for manual

[Leo Famulari]

Here is my revised patch adding to the manual instructions on how to
boot the output of `guix system vm-image`.

Thoughts?

Leo Famulari (1):
  doc: Show how to boot result of 'vm-image'.

 doc/guix.texi | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

-- 
2.7.0.rc3

[v2 1/1] doc: Show how to boot result of 'vm-image'.

[Leo Famulari]

* doc/guix.texi (Running GuixSD in a VM): New node.
(Invoking guix system): Add reference to 'Running GuixSD in a VM'.
---
 doc/guix.texi | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 4ce6ef5..cd5ced4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -15,8 +15,8 @@ Copyright @copyright{} 2013, 2014 Andreas Enge@*
 Copyright @copyright{} 2013 Nikita Karetnikov@*
 Copyright @copyright{} 2015 Mathieu Lirzin@*
 Copyright @copyright{} 2014 Pierre-Antoine Rault@*
-Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
-Copyright @copyright{} 2015 Leo Famulari
+Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
+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
@@ -174,6 +174,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
@@ -5693,6 +5694,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
 
@@ -9193,7 +9195,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
@@ -9332,6 +9335,55 @@ graph} of dmd services of the operating system defined in @var{file}.
 
 @end table
 
+@node Running GuixSD in a VM
+@subsection Running GuixSD in a VM
+
+One way to run GuixSD in a virtual machine 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:
+
+@example
+$ qemu-system-x86_64 \
+-net user -net nic,model=virtio \
+-enable-kvm -m 256 /tmp/qemu-image
+@end example
+
+And the annotated version:
+
+@table @code
+@item qemu-system-x86_64
+This specifies the hardware platform to emulate. This should match the
+host.
+
+@item -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.
+
+@item -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
+`qemu-system-x86_64 -net nic,model=help`.
+
+@item -enable-kvm
+If your system has hardware virtualization extensions, enabling the
+kernel virtual machine will make things run faster.
+
+@item -m 256
+RAM available to the guest OS, in megabytes. Defaults to 128 megabytes,
+which is not enough for the Guix daemon.
+
+@item /tmp/qemu-image
+The filesystem path of the qcow2 image.
+@end table
 
 @node Defining Services
 @subsection Defining Services
-- 
2.7.0.rc3

Re: [v2 1/1] doc: Show how to boot result of 'vm-image'.

[Ludovic Courtès]

Leo Famulari <leo@famulari.name> skribis:

> * doc/guix.texi (Running GuixSD in a VM): New node.
> (Invoking guix system): Add reference to 'Running GuixSD in a VM'.

[...]

> +@node Running GuixSD in a VM
> +@subsection Running GuixSD in a VM

s/VM/virtual machine/ on the second line.

> +One way to run GuixSD in a virtual machine is to build a GuixSD virtual

After “virtual machine”, add “(VM)” to introduce the acronym.

> +machine image using @command{guix system vm-image} (@pxref{Invoking guix
> +system}). The returned image is in qcow2 format, which the
           ^^
Please make sure that all the end-of-sentence periods are followed by
two spaces or a newline (info "(texinfo) Not Ending a Sentence").

> +$ qemu-system-x86_64 \
> +-net user -net nic,model=virtio \
> +-enable-kvm -m 256 /tmp/qemu-image

Would be nice to align the 2nd and 3rd line below the ‘e’ of ‘qemu’.

> +And the annotated version:

Maybe “Here is what each of these options means:”.

> +x86_64, you can get a list of available NIC models by running
> +`qemu-system-x86_64 -net nic,model=help`.

Instead of backquotes, use @command{…}.

> +@item -enable-kvm
> +If your system has hardware virtualization extensions, enabling the
> +kernel virtual machine will make things run faster.

s/kernel virtual machine/Linux kernel's virtual machine support (KVM)/

> +@item -m 256
> +RAM available to the guest OS, in megabytes. Defaults to 128 megabytes,
> +which is not enough for the Guix daemon.

“Defaults to 128@tie{}MiB, which may be insufficient for some
operations.”  (It’s not the daemon specifically, it’s mostly if you want
to run X + Xfce, for instance.  The former ‘guix substitute’ used to
take quite a lot of memory, but I think that’s no longer the case since
we switched to HTTP pipelining.)

> +@item /tmp/qemu-image
> +The filesystem path of the qcow2 image.

s/filesystem path/file name/

OK with these changes, thanks a lot!

Ludo’.

Re: [v2 1/1] doc: Show how to boot result of 'vm-image'.

[Leo Famulari]

On Tue, Jan 26, 2016 at 11:08:09AM +0100, Ludovic Courtès wrote:
> Leo Famulari <leo@famulari.name> skribis:
> 
> > * doc/guix.texi (Running GuixSD in a VM): New node.
> > (Invoking guix system): Add reference to 'Running GuixSD in a VM'.
> 
> [...]
> 
> > +@node Running GuixSD in a VM
> > +@subsection Running GuixSD in a VM
> 
> s/VM/virtual machine/ on the second line.
> 
> > +One way to run GuixSD in a virtual machine is to build a GuixSD virtual
> 
> After “virtual machine”, add “(VM)” to introduce the acronym.
> 
> > +machine image using @command{guix system vm-image} (@pxref{Invoking guix
> > +system}). The returned image is in qcow2 format, which the
>            ^^
> Please make sure that all the end-of-sentence periods are followed by
> two spaces or a newline (info "(texinfo) Not Ending a Sentence").
> 
> > +$ qemu-system-x86_64 \
> > +-net user -net nic,model=virtio \
> > +-enable-kvm -m 256 /tmp/qemu-image
> 
> Would be nice to align the 2nd and 3rd line below the ‘e’ of ‘qemu’.
> 
> > +And the annotated version:
> 
> Maybe “Here is what each of these options means:”.
> 
> > +x86_64, you can get a list of available NIC models by running
> > +`qemu-system-x86_64 -net nic,model=help`.
> 
> Instead of backquotes, use @command{…}.
> 
> > +@item -enable-kvm
> > +If your system has hardware virtualization extensions, enabling the
> > +kernel virtual machine will make things run faster.
> 
> s/kernel virtual machine/Linux kernel's virtual machine support (KVM)/
> 
> > +@item -m 256
> > +RAM available to the guest OS, in megabytes. Defaults to 128 megabytes,
> > +which is not enough for the Guix daemon.
> 
> “Defaults to 128@tie{}MiB, which may be insufficient for some
> operations.”  (It’s not the daemon specifically, it’s mostly if you want
> to run X + Xfce, for instance.  The former ‘guix substitute’ used to
> take quite a lot of memory, but I think that’s no longer the case since
> we switched to HTTP pipelining.)

I hit this limit while using the "bare-bones" configuration template.
The system would boot with 128 MiB of RAM but any operations using the
daemon would fail.

Also, I looked into how QEMU interprets "megabyte" et al. From the QEMU
source file "include/qemu-common.h":
#define M_BYTE     (1ULL << 20)

So, I replaced "megabyte" with "mebibyte" in this paragraph.

> 
> > +@item /tmp/qemu-image
> > +The filesystem path of the qcow2 image.
> 
> s/filesystem path/file name/
> 
> OK with these changes, thanks a lot!

Thanks for your help!

> 
> Ludo’.

Re: [v2 1/1] doc: Show how to boot result of 'vm-image'.

[Ludovic Courtès]

Leo Famulari <leo@famulari.name> skribis:

> On Tue, Jan 26, 2016 at 11:08:09AM +0100, Ludovic Courtès wrote:

[...]

>> “Defaults to 128@tie{}MiB, which may be insufficient for some
>> operations.”  (It’s not the daemon specifically, it’s mostly if you want
>> to run X + Xfce, for instance.  The former ‘guix substitute’ used to
>> take quite a lot of memory, but I think that’s no longer the case since
>> we switched to HTTP pipelining.)
>
> I hit this limit while using the "bare-bones" configuration template.
> The system would boot with 128 MiB of RAM but any operations using the
> daemon would fail.

Oh OK.  Well the thing is still using too much memory then (I suspect
it’s ‘guix substitute’ that’s at fault, not the C++ part of the daemon.)

> Also, I looked into how QEMU interprets "megabyte" et al. From the QEMU
> source file "include/qemu-common.h":
> #define M_BYTE     (1ULL << 20)
>
> So, I replaced "megabyte" with "mebibyte" in this paragraph.

Perfect.  :-)

Thanks,
Ludo’.