Cross-reference: * bug 229595 * bug 256024
> Affects Only Me … affects many people. Thanks.
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").
(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.
See also: bug 258987
A moderated how-to: Update of the bootcodes for a GPT scheme | The FreeBSD Forums <https://forums.freebsd.org/threads/80163/>
Also: bug 229191
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(+)
(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
(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.)
(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
^Triage: grahamperrin is not active on doc ATM.