[PATCH] doc: Document how to repair Guix System from a chroot.

  • Done
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • Maxim Cournoyer
Owner
unassigned
Submitted by
Maxim Cournoyer
Severity
normal
M
M
Maxim Cournoyer wrote on 24 May 2022 16:57
(address . guix-patches@gnu.org)(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
20220524145738.4547-1-maxim.cournoyer@gmail.com
* doc/guix.texi (System Troubleshooting Tips): New chapter.
---
doc/guix.texi | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 119 insertions(+)

Toggle diff (153 lines)
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
L
L
Ludovic Courtès wrote on 31 May 2022 16:10
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)(address . 55613@debbugs.gnu.org)
87mtexyer6.fsf@gnu.org
Hi!

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

Toggle quote (2 lines)
> * 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…

Toggle quote (2 lines)
> +@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).

Toggle quote (2 lines)
> +@cindex troubleshooting, guix system

“Guix System”

Toggle quote (5 lines)
> +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").

Toggle quote (3 lines)
> +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}.

Toggle quote (13 lines)
> +@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.

Toggle quote (7 lines)
> +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.

Toggle quote (3 lines)
> +@item
> +Start a minimal guix-daemon in the background:

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

Toggle quote (3 lines)
> +@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’.
M
M
Maxim Cournoyer wrote on 14 Jun 2022 21:22
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 55613-done@debbugs.gnu.org)
87fsk7dp81.fsf@gmail.com
Hi Ludovic,

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

Toggle quote (11 lines)
> Hi!
>
> Maxim Cournoyer <maxim.cournoyer@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.

Toggle quote (7 lines)
> 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'.

Toggle quote (14 lines)
>> +@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.

Toggle quote (5 lines)
>> +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.

Toggle quote (17 lines)
>> +@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!

Toggle quote (10 lines)
>> +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!

Toggle quote (5 lines)
>> +@item
>> +Start a minimal guix-daemon in the background:
>
> s/a minimal guix-daemon/@command{guix-daemon}/

Done.

Toggle quote (5 lines)
>> +@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
Closed
?