Bug 255318

Comment 1 Graham Perrin 2021-05-21 07:54:20 UTC

Cross-reference: 

* bug 229595
* bug 256024

Comment 2 Graham Perrin 2021-05-21 07:55:39 UTC

> Affects Only Me

… affects many people. Thanks.

Comment 3 Michael Gmelin 2021-05-22 16:14:20 UTC

There are a couple of helpful man pages
- zfsboot
- gptzfsboot
- loader.efi
- loader
- boot

So maybe it would be best to add one general man page on the topic that then can link to the relevant man pages based on user needs? (e.g. "man bootcode").

Comment 4 Graham Perrin 2022-01-09 23:14:51 UTC

(In reply to Michael Gmelin from comment #3)

Last month's <https://lists.freebsd.org/archives/freebsd-doc/2021-December/001068.html> and the response suggest improvements to: 

intro(8)
<https://www.freebsd.org/cgi/man.cgi?query=intro&sektion=8&manpath=FreeBSD>

>  intro -- introduction to system maintenance procedures and commands


In particular, from the first and second e-mails: 

> - whichever ZFS command(s) control mounting at boot

> efibootmgr(8)

<https://www.freebsd.org/cgi/man.cgi?query=efibootmgr&sektion=8&manpath=FreeBSD>

A section mentioning the need to update the bootloader is definitely missing in Chapter 24 "Updating and Upgrading FreeBSD". There's currently no mention of it, but a system upgrade isn't complete without this step, and the upgraded system may encounter problems with an out of date bootloader (happened to me after upgrading from 12.2 to 13.0).

Uncc'ing myself to avoid duplicate emails.

Comment 7 Graham Perrin 2022-01-10 22:53:33 UTC

See also: bug 258987

Comment 8 Graham Perrin 2022-02-06 14:17:54 UTC

A moderated how-to: 

Update of the bootcodes for a GPT scheme | The FreeBSD Forums
<https://forums.freebsd.org/threads/80163/>

Comment 9 Graham Perrin 2022-04-01 08:34:38 UTC

Also: bug 229191

Comment 10 commit-hook 2022-04-03 12:39:13 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=7233fc956edc31002c2e8f38ce30dda6b972f24c

commit 7233fc956edc31002c2e8f38ce30dda6b972f24c
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2022-04-03 12:34:55 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2022-04-03 12:37:58 +0000

    handbook: Add a brief section about updating bootcode

    Currently, the section does not explain when or why bootcode has to be
    updated. It just references some related manual pages.

    PR:             255318

 documentation/content/en/books/handbook/cutting-edge/_index.adoc | 5 +++++
 1 file changed, 5 insertions(+)

Comment 11 Graham Perrin 2022-08-14 13:51:01 UTC

(In reply to commit-hook from comment #10)

Thanks. 

Can we add links to the following? 

uefi(8)
<https://www.freebsd.org/cgi/man.cgi?query=uefi&sektion=8&manpath=FreeBSD>

UEFI - FreeBSD Wiki
<https://wiki.freebsd.org/UEFI>

----

loader.efi(8) is somewhat vague, compared to uefi(8) (and neither page mentions the other; see also bug 265834). 

It will be good to exemplify at least:

    /EFI/BOOT/BOOTX64.EFI

– or (lowercase, maybe preferred): 

    /efi/boot/bootx64.efi

Comment 12 Graham Perrin 2022-08-14 14:01:57 UTC

(In reply to Graham Perrin from comment #11)

> … (lowercase, maybe preferred): …

Sorry, I forgot to add an example. 

From last year's <https://www.freebsd.org/releases/13.0R/relnotes/#boot> (consistent with what I was taught, long ago): 

> … ESP partitions should be mounted as MS-DOS filesystems as 
> /boot/efi, and /boot/loader.efi should be copied to 
> /boot/efi/efi/boot/bootx64.efi if the default setup is used. …


(Some users will find the ESP mounted by default.)

Comment 13 Graham Perrin 2022-08-16 00:36:29 UTC

(In reply to Graham Perrin from comment #11)

> … It will be good to exemplify at least:
> 
>     /EFI/BOOT/BOOTX64.EFI
> 
> – or (lowercase, maybe preferred): 
> 
>     /efi/boot/bootx64.efi


<http://markmail.org/message/il4pgfyc7hlkwffh> imp@ enlightens: 

>>> …
>>>
>>> … amd64 … (/boot/efi/efi/freebsd/loader.efi) …
>>
>> Side note: please, why the FreeBSD reserved area?
> 
> When you create a boot variable using efibootmgr, it's better to 
> specify something that's not the default binary. It's what Windows, 
> Linux, etc do when they are installed and it facilitates better 
> multiboot when the target OSes depend on the first stage efi boot 
> loader (like FreeBSD and Windows certainly do).
> 
> Warner

(In reply to Graham Perrin from comment #12)

> … (Some users will find the ESP mounted by default.)

Probably _not_ true. I might have misunderstood part of a commit message.

(In reply to Graham Perrin from comment #13)

Alternatives to the MarkMail URL: 

<https://www.mail-archive.com/freebsd-current@freebsd.org/msg186720.html>
<https://lists.freebsd.org/archives/freebsd-current/2022-August/002408.html>


(In reply to commit-hook from comment #10)

>>    …
>>    Currently, the section does not explain when or why bootcode has to be
>>    updated. It just references some related manual pages.
>>    …

That is, <https://docs.freebsd.org/en/books/handbook/book/#updating-bootcode>; and (from base 9ecf6e0f9f25) the example in loader.efi(8) is good: <https://man.freebsd.org/cgi/man.cgi?query=loader.efi&sektion=8&manpath=freebsd-release#EXAMPLES> (thanks again, 0mp).

----

^Triage: with stable/12 end of life and 14.0-RELEASE both approaching, I reckon: 

a) <https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/cutting-edge/_index.adoc#23-performing-minor-and-major-version-upgrades>  should gain a warning, for readers to know that attention to an ESP might be essential

* two warning boxes plus a note box might be overwhelming, as a trio, so this
  ESP-related warning must be concise

* refer to the 'Updating Bootcode' section of the chapter

b) <https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/cutting-edge/_index.adoc#3-updating-bootcode> should be expanded, at least

* paraphrase the instruction to _stop_ using gpart(8) for ESP partitions

* refer directly to the EXAMPLES section of loader.efi(8)

* hint that if multiple ESPs exist, attention to more than one may be 
  appropriate (mirrored disks, for example).

<https://www.freebsd.org/releases/13.0R/relnotes/#boot>
<https://www.freebsd.org/releases/13.2R/relnotes/#boot>

! There is no stop note for 13.2, and upgrades from 12.⋯ to 13.2-RELEASE
  are expected (not all departures from 12.⋯ will go to 14.⋯), so 
  let's document this ASAP.

Created attachment 245266 [details]
A screenshot of proposed changes

Re: comment 15

> …
> 
> a) … a warning, for readers to know that attention to an ESP might be essential
> 
> * two warning boxes plus a note box might be overwhelming, …

I opted for three note boxes, as shown in the window to the left. 

(What's now the second box was previously a warning.)


> b) … expanded, at least
> 
> * paraphrase the instruction to _stop_ using gpart(8) for ESP partitions
> 
> * refer directly to the EXAMPLES section of loader.efi(8)

Shown in the window to the right. 

First mentions of gpart(8) and loader.efi(8) are links to the manual pages. 

Second mentions – adjacent, and nearly adjacent – are intentionally not links.


> * hint that if multiple ESPs exist, attention to more than one may be 
>   appropriate (mirrored disks, for example).

I'll add this locally, then attach the .patch file in Bugzilla.

Created attachment 245268 [details]
An updated screenshot of proposed changes

For the first note box in the window to the left: 

* instead of a two-sentence paragraph, two paragraphs. 

(The earlier edition avoided separate paragraphs only because spacing is slightly peculiar.)


In the window to the right: 

* the section heading is expanded to include ESPs

* a paragraph about mirroring and the like (for example, both disks should have 
  equally capable ESPs).

Created attachment 245269 [details]
signed-off .patch