[PATCH 0/1] Show to use vm-image

[PATCH 0/1] Show to use vm-image

[Leo Famulari]

This patch on the manual explains how to use the output of
`guix system vm-image`.

Thoughts?

It seems wrong to repeat the command-line like that, but I don't know a
better way to explain the elements of the command. On the other hand,
the annotated version is hard to read as a command-line. Should it
change somehow, or is it fine?

I tried booting i686 on x86_64 and it didn't work, so I didn't mention
the possibility.

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

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

-- 
2.6.4

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

[Leo Famulari]

* 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

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

[Leo Famulari]

On Fri, Jan 15, 2016 at 05:12:24AM -0500, Leo Famulari wrote:
> * 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(-)

Does anyone have feedback on this addition to the manual?

I'd like to have _something_ like it in the manual so that totally new
users can try GuixSD.

> 
> 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
> 
> 

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

[Ludovic Courtès]

Leo Famulari <leo@famulari.name> skribis:

> * doc/guix.texi (Invoking guix system): Explain how to boot the QEMU
> images created by vm-image.

Hey!  Sorry for the looong delay!  I think this is a useful addition.

> @@ -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.

I’m thinking there are often questions about using GuixSD in a VM etc.,
so it may well deserve one or two sections of its own.

What about leaving the above sentence here, and appending:

  @xref{Running GuixSD in a VM}, for more information on how to run the
  image in a virtual machine.

?

The rest of the material you added would then go to the new “Running
GuixSD in a VM” section, which could go maybe right after “Invoking guix
system”.  WDYT?

> +When using @code{vm-image}, the returned image is in qcow2 format, which
> +the QEMU emulator can efficiently use.

In the new section, this would need to be slightly adjusted to give more
context, like:

  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 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

I think it would be nicer to put it on 3 lines.

> +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

I would typeset it as:

  @table @code
  @item qemu-system-x86_64
  This specifies the hardware platform to…

  @item -net user
  Enable unpriviliged user-mode networking…
  …

  @end @table

With all this, it’s going to look perfect!  :-)

Another question that people often ask is how to install GuixSD from the
installation image in a VM.  Maybe that could be added eventually in a
subsection of this new node?

Thank you!

Ludo’.

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

[Leo Famulari]

On Sun, Jan 24, 2016 at 06:32:57PM +0100, Ludovic Courtès wrote:
> Leo Famulari <leo@famulari.name> skribis:
> 
> > * doc/guix.texi (Invoking guix system): Explain how to boot the QEMU
> > images created by vm-image.
> 

[...]

> I’m thinking there are often questions about using GuixSD in a VM etc.,
> so it may well deserve one or two sections of its own.
> 
> What about leaving the above sentence here, and appending:
> 
>   @xref{Running GuixSD in a VM}, for more information on how to run the
>   image in a virtual machine.
> 
> ?
> 
> The rest of the material you added would then go to the new “Running
> GuixSD in a VM” section, which could go maybe right after “Invoking guix
> system”.  WDYT?

That sounds good, done!

> 
> > +When using @code{vm-image}, the returned image is in qcow2 format, which
> > +the QEMU emulator can efficiently use.
> 
> In the new section, this would need to be slightly adjusted to give more
> context, like:
> 
>   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.

Thanks for this :)

[...]

> > +@example
> > +$ qemu-system-x86_64 \
> > +-net user \
> > +-net nic,model=virtio \
> > +-enable-kvm \
> > +-m 256 \
> > +/tmp/qemu-image
> > +@end example
> 
> I think it would be nicer to put it on 3 lines.

Done.

[...]

> I would typeset it as:
> 
>   @table @code
>   @item qemu-system-x86_64
>   This specifies the hardware platform to…
> 
>   @item -net user
>   Enable unpriviliged user-mode networking…
>   …
> 
>   @end @table
> 
> With all this, it’s going to look perfect!  :-)

Thank you for this example. I really need to study what Texinfo can do.

> 
> Another question that people often ask is how to install GuixSD from the
> installation image in a VM.  Maybe that could be added eventually in a
> subsection of this new node?

I agree, that would be useful. If anybody knows how to do that, they
should chime in.

> 
> Thank you!

Thanks for your helpful feedback!

> 
> Ludo’.