GNU bug report logs - #55613
[PATCH] doc: Document how to repair Guix System from a chroot.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55613 in the body.
You can then email your comments to 55613 AT debbugs.gnu.org in the normal way.

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

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

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: guix-patches <at> gnu.org
Cc: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Subject: [PATCH] doc: Document how to repair Guix System from a chroot.
Date: Tue, 24 May 2022 10:57:38 -0400

* doc/guix.texi (System Troubleshooting Tips): New chapter.
---
 doc/guix.texi | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 184206bec8..e09daee512 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -168,6 +168,7 @@ Weblate} (@pxref{Translating Guix}).
 * Introduction::                What is Guix about?
 * Installation::                Installing Guix.
 * System Installation::         Installing the whole operating system.
+* System Troubleshooting Tips:: When things don't go as planned.
 * Getting Started::             Your first steps.
 * Package Management::          Package installation, upgrade, etc.
 * Channels::                    Customizing the package collection.
@@ -226,6 +227,10 @@ System Installation
 * Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 
+System Troubleshooting Tips
+
+* Chrooting into an existing system::  Fixing things from a chroot
+
 Manual Installation
 
 * Keyboard Layout and Networking and Partitioning:: Initial setup.
@@ -2367,6 +2372,7 @@ See the files under @file{/run/current-system/profile/share/keymaps} for
 a list of available keyboard layouts.  Run @command{man loadkeys} for
 more information.
 
+@anchor{Manual Installation - Networking}
 @subsubsection Networking
 
 Run the following command to see what your network interfaces are called:
@@ -2820,6 +2826,119 @@ guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-b
 @code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid
 board, a list of possible boards will be printed.
 
+@c *********************************************************************
+@cindex troubleshooting, guix system
+@cindex guix system troubleshooting
+@node System Troubleshooting Tips
+@chapter System Troubleshooting Tips
+
+Guix System allows rebooting into a previous generation should the last
+one be malfunctioning, which makes it quite robust against being broken
+irreversibly.  This feature depends on GRUB being correctly functioning
+though, which means that if for whatever reasons your GRUB installation
+becomes corrupted during a system reconfiguration, you may not be able
+to easily boot into a previous generation.  A technique that can be used
+in this case is to @i{chroot} into your broken system and reconfigure it
+from there.  Such technique is explained below.
+
+@cindex chroot, guix system
+@cindex chrooting, guix system
+@cindex repairing GRUB, via chroot
+@node Chrooting into an existing system
+@section Chrooting into an existing system
+
+This section details how to @i{chroot} to an already installed Guix
+System with the aim of reconfiguring it, for example to fix a broken
+GRUB installation.  The process is similar to how it would be done on
+other GNU/Linux systems, but there are some Guix System particularities
+such as the daemon and profiles that make it worthy of explaining here.
+
+@enumerate
+@item
+Obtain a bootable image of Guix System.  It is recommended the latest
+development snapshot so the kernel and the tools used are at least as as
+new as those of your installed system; it can be retrieved from the
+@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
+https://ci.guix.gnu.org} URL.  Follow the @pxref{USB Stick and DVD
+Installation} section for copying it to a bootable media.
+
+@item
+Boot the image, and proceed with the graphical text-based installer
+until your network is configured.  Alternatively, you could configure
+the network manually by following the @pxref{Manual Installation -
+Networking} section.  If you get the error @samp{RTNETLINK answers:
+Operation not possible due to RF-kill}, try @samp{rfkill list} followed
+by @samp{rfkill unblock 0}, where @samp{0} is your device identifier
+(ID).
+
+@item
+Switch to a virtual console (tty) if you haven't already by pressing
+simultaneously the @samp{Control + Alt + F4} keys.  Mount your file
+system at @file{/mnt}.  Assuming your root partition is
+@file{/dev/sda2}, you would do:
+
+@example sh
+# mount /dev/sda2 /mnt
+@end example
+
+@item
+Mount special block devices and Linux-specific directories:
+
+@example sh
+# mount --bind /proc /mnt/proc
+# mount --bind /sys /mnt/sys
+# mount --bind /dev /mnt/dev
+@end example
+
+If your system is EFI-based, you must also mount the ESP partition.
+Assuming it is @file{/dev/sda1}, you can do so with:
+
+@example sh
+# mount /dev/sda1 /mnt/boot/efi
+@end example
+
+@item
+Enter your system via chroot:
+
+@example sh
+# chroot /mnt /bin/sh
+@end example
+
+@item
+Source your user profile to setup the environment, where
+@samp{$YOUR_USER} is adjusted to the user name used for the Guix System
+you are attempting to repair.
+
+@example sh
+sh-5.1# source /home/$YOUR_USER/.guix-profile/etc/profile
+@end example
+
+To ensure you are working with the Guix revision you normally would as
+your normal user, also source your current Guix profile:
+
+@example sh
+sh-5.1# source /home/$YOUR_USER/.config/guix/current/etc/profile
+@end example
+
+@item
+Start a minimal guix-daemon in the background:
+
+@example sh
+sh-5.1# guix-daemon --build-users-group=guixbuild --disable-chroot &
+@end example
+
+@item
+Edit your Guix System configuration if needed, then reconfigure with:
+
+@example sh
+sh-5.1# guix system reconfigure your-config.scm
+@end example
+
+@item
+Finally, you should be good to reboot the system to test your fix.
+
+@end enumerate
+
 @c *********************************************************************
 @node Getting Started
 @chapter Getting Started
-- 
2.36.0

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

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: 55613 <at> debbugs.gnu.org
Subject: Re: bug#55613: [PATCH] doc: Document how to repair Guix System from
 a chroot.
Date: Tue, 31 May 2022 16:10:21 +0200

Hi!

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> skribis:

> * doc/guix.texi (System Troubleshooting Tips): New chapter.

That’s a much welcome addition.

Since it’s more informal than the manual, how adding it to the cookbook?
I imagine we could have other troubleshooting subsections.

Some minor typographical comments…

> +@anchor{Manual Installation - Networking}

Usually anchor names are lowercase and without spaces (I’m not sure if
it’s a hard requirement or a convention).

> +@cindex troubleshooting, guix system

“Guix System”

> +Boot the image, and proceed with the graphical text-based installer
> +until your network is configured.  Alternatively, you could configure
> +the network manually by following the @pxref{Manual Installation -
> +Networking} section.  If you get the error @samp{RTNETLINK answers:

@pxref is for use in a parenthesized expression; it cannot be used in
the middle of a sentence; in fact, no cross-reference markup can be used
in the middle of a sentence, but I recommend checking the manual
(info "(texinfo) Cross References").

> +Switch to a virtual console (tty) if you haven't already by pressing
> +simultaneously the @samp{Control + Alt + F4} keys.  Mount your file

Rather @kbd{ctrl-alt-F4}.

> +@example sh
> +# mount /dev/sda2 /mnt
> +@end example
> +
> +@item
> +Mount special block devices and Linux-specific directories:
> +
> +@example sh
> +# mount --bind /proc /mnt/proc
> +# mount --bind /sys /mnt/sys
> +# mount --bind /dev /mnt/dev
> +@end example

I’d remove the “#” prompt from examples, for easier copy/pasting
(assuming that’s an option in those circumstances :-)) and for
consistency.

> +Source your user profile to setup the environment, where
> +@samp{$YOUR_USER} is adjusted to the user name used for the Guix System
> +you are attempting to repair.
> +
> +@example sh
> +sh-5.1# source /home/$YOUR_USER/.guix-profile/etc/profile

You can use a “meta-syntactic variable” for the user name: write
@var{user}, both in the text and example.

> +@item
> +Start a minimal guix-daemon in the background:

s/a minimal guix-daemon/@command{guix-daemon}/

> +@example sh
> +sh-5.1# guix-daemon --build-users-group=guixbuild --disable-chroot &

What’s the rationale for ‘--disable-chroot’?  It’s safer to avoid it.

Thanks,
Ludo’.

Message #13 received at 55613-done <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: 55613-done <at> debbugs.gnu.org
Subject: Re: bug#55613: [PATCH] doc: Document how to repair Guix System from
 a chroot.
Date: Tue, 14 Jun 2022 15:22:54 -0400

Hi Ludovic,

Ludovic Courtès <ludo <at> gnu.org> writes:

> Hi!
>
> Maxim Cournoyer <maxim.cournoyer <at> gmail.com> skribis:
>
>> * doc/guix.texi (System Troubleshooting Tips): New chapter.
>
> That’s a much welcome addition.
>
> Since it’s more informal than the manual, how adding it to the cookbook?
> I imagine we could have other troubleshooting subsections.

I think I'd prefer keeping this one in the reference manual, as that
seems the most natural place to consult first when looking for ways to
fix an unbootable Guix System.  Alternatively, we could have some
section stub simply cross-referencing the Cookbook, but I prefer the
former for now.

> Some minor typographical comments…
>
>> +@anchor{Manual Installation - Networking}
>
> Usually anchor names are lowercase and without spaces (I’m not sure if
> it’s a hard requirement or a convention).

Convention it seems; although you can't use periods, commas, colons or
leading parenthesis (per info "(texinfo) Node Line Requirements").  I've
now made it 'manual-installation-networking'.

>> +@cindex troubleshooting, guix system
>
> “Guix System”
>
>> +Boot the image, and proceed with the graphical text-based installer
>> +until your network is configured.  Alternatively, you could configure
>> +the network manually by following the @pxref{Manual Installation -
>> +Networking} section.  If you get the error @samp{RTNETLINK answers:
>
> @pxref is for use in a parenthesized expression; it cannot be used in
> the middle of a sentence; in fact, no cross-reference markup can be used
> in the middle of a sentence, but I recommend checking the manual
> (info "(texinfo) Cross References").

It seems like @ref can be used "*within* or, more often, at the end of a
sentence", per the above manual, which I'm now using.

>> +Switch to a virtual console (tty) if you haven't already by pressing
>> +simultaneously the @samp{Control + Alt + F4} keys.  Mount your file
>
> Rather @kbd{ctrl-alt-F4}.

Neat, I had forgotten about that one.

>> +@example sh
>> +# mount /dev/sda2 /mnt
>> +@end example
>> +
>> +@item
>> +Mount special block devices and Linux-specific directories:
>> +
>> +@example sh
>> +# mount --bind /proc /mnt/proc
>> +# mount --bind /sys /mnt/sys
>> +# mount --bind /dev /mnt/dev
>> +@end example
>
> I’d remove the “#” prompt from examples, for easier copy/pasting
> (assuming that’s an option in those circumstances :-)) and for
> consistency.

It should be possible, supposing you are following this Guix Reference
manual in the TTY1 of the bootable installation image; although I'm not
sure you can copy-paste between TTYs; adjusted!

>> +Source your user profile to setup the environment, where
>> +@samp{$YOUR_USER} is adjusted to the user name used for the Guix System
>> +you are attempting to repair.
>> +
>> +@example sh
>> +sh-5.1# source /home/$YOUR_USER/.guix-profile/etc/profile
>
> You can use a “meta-syntactic variable” for the user name: write
> @var{user}, both in the text and example.

Cool trick, thanks!

>> +@item
>> +Start a minimal guix-daemon in the background:
>
> s/a minimal guix-daemon/@command{guix-daemon}/

Done.

>> +@example sh
>> +sh-5.1# guix-daemon --build-users-group=guixbuild --disable-chroot &
>
> What’s the rationale for ‘--disable-chroot’?  It’s safer to avoid it.

When using a chroot, it would fail before grub-install would get to run,
defeating the purpose.  It's perhaps workable, but I didn't investigate.

I've now pushed as 4e93ca70da.  Thanks for the review!

Maxim

Previous Next

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