GNU bug report logs - #59846
"Running Guix in a Virtual Machine" documentation unclear/incomplete/wrong

Previous Next

To reply to this bug, email your comments to 59846 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ian Eure <ian <at> retrospec.tv>
To: bug-guix <at> gnu.org
Subject: "Running Guix in a Virtual Machine" documentation
 unclear/incomplete/wrong
Date: Mon, 05 Dec 2022 14:02:43 -0800

I’m trying to explore Guix System by running it in a VM on my 
computer which runs Debian.  I’m interested in some of the Guix 
ideas, but not ready to do a bare-metal install.

I found the download page[1] and got a copy of the QEMU image, 
then clicked "Installation instructions"[2].  These instructions 
didn’t work, because they’re incomplete and/or unclear and/or 
wrong and/or not really installation instructions in the way one 
might assume.  Since I don’t really know anything about Guix 
(which is why I’m reading the documentation and test driving it in 
a VM), I’m not sure which one-or-more of these it may be.

Specifically:

> To enable SSH inside a VM you need to add an SSH server like 
> openssh-service-type to your VM (see openssh-service-type).

The documentation doesn’t say *how* to do that.  The 
openssh-service-type link[3] takes me to a large page of code 
documentation for every possible networking service, instead of 
the openssh-service-type one specifically.  This documentation 
describes *what* the service type and its many configuration 
options is, but is silent on *how* to make use of it.

It continues:

> In addition you need to forward the SSH port, 22 by default, to 
> the host. You can do this with
> $(guix system vm config.scm) -nic 
> user,model=virtio-net-pci,hostfwd=tcp::10022-:22

I’m really not sure what this is supposed to be doing.  It can’t 
run on my Debian host, since there’s no guix command.  It errors 
inside the VM, since it can’t find a config.scm file; and I don’t 
see an obvious config.scm file anywhere inside the VM that it 
might be looking for.

I *suspect* that this documentation is actually targeted at 
running a Guix System VM on an existing Guix host.  Which is a 
chicken-and-egg problem, if I’ve already installed Guix, I don’t 
need to follow instructions to install it.

[1]: https://guix.gnu.org/en/download/
[2]: 
https://guix.gnu.org/manual/en/html_node/Running-Guix-in-a-VM.html
[3]: 
https://guix.gnu.org/manual/en/html_node/Networking-Services.html

Message #8 received at 59846 <at> debbugs.gnu.org (full text, mbox):

From: zamfofex <zamfofex <at> twdb.moe>
To: "59846 <at> debbugs.gnu.org" <59846 <at> debbugs.gnu.org>
Subject: Re: "Running Guix in a Virtual Machine" documentation
 unclear/incomplete/wrong
Date: Tue, 6 Dec 2022 09:11:38 -0300 (BRT)

Hello! As far as I understand, the QEMU image is not meant to be used for installing Guix System, but rather just trying it out.

You should instead use the “GNU Guix Sytem on Linux” image from <https://guix.gnu.org/download/latest/>

Here are some quick steps to get started:

- - - - -
% wget -Oguix.iso https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso

% qemu-img create -f qcow2 guix.qcow2 500G

% qemu-system-x86_64 -enable-kvm -m 2G -nic user -cdrom guix.iso guix.qcow2
- - - - -

You can then proceed with the installation using the pseudo‐graphical installer, then later use the installed system by using:

- - - - -
% qemu-system-x86_64 -enable-kvm -m 2G -nic user guix.qcow2
- - - - -

Here is a short video I have coincidentally recorded another day: <https://zamfofex.neocities.org/temporary/guix.mp4> (Though I might remove it at some point.)

Here is an even shorter video showing basically the same thing, but that is likely more permanent: <https://guix.gnu.org/videos/2020/system-graphical-installer/>

Message #11 received at 59846 <at> debbugs.gnu.org (full text, mbox):

From: 宋文武 <iyzsong <at> envs.net>
To: Ian Eure <ian <at> retrospec.tv>
Cc: 59846 <at> debbugs.gnu.org
Subject: Re: bug#59846: "Running Guix in a Virtual Machine" documentation
 unclear/incomplete/wrong
Date: Thu, 08 Dec 2022 14:06:18 +0800

Ian Eure <ian <at> retrospec.tv> writes:

> I’m trying to explore Guix System by running it in a VM on my computer
> which runs Debian.  I’m interested in some of the Guix ideas, but not
> ready to do a bare-metal install.

Hello!
>
> I found the download page[1] and got a copy of the QEMU image, then
> clicked "Installation instructions"[2].  These instructions didn’t
> work, because they’re incomplete and/or unclear and/or wrong and/or
> not really installation instructions in the way one might assume.
> Since I don’t really know anything about Guix (which is why I’m
> reading the documentation and test driving it in a VM), I’m not sure
> which one-or-more of these it may be.

Sorry for the not very helpful documentation, I'd say write good
documentation is very hard...
>
> Specifically:
>
>> To enable SSH inside a VM you need to add an SSH server like
>> openssh-service-type to your VM (see openssh-service-type).
>
> The documentation doesn’t say *how* to do that.  The
> openssh-service-type link[3] takes me to a large page of code
> documentation for every possible networking service, instead of the
> openssh-service-type one specifically.  This documentation describes
> *what* the service type and its many configuration options is, but is
> silent on *how* to make use of it.

This openssh-service-type should be added into the system configuration
file, it's /run/current-system/configuration.scm in the pre-built qemu
image or the file passed to 'guix system vm-image' when built your own
image.  The configuration file is a scheme (guile) file, the detail is
in the section "10.1 Using the configuration System".

>
> It continues:
>
>> In addition you need to forward the SSH port, 22 by default, to the
>> host. You can do this with
>> $(guix system vm config.scm) -nic
>> user,model=virtio-net-pci,hostfwd=tcp::10022-:22
>
> I’m really not sure what this is supposed to be doing.  It can’t run
> on my Debian host, since there’s no guix command.  It errors inside
> the VM, since it can’t find a config.scm file; and I don’t see an
> obvious config.scm file anywhere inside the VM that it might be
> looking for.
>
> I *suspect* that this documentation is actually targeted at running a
> Guix System VM on an existing Guix host.  Which is a chicken-and-egg
> problem, if I’ve already installed Guix, I don’t need to follow
> instructions to install it.

Well this 10.16 target both running a pre-built qcow guix system image
and running a 'guix system vm' built one.  But it's not self contained,
as the service things lacking commands for the former as you reported,
and the later case assume you already have guix installed (not the guix
system though).

Hope it helps!

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.