bug#30312: documentation: misleading EFI partitioning instructions

bug#30312: documentation: misleading EFI partitioning instructions

[Ricardo Wurmus]

The manual section “Preparing for Installation: Disk Partitioning” says
this:

--8<---------------cut here---------------start------------->8---
   If your disk uses the GUID Partition Table (GPT) format and you plan
to install BIOS-based GRUB (which is the default), make sure a BIOS Boot
Partition is available (*note (grub)BIOS installation::).

   If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
Partition” (ESP) is required.  This partition should be mounted at
‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:

     parted /dev/sda set 1 esp on

   Once you are done partitioning the target hard disk drive, you have
to create a file system on the relevant partition(s)(1).  For the ESP,
if you have one and assuming it is ‘/dev/sda2’, run:

     mkfs.fat -F32 /dev/sda2
--8<---------------cut here---------------end--------------->8---

First, this sounds like it’s up to the user to pick either EFI-based
GRUB or BIOS-based GRUB.  It is not clear that this is determined by
whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
really not much of a choice.

Second, the “parted” command operates on the first partition (“1”), yet
for the second command the second partition (“/dev/sda2”) is used.  It’s
better to be consistent here, i.e. to change “set 1 esp on” to “set 2
esp on” and to state that this would modify “/dev/sda2”.

Finally, it is not clear where the efi partition should be mounted.
Should it be /mnt/boot/efi?  If so, should the configuration file
specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?

An example would be useful here.

-- 
Ricardo

bug#30312: documentation: misleading EFI partitioning instructions

[Gábor Boskovits]

[-- Attachment #1: Type: text/plain, Size: 2020 bytes --]

2018-01-31 20:01 GMT+01:00 Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de>:

> The manual section “Preparing for Installation: Disk Partitioning” says
> this:
>
> --8<---------------cut here---------------start------------->8---
>    If your disk uses the GUID Partition Table (GPT) format and you plan
> to install BIOS-based GRUB (which is the default), make sure a BIOS Boot
> Partition is available (*note (grub)BIOS installation::).
>
>    If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
> Partition” (ESP) is required.  This partition should be mounted at
> ‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:
>
>      parted /dev/sda set 1 esp on
>
>    Once you are done partitioning the target hard disk drive, you have
> to create a file system on the relevant partition(s)(1).  For the ESP,
> if you have one and assuming it is ‘/dev/sda2’, run:
>
>      mkfs.fat -F32 /dev/sda2
> --8<---------------cut here---------------end--------------->8---
>
> First, this sounds like it’s up to the user to pick either EFI-based
> GRUB or BIOS-based GRUB.  It is not clear that this is determined by
> whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
> really not much of a choice.
>
> Second, the “parted” command operates on the first partition (“1”), yet
> for the second command the second partition (“/dev/sda2”) is used.  It’s
> better to be consistent here, i.e. to change “set 1 esp on” to “set 2
> esp on” and to state that this would modify “/dev/sda2”.
>
> Finally, it is not clear where the efi partition should be mounted.
> Should it be /mnt/boot/efi?  If so, should the configuration file
> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>
> An example would be useful here.
>
> I agree an example would be nice.
I will have a look at this when I have time.
I guess I had done something similar.



> --
> Ricardo
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 3832 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Gábor Boskovits]

[-- Attachment #1: Type: text/plain, Size: 2412 bytes --]

2018-02-01 10:13 GMT+01:00 Gábor Boskovits <boskovits@gmail.com>:

> 2018-01-31 20:01 GMT+01:00 Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de>:
>
>> The manual section “Preparing for Installation: Disk Partitioning” says
>> this:
>>
>> --8<---------------cut here---------------start------------->8---
>>    If your disk uses the GUID Partition Table (GPT) format and you plan
>> to install BIOS-based GRUB (which is the default), make sure a BIOS Boot
>> Partition is available (*note (grub)BIOS installation::).
>>
>>    If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
>> Partition” (ESP) is required.  This partition should be mounted at
>> ‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:
>>
>>      parted /dev/sda set 1 esp on
>>
>>    Once you are done partitioning the target hard disk drive, you have
>> to create a file system on the relevant partition(s)(1).  For the ESP,
>> if you have one and assuming it is ‘/dev/sda2’, run:
>>
>>      mkfs.fat -F32 /dev/sda2
>> --8<---------------cut here---------------end--------------->8---
>>
>> First, this sounds like it’s up to the user to pick either EFI-based
>> GRUB or BIOS-based GRUB.  It is not clear that this is determined by
>> whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
>> really not much of a choice.
>>
>> Second, the “parted” command operates on the first partition (“1”), yet
>> for the second command the second partition (“/dev/sda2”) is used.  It’s
>> better to be consistent here, i.e. to change “set 1 esp on” to “set 2
>> esp on” and to state that this would modify “/dev/sda2”.
>>
>> Finally, it is not clear where the efi partition should be mounted.
>> Should it be /mnt/boot/efi?  If so, should the configuration file
>> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>>
>> An example would be useful here.
>>
>> I agree an example would be nice.
> I will have a look at this when I have time.
> I guess I had done something similar.
>
> I've just looked around and found that we have ovmf in our repository.
It would be nice if we could create a system test and use an ovmf qemu to
test installation.
Once we have that we could get the documentation consistent with a working
testcase.
WDYT?

>
>
>> --
>> Ricardo
>>
>>
>>
>>
>

[-- Attachment #2: Type: text/html, Size: 4974 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Joshua Branson]

[-- Attachment #1: Type: text/plain, Size: 2670 bytes --]

By no means am I a developer, but that sounds like a good idea.


On Thu, Feb 1, 2018, at 3:01 AM, Gábor Boskovits wrote:
> 2018-02-01 10:13 GMT+01:00 Gábor Boskovits <boskovits@gmail.com>:
>> 2018-01-31 20:01 GMT+01:00 Ricardo Wurmus <ricardo.wurmus@mdc-
>> berlin.de>:>>> The manual section “Preparing for Installation: Disk
>>> Partitioning” says>>>  this:
>>> 
>>>  --8<---------------cut here---------------start------------->8---
>>>     If your disk uses the GUID Partition Table (GPT) format and you
>>>     plan>>>  to install BIOS-based GRUB (which is the default), make sure a
>>>  BIOS Boot>>>  Partition is available (*note (grub)BIOS installation::).
>>> 
>>>     If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
>>>  Partition” (ESP) is required.  This partition should be mounted at>>>  ‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:>>> 
>>>       parted /dev/sda set 1 esp on
>>> 
>>>     Once you are done partitioning the target hard disk drive, you
>>>     have>>>  to create a file system on the relevant partition(s)(1).  For
>>>  the ESP,>>>  if you have one and assuming it is ‘/dev/sda2’, run:
>>> 
>>>       mkfs.fat -F32 /dev/sda2
>>>  --8<---------------cut here---------------end--------------->8---
>>> 
>>>  First, this sounds like it’s up to the user to pick either EFI-
>>>  based>>>  GRUB or BIOS-based GRUB.  It is not clear that this is
>>>  determined by>>>  whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s>>>  really not much of a choice.
>>> 
>>>  Second, the “parted” command operates on the first partition
>>>  (“1”), yet>>>  for the second command the second partition (“/dev/sda2”) is
>>>  used.  It’s>>>  better to be consistent here, i.e. to change “set 1 esp on” to
>>>  “set 2>>>  esp on” and to state that this would modify “/dev/sda2”.
>>> 
>>>  Finally, it is not clear where the efi partition should be mounted.>>>  Should it be /mnt/boot/efi?  If so, should the configuration file
>>>  specify “/mnt/boot/efi” as the target?  Or should it be
>>>  “/boot/efi”?>>> 
>>>  An example would be useful here.
>>> 
>> I agree an example would be nice.
>> I will have a look at this when I have time.
>> I guess I had done something similar.
>> 
> I've just looked around and found that we have ovmf in our repository.> It would be nice if we could create a system test and use an ovmf qemu
> to test installation.> Once we have that we could get the documentation consistent with a
> working testcase.> WDYT? 
>>  
>> 
>>> --
>>>  Ricardo
>>> 
>>> 
>> 


[-- Attachment #2: Type: text/html, Size: 6397 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Carlo Zancanaro]

[-- Attachment #1: Type: text/plain, Size: 1562 bytes --]

On Wed, Jan 31 2018, Ricardo Wurmus wrote:
> Finally, it is not clear where the efi partition should be 
> mounted.
> Should it be /mnt/boot/efi?  If so, should the configuration 
> file
> specify “/mnt/boot/efi” as the target?  Or should it be 
> “/boot/efi”?
>
> An example would be useful here.

We have an example in the manual at "(guix) Using the 
Configuration System" with the following sections:

  ;; Use the UEFI variant of GRUB with the EFI System
  ;; Partition mounted on /boot/efi.
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")))

  ;; Assume the target root file system is labelled "my-root",
  ;; and the EFI System Partition has UUID 1234-ABCD.
  (file-systems (cons* (file-system
                         (device "my-root")
                         (title 'label)
                         (mount-point "/")
                         (type "ext4"))
                       (file-system
                         (device (uuid "1234-ABCD" 'fat))
                         (title 'uuid)
                         (mount-point "/boot/efi")
                         (type "vfat"))
                       %base-file-systems))

I know that's a completely different section where you're talking 
about, but maybe it can be referenced/copied in the installation 
section. I think we should mount the efi partition at /boot/efi 
during installation, to match the way things will be when we boot 
into the installed system.

Carlo

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Ludovic Courtès]

Hello gentlefolks!

Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:

> First, this sounds like it’s up to the user to pick either EFI-based
> GRUB or BIOS-based GRUB.  It is not clear that this is determined by
> whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
> really not much of a choice.
>
> Second, the “parted” command operates on the first partition (“1”), yet
> for the second command the second partition (“/dev/sda2”) is used.  It’s
> better to be consistent here, i.e. to change “set 1 esp on” to “set 2
> esp on” and to state that this would modify “/dev/sda2”.
>
> Finally, it is not clear where the efi partition should be mounted.
> Should it be /mnt/boot/efi?  If so, should the configuration file
> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>
> An example would be useful here.

It’d be nice to fix this before the release.  Anyone could take a look
to address these issues?

Thanks,
Ludo’.

bug#30312: documentation: misleading EFI partitioning instructions

[Marius Bakke]

[-- Attachment #1.1: Type: text/plain, Size: 1408 bytes --]

ludo@gnu.org (Ludovic Courtès) writes:

> Hello gentlefolks!
>
> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
>
>> First, this sounds like it’s up to the user to pick either EFI-based
>> GRUB or BIOS-based GRUB.  It is not clear that this is determined by
>> whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
>> really not much of a choice.
>>
>> Second, the “parted” command operates on the first partition (“1”), yet
>> for the second command the second partition (“/dev/sda2”) is used.  It’s
>> better to be consistent here, i.e. to change “set 1 esp on” to “set 2
>> esp on” and to state that this would modify “/dev/sda2”.
>>
>> Finally, it is not clear where the efi partition should be mounted.
>> Should it be /mnt/boot/efi?  If so, should the configuration file
>> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>>
>> An example would be useful here.
>
> It’d be nice to fix this before the release.  Anyone could take a look
> to address these issues?

I've tried to address the latter issue in <https://bugs.gnu.org/31959>.

I tested it by installing in a virtual machine with the ESP mounted at
"/mnt/boot/efi", using a Guix snapshot that included that commit.  It
also works on my installed system with the ESP on /boot/efi.

Here is a patch addressing the second issue:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-Use-a-consistent-partitioning-scheme.patch --]
[-- Type: text/x-patch, Size: 2922 bytes --]

From 28b1aff2f0a78e7736c214880bbcfce1c0135346 Mon Sep 17 00:00:00 2001
From: Marius Bakke <mbakke@fastmail.com>
Date: Tue, 26 Jun 2018 11:59:51 +0200
Subject: [PATCH] doc: Use a consistent partitioning scheme.

* doc/guix.texi (Preparing for Installation): Consistently refer to the ESP as
/dev/sda1; root file system as /dev/sda2; and swap as /dev/sda3.
---
 doc/guix.texi | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index da05a200a..d3375601a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8641,21 +8641,21 @@ create a file system on the relevant partition(s)@footnote{Currently
 GuixSD only supports ext4 and btrfs file systems.  In particular, code
 that reads file system UUIDs and labels only works for these file system
 types.}.  For the ESP, if you have one and assuming it is
-@file{/dev/sda2}, run:
+@file{/dev/sda1}, run:
 
 @example
-mkfs.fat -F32 /dev/sda2
+mkfs.fat -F32 /dev/sda1
 @end example
 
 Preferably, assign file systems a label so that you can easily and
 reliably refer to them in @code{file-system} declarations (@pxref{File
 Systems}).  This is typically done using the @code{-L} option of
 @command{mkfs.ext4} and related commands.  So, assuming the target root
-partition lives at @file{/dev/sda1}, a file system with the label
+partition lives at @file{/dev/sda2}, a file system with the label
 @code{my-root} can be created with:
 
 @example
-mkfs.ext4 -L my-root /dev/sda1
+mkfs.ext4 -L my-root /dev/sda2
 @end example
 
 @cindex encrypted disk
@@ -8663,12 +8663,12 @@ If you are instead planning to encrypt the root partition, you can use
 the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
 @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
 @code{man cryptsetup}} for more information.)  Assuming you want to
-store the root partition on @file{/dev/sda1}, the command sequence would
+store the root partition on @file{/dev/sda2}, the command sequence would
 be along these lines:
 
 @example
-cryptsetup luksFormat /dev/sda1
-cryptsetup open --type luks /dev/sda1 my-partition
+cryptsetup luksFormat /dev/sda2
+cryptsetup open --type luks /dev/sda2 my-partition
 mkfs.ext4 -L my-root /dev/mapper/my-partition
 @end example
 
@@ -8688,11 +8688,11 @@ by @code{guix system init} afterwards.
 Finally, if you plan to use one or more swap partitions (@pxref{Memory
 Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
 sure to initialize them with @command{mkswap}.  Assuming you have one
-swap partition on @file{/dev/sda2}, you would run:
+swap partition on @file{/dev/sda3}, you would run:
 
 @example
-mkswap /dev/sda2
-swapon /dev/sda2
+mkswap /dev/sda3
+swapon /dev/sda3
 @end example
 
 Alternatively, you may use a swap file.  For example, assuming that in
-- 
2.18.0


[-- Attachment #1.3: Type: text/plain, Size: 275 bytes --]


I'm not sure how to best resolve the first issue.  I suppose we can
mention that if unsure which GRUB to use, the user can test whether
"/sys/firmware/efi" exists on the live image.

We could also make it clearer when booting whether the installer is in
"UEFI" mode or not.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Ludovic Courtès]

Hi Marius!

Marius Bakke <mbakke@fastmail.com> skribis:

>> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
>>
>>> Finally, it is not clear where the efi partition should be mounted.
>>> Should it be /mnt/boot/efi?  If so, should the configuration file
>>> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?

[...]

> I've tried to address the latter issue in <https://bugs.gnu.org/31959>.
>
> I tested it by installing in a virtual machine with the ESP mounted at
> "/mnt/boot/efi", using a Guix snapshot that included that commit.  It
> also works on my installed system with the ESP on /boot/efi.

So with #31959 applied, users can mount to /boot/efi or /mnt/boot/efi,
and both will work, right?

I think #31959 can be applied.

> From 28b1aff2f0a78e7736c214880bbcfce1c0135346 Mon Sep 17 00:00:00 2001
> From: Marius Bakke <mbakke@fastmail.com>
> Date: Tue, 26 Jun 2018 11:59:51 +0200
> Subject: [PATCH] doc: Use a consistent partitioning scheme.
>
> * doc/guix.texi (Preparing for Installation): Consistently refer to the ESP as
> /dev/sda1; root file system as /dev/sda2; and swap as /dev/sda3.

Go for it!

> I'm not sure how to best resolve the first issue.  I suppose we can
> mention that if unsure which GRUB to use, the user can test whether
> "/sys/firmware/efi" exists on the live image.
> 
> We could also make it clearer when booting whether the installer is in
> "UEFI" mode or not.

Maybe ‘guix system’ could warn, but I’m not sure how to do that in a
clean way.

Or at the very least we can document it.  Perhaps we need to add a “UEFI
vs. BIOS” section in the manual.

Ludo’.

bug#30312: documentation: misleading EFI partitioning instructions

[Marius Bakke]

[-- Attachment #1: Type: text/plain, Size: 2430 bytes --]

ludo@gnu.org (Ludovic Courtès) writes:

> Hi Marius!
>
> Marius Bakke <mbakke@fastmail.com> skribis:
>
>>> Ricardo Wurmus <ricardo.wurmus@mdc-berlin.de> skribis:
>>>
>>>> Finally, it is not clear where the efi partition should be mounted.
>>>> Should it be /mnt/boot/efi?  If so, should the configuration file
>>>> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>
> [...]
>
>> I've tried to address the latter issue in <https://bugs.gnu.org/31959>.
>>
>> I tested it by installing in a virtual machine with the ESP mounted at
>> "/mnt/boot/efi", using a Guix snapshot that included that commit.  It
>> also works on my installed system with the ESP on /boot/efi.
>
> So with #31959 applied, users can mount to /boot/efi or /mnt/boot/efi,
> and both will work, right?

Yes, both should work at "guix system init" time, even if they only
specify "/boot/efi" in the configuration file.

> I think #31959 can be applied.

Excellent, I'll push it shortly.

>> From 28b1aff2f0a78e7736c214880bbcfce1c0135346 Mon Sep 17 00:00:00 2001
>> From: Marius Bakke <mbakke@fastmail.com>
>> Date: Tue, 26 Jun 2018 11:59:51 +0200
>> Subject: [PATCH] doc: Use a consistent partitioning scheme.
>>
>> * doc/guix.texi (Preparing for Installation): Consistently refer to the ESP as
>> /dev/sda1; root file system as /dev/sda2; and swap as /dev/sda3.
>
> Go for it!

Staged for inclusion!

>> I'm not sure how to best resolve the first issue.  I suppose we can
>> mention that if unsure which GRUB to use, the user can test whether
>> "/sys/firmware/efi" exists on the live image.
>> 
>> We could also make it clearer when booting whether the installer is in
>> "UEFI" mode or not.
>
> Maybe ‘guix system’ could warn, but I’m not sure how to do that in a
> clean way.

I was thinking a visual hint when booting the live USB, e.g. in the
motd:

(if (file-exists? "/sys/firmware/efi")
     "Welcome to the GuixSD installation image (UEFI mode)!".
     "Welcome to the GuixSD installation image!")

I think Debian does something like this in the boot menu (IIRC).

> Or at the very least we can document it.  Perhaps we need to add a “UEFI
> vs. BIOS” section in the manual.

Yes, documentation needs more tweaks.  As Ricardo mentioned, using EFI
is not really optional once you've booted with it.  Leaving this bug
open still, suggestions welcome!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#30312: documentation: misleading EFI partitioning instructions

[Ludovic Courtès]

Marius Bakke <mbakke@fastmail.com> skribis:

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

[...]

>>> I'm not sure how to best resolve the first issue.  I suppose we can
>>> mention that if unsure which GRUB to use, the user can test whether
>>> "/sys/firmware/efi" exists on the live image.
>>> 
>>> We could also make it clearer when booting whether the installer is in
>>> "UEFI" mode or not.
>>
>> Maybe ‘guix system’ could warn, but I’m not sure how to do that in a
>> clean way.
>
> I was thinking a visual hint when booting the live USB, e.g. in the
> motd:
>
> (if (file-exists? "/sys/firmware/efi")
>      "Welcome to the GuixSD installation image (UEFI mode)!".
>      "Welcome to the GuixSD installation image!")
>
> I think Debian does something like this in the boot menu (IIRC).

The body is just plain static text, so I’m not sure how we could do
this.  We’d need a bit of code to do that in /etc/profile or something.
Ideas?

Thanks,
Ludo’.

bug#30312: documentation: misleading EFI partitioning instructions

[Ludovic Courtès]

Hi!

I ended up simply improving the manual in commit
fc0e663f782896f542d008c871d21b9cf636a75c.

Maybe we can do better next time, like have ‘guix system init’ provide
hints or something.

Thanks,
Ludo’.