[DOCUMENTATION] doc: Include steps for mounting EFI partitions.

  • Done
  • quality assurance status badge
Details
3 participants
  • Christina O'Donnell
  • Ludovic Courtès
  • Maxim Cournoyer
Owner
unassigned
Submitted by
Christina O'Donnell
Severity
normal
C
C
Christina O'Donnell wrote on 15 Oct 2023 14:00
(address . guix-patches@gnu.org)(name . Christina O'Donnell)(address . cdo@mutix.org)
655dcf80f8770bd887d5c5305335d880cef7fec5.1697371222.git.cdo@mutix.org
This patch ammends the Chrooting section of the Guix manual to help EFI users
who have misconfigured their bootloader. This was neccessary for me after the
first couple botched installation attempts.

* doc/guix.texi (Chrooting into an existing system): Add missing mounts for
repairing broken EFI partitions.
---
doc/guix.texi | 32 ++++++++++++++++++++++++++++++--
1 file changed, 30 insertions(+), 2 deletions(-)

Toggle diff (47 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 3517c95251..72909fc0cb 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3046,8 +3046,36 @@ Chrooting into an existing system
mount --rbind /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:
+@item
+There are a few more steps for those who are on EFI-based systems. If
+you're using another bootloader method then you may safely skip these.
+They are adapted from @url{https://wiki.debian.org/GrubEFIReinstall, a
+page on the Debian Wiki}.
+
+@item
+Verify that you are booting in from UEFI by checking that
+@file{/sys/firmware/efi} isn't empty.
+
+@item
+If the directory @file{/sys/firmware/efi/efivars} is empty, you need to
+boot the rescue system including the kernel option "efi=runtime" and
+mount the EFI variables before proceeding:
+
+@example sh
+mount -t efivarfs none /sys/firmware/efi/efivars
+@end example
+
+@item
+If your bootloader installation failed, you may need to bind
+@file{efivars} between the two systems.
+
+@example sh
+mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
+@end example
+
+@item
+You also need to mount the ESP partition. Assuming it is
+@file{/dev/sda1}, you can do so with:
@example sh
mount /dev/sda1 /mnt/boot/efi

base-commit: d2923babf3ac44cb6faa88317f77c98f3016820d
--
2.41.0
L
L
Ludovic Courtès wrote on 26 Oct 2023 22:54
(address . 66560@debbugs.gnu.org)
87edhh14vd.fsf@gnu.org
Hi Christina,

Christina O'Donnell <cdo@mutix.org> skribis:

Toggle quote (7 lines)
> This patch ammends the Chrooting section of the Guix manual to help EFI users
> who have misconfigured their bootloader. This was neccessary for me after the
> first couple botched installation attempts.
>
> * doc/guix.texi (Chrooting into an existing system): Add missing mounts for
> repairing broken EFI partitions.

At first sight that looks good to me. Maxim, could you confirm? (I
think you’re the initial author of this part.)

The patch probably needs rebasing due to commit
978b9619a8adcf884b672db48facca9414f3070c.

Thanks,
Ludo’.
M
M
Maxim Cournoyer wrote on 31 Oct 2023 18:54
(name . Christina O'Donnell)(address . cdo@mutix.org)
87y1fiptil.fsf@gmail.com
Hi!

Thanks for attempting to improve the documentation!

Christina O'Donnell <cdo@mutix.org> writes:

Toggle quote (26 lines)
> This patch ammends the Chrooting section of the Guix manual to help EFI users
> who have misconfigured their bootloader. This was neccessary for me after the
> first couple botched installation attempts.
>
> * doc/guix.texi (Chrooting into an existing system): Add missing mounts for
> repairing broken EFI partitions.
> ---
> doc/guix.texi | 32 ++++++++++++++++++++++++++++++--
> 1 file changed, 30 insertions(+), 2 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 3517c95251..72909fc0cb 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -3046,8 +3046,36 @@ Chrooting into an existing system
> mount --rbind /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:
> +@item
> +There are a few more steps for those who are on EFI-based systems. If
> +you're using another bootloader method then you may safely skip these.
> +They are adapted from @url{https://wiki.debian.org/GrubEFIReinstall, a
> +page on the Debian Wiki}.

It seems odd to use an item entry like the above; I'd use nested
enumeration at that point instead.

Toggle quote (4 lines)
> +@item
> +Verify that you are booting in from UEFI by checking that
> +@file{/sys/firmware/efi} isn't empty.

If you look at the latest manual, this should not be empty since mount
--rbind is used (the 'r' in the name is for recursive) for the whole
/sys directory:

mount --rbind /proc /mnt/proc
mount --rbind /sys /mnt/sys
mount --rbind /dev /mnt/dev

Toggle quote (9 lines)
> +@item
> +If the directory @file{/sys/firmware/efi/efivars} is empty, you need to
> +boot the rescue system including the kernel option "efi=runtime" and
> +mount the EFI variables before proceeding:
> +
> +@example sh
> +mount -t efivarfs none /sys/firmware/efi/efivars
> +@end example

Maybe the only information missing here is the "if empty, run with
"efi=runtime" bit? Also note that the latest version of the manually
mentions using Guix System rather than another live rescue image, so
perhaps it just wouldn't happen then? It seems we assume that
/sys/firmware/efi exists for UEFI systems in the documentation
elswehere, without having to mention that "efi=runtime" bit, so I'm
inclined to think it's not necessary for Guix System.

Toggle quote (8 lines)
> +@item
> +If your bootloader installation failed, you may need to bind
> +@file{efivars} between the two systems.
> +
> +@example sh
> +mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
> +@end example

This should be covered by the --rbind, asusming the host contains
/sys/firmware/efi/efivars.

So I think we don't need to change anything to the manual. If the
"efi=runtime" advice is truly useful even on Guix System, we could
mention it like so:

Toggle snippet (14 lines)
modified doc/guix.texi
@@ -43075,6 +43075,11 @@ Chrooting into an existing system
mount /dev/sda1 /mnt/boot/efi
@end example
+If using an EFI-based system, also make sure that the directory
+@file{/sys/firmware/efi/efivars} is @emph{not} empty. If it is empty,
+you will need to reboot your rescue system with the kernel option
+@option{efi=runtime} and redo the steps from the beginning.
+
@item
Enter your system via chroot:

--
Thanks,
Maxim
C
C
Christina O'Donnell wrote on 1 Nov 2023 10:51
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
aa68ca40-24cb-cfef-77a6-69020b3c5f3c@mutix.org
Hi Maxim,

Thank you for your time and comments.

> If you look at the latest manual, this should not be empty since mount
> --rbind is used (the 'r' in the name is for recursive) for the whole
> /sys directory:
>
>           mount --rbind /proc /mnt/proc
>           mount --rbind /sys /mnt/sys
>           mount --rbind /dev /mnt/dev

Yes! I see the latest one uses --rbind while the 1.4.0 manual that I
was following uses --bind. I didn't see the change, but that should be
sufficient.

>> +@item
>> +If the directory @file{/sys/firmware/efi/efivars} is empty, you need to
>> +boot the rescue system including the kernel option "efi=runtime" and
>> +mount the EFI variables before proceeding:
>> +
>> +@example sh
>> +mount -t efivarfs none /sys/firmware/efi/efivars
>> +@end example
>
> Maybe the only information missing here is the "if empty, run with
> "efi=runtime" bit?  Also note that the latest version of the manually
> mentions using Guix System rather than another live rescue image, so
> perhaps it just wouldn't happen then?  It seems we assume that
> /sys/firmware/efi exists for UEFI systems in the documentation
> elswehere, without having to mention that "efi=runtime" bit, so I'm
> inclined to think it's not necessary for Guix System.

I don't think "efi=runtime" is necessary (and I couldn't it in the
kernel documentation).I did run into this problem on the Guix System
installer. I think now that my problem must have been caused by using
'--bind' (without the "r"). Since the installer uses an UEFI
bootloader, I doubt any further steps are needed as you say.

>> +@item
>> +If your bootloader installation failed, you may need to bind
>> +@file{efivars} between the two systems.
>> +
>> +@example sh
>> +mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
>> +@end example
>
> This should be covered by the --rbind, asusming the host contains
> /sys/firmware/efi/efivars.
>
> So I think we don't need to change anything to the manual. If the
> "efi=runtime" advice is truly useful even on Guix System, we could
> mention it like so:
>

I agree. I'm happy for this patch/issue to be closed. Thank you for
reviewing this!

Kind regards,
 - Christina
M
M
Maxim Cournoyer wrote on 1 Nov 2023 17:23
(name . Christina O'Donnell)(address . cdo@mutix.org)
871qd9o326.fsf@gmail.com
Hi Christina,

Christina O'Donnell <cdo@mutix.org> writes:

Toggle quote (16 lines)
> Hi Maxim,
>
> Thank you for your time and comments.
>
>> If you look at the latest manual, this should not be empty since mount
>> --rbind is used (the 'r' in the name is for recursive) for the whole
>> /sys directory:
>>
>>           mount --rbind /proc /mnt/proc
>>           mount --rbind /sys /mnt/sys
>>           mount --rbind /dev /mnt/dev
>
> Yes! I see the latest one uses --rbind while the 1.4.0 manual that I
> was following uses --bind. I didn't see the change, but that should be
> sufficient.

[...]

Toggle quote (6 lines)
> I don't think "efi=runtime" is necessary (and I couldn't it in the
> kernel documentation).I did run into this problem on the Guix System
> installer. I think now that my problem must have been caused by using
> '--bind' (without the "r"). Since the installer uses an UEFI
> bootloader, I doubt any further steps are needed as you say.

[...]

Toggle quote (11 lines)
>> This should be covered by the --rbind, asusming the host contains
>> /sys/firmware/efi/efivars.
>>
>> So I think we don't need to change anything to the manual. If the
>> "efi=runtime" advice is truly useful even on Guix System, we could
>> mention it like so:
>>
>
> I agree. I'm happy for this patch/issue to be closed. Thank you for
> reviewing this!

OK! Thanks for getting back to us. Closing!

--
Maxim
Closed
?