Recent related feature changes
https://fedoraproject.org/wiki/Changes/BootLoaderSpecByDefault
https://fedoraproject.org/wiki/Changes/UnifyGrubConfig

@quiet @javierm

I think there are few salvagable parts to the existing wiki.

These are the most important and common, but need to be reworked:

2.1 Updating GRUB 2 configuration on BIOS systems
2.2 Updating GRUB 2 configuration on UEFI systems
2.4 Setting default entry

The UEFI advise applies to F33 and older. And for F34 and newer, the command is the same. Instead of recommending 'grub2-mkconfig for configuration changes, we should recommend grubby because then the same commands apply no matter the firmware, and no matter the release version. And it can also set the default kernel.

To add and argument to a single entry:
grubby --args=tonk --update-kernel=/boot/vmlinuz-5.11.14-300.fc34.x86_64

To add multiple arguments to a single entry:
grubby --args="tonk1 tonk2" --update-kernel=/boot/vmlinuz-5.11.14-300.fc34.x86_64

To add an argument to all current and future entries:
grubby --args=tonk --update-kernel=ALL

To remove an argument from all current and future entires:
grubby --remove-args=tonk --update-kernel=ALL

To set the default kernel:
grubby --set-default=/boot/vmlinuz-5.12.0-198.fc35.x86_64

2.2.1, 2.2.2, 2.2.3, 2.2.4

It think these should be discarded.

2.3

I think this section is mostly OK but is better off being made general purpose with a title: "Updating and repairing grub main configuration file". A brief intro could say: the grub configuration file at /boot/grub2/grub.cfg is a static file, not normally modified. But in case of drive replacement, installation of other Linux distros, it might be necessary to repair/update the configuration file.

How to tell when kind of firmware I have? '[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS'

Deprecated command. Only applies to UEFI systems with Fedora 33 and older: grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

Everyone else: grub2-mkconfig -o /boot/grub2/grub.cfg

Reinstalling GRUB:

If the user is advised to download any Fedora netinstaller, and boot the Troubleshooting->Rescue a Fedora system option, it's easier to document, and less confusing for them. So I'd suggest pushing them in that direction. Any relatively recent one will do. Once the installation is discovered and assembed: chroot /mnt/sysimage

How to tell when kind of firmware I have? '[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS'

UEFI:

$ sudo dnf reinstall shim-* grub-efi-*

BIOS:
Find the device node "/boot" is located on:
# mount | grep "/boot "
/dev/sda4 on /boot type ext4 (rw,relatime,seclabel)

The device node is /dev/sda (omit the number, referring to the partition)

grub2-install /dev/sda

WARN: grub2-install should not be used on UEFI systems. The bootloaders are in the shim and grub-efi packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in /boot/efi (the EFI System partition).

2.5 2.6, 2.7, 2.8, 2.9

Discard

2.10 Enable Serial Console in Grub

This could be handy but maybe put it in an appendix ormiscillaneous section. Also it should be updated to use grubby, rather that stepping all over everything.

Virtual machines:

grubby --args="systemd.journald.forward_to_console=1 console=ttyS0,38400 console=tty1" --update-kernel=/boot/vmlinuz-5.11.16-300.fc34.x86_64
grubby --set-default=/boot/vmlinuz-5.11.16-300.fc34.x86_64

Baremetal:

See https://www.gnu.org/software/grub/manual/grub/html_node/Serial-terminal.html

@quiet @javierm

Another option for the Fedora 33 and older, vs Fedora 34 and newer conundrum? We could recommend:

grub2-mkconfig -o /etc/grub-efi.cfg
grub2-mkconfig -o /etc/grub.cfg

That is a symlink that points to /boot/efi/EFI/fedora/grub.cfg on Fedora 33 and older. And to /boot/grub2/grub.cfg on Fedora 34 and newer. There is also /etc/grub.cfg which has only ever pointed to /boot/grub2/grub.cfg.

Further, since they both exist, there's no harm to the system in recommending the user do both. There's some "harm" in that some users might confused if they're really supposed to run both, and thereby wonder if one of them is incorrect. shrug It could come with a page/foot note explaining that yeah you really only need to run one of them, if you're sure which one to run.

Another thing to add to the appendix of the new document is how to fix an accidentally stomped on /boot/efi/EFI/fedora/grub.cfg on Fedora 34+ with the proper stub file. This might be a temporary need, but if grubby or grub2-mkconfig learn how to do this for us, we'll just update the appendix.

The gist of how to create one:

• Create a plain text file containing the following lines.

# cat grub.cfg
search --no-floppy --fs-uuid --set=dev !FSUUID!
set prefix=($dev)/grub2

export $prefix
configfile $prefix/grub.cfg

• Use lsblk -f to find the UUID for the '/boot/' mount point. This UUID is computer specific.

• Use that UUID in place of !FSUUID! in the file created in step one. For example that line becomes:

search --no-floppy --fs-uuid --set=dev f4292b13-8faf-4154-b022-7002ae70f312

• Move or copy the file to /boot/efi/EFI/fedora/grub.cfg

NOTE 1: The above assumes default partitioning, where a separate ext4 file system is mounted at /boot. In case of other configurations, for example /boot is a directory on system root, or /boot is a Btrfs subvolume, you will need to insert /boot into line 2, for example:

set prefix=($dev)/boot/grub2

Reinstalling GRUB:

If the user is advised to download any Fedora netinstaller, and boot the Troubleshooting->Rescue a Fedora system option, it's easier to document, and less confusing for them. So I'd suggest pushing them in that direction. Any relatively recent one will do. Once the installation is discovered and assembed: chroot /mnt/sysimage

@chrismurphy, I am not sure I understood ^^^ that paragraph and what i should do there.

How to tell when kind of firmware I have? '[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS'

UEFI:

$ sudo dnf reinstall shim-* grub-efi-*

I believe this is how to reinstall GRUB on UEFI systems.

BIOS:
Find the device node "/boot" is located on:
# mount | grep "/boot "
/dev/sda4 on /boot type ext4 (rw,relatime,seclabel)

The device node is /dev/sda (omit the number, referring to the partition)

grub2-install /dev/sda

And this is how to reinstall GRUB on BIOS systems.

WARN: grub2-install should not be used on UEFI systems. The bootloaders are in the shim and grub-efi packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in /boot/efi (the EFI System partition).

@quiet

I am not sure I understood ^^^ that paragraph and what i should do there.

It's just a point of discussion, whether docs can make a recommendation about what media to boot for repairs. Repairs need to go in their own section and I would demote them compared to the routine tasks that grubby can do like add/remove arguments and change default kernel to boot. The netinstaller is easier to document because it has a rescue option in the boot menu, which causes Anaconda to assemble the system for the user. Otherwise the documentation needs to spell out each step to assemble the system, in order for chroot to work, so that it's possible to reinstall the bootloader and run any other related commands for a repair.

I'd say the first section for the new doc is Add/Remove Boot Parameters. And maybe the second section is Repairs or Reinstallation the bootloader. So all of what I wrote was about repair/reinstall. And these days I'd put grub2-mkconfig in the repair category. Previously it was common to modify /etc/default/grub to add some parameters and then run grub2-mkconfig, but that's not recommended since the switch to BLS snippets. We're better off recommending grubby for that purpose, it's release version and firmware agnostic. And less fragile because it leaves the grub.cfg's untouched.

A possible third section could just be "Appendix" which could contain any of the legacy information of value that's in the wiki. I'm not really sure it's worth the effort compared to the complexity though.

@chrismurphy

Another thing to add to the appendix of the new document is how to fix an accidentally stomped on /boot/efi/EFI/fedora/grub.cfg on Fedora 34+ with the proper stub file. This might be a temporary need, but if grubby or grub2-mkconfig learn how to do this for us, we'll just update the appendix.

is this applicable also to /boot/grub2/grub.cfg on Fedora 34+ for BIOS machines ?

After I completed your outlined procedure on a BIOS based machine (creating plain text file, UUID, ...) and rebooted, i got a system that didnt boot.

• Move or copy the file to /boot/efi/EFI/fedora/grub.cfg

On BIOS machines to /boot/grub2/grub.cfg ?

Maybe we could explain in what situations users should use this route. What is the difference between these ways of repairing grub.cfg:
1) Troubleshooting ---> Rescue a Fedora system;
2) reinstalling grub.cfg with grub2-install (and on UEFI with that different command);
3) and this way -- creating plaintext file.

I feel they all aim to achieve the same goal -- functional grub.cfg and bootable system. Probably from different angles? Are all the 3 methods equal, and user can freely choose which on to use? Or they have specific usecases attached to them.

is this applicable also to /boot/grub2/grub.cfg on Fedora 34+ for BIOS machines ?

No, but there is still a /boot/efi on BIOS systems. It's ignored.

After I completed your outlined procedure on a BIOS based machine (creating plain text file, UUID, ...) and rebooted, i got a system that didnt boot.

Uhhh... only if you also copy this stub file to /boot/grub2/grub.cfg which should not be done, it is only used on UEFI and only should go at /boot/efi/EFI/fedora/grub.cfg.

Maybe we could explain in what situations users should use this route. What is the difference between these ways of repairing grub.cfg:
1) Troubleshooting ---> Rescue a Fedora system;

This just finds and assembles a system. It doesn't repair grub.cfg. It is one possible first step in repairing grub.cfg.

2) reinstalling grub.cfg with grub2-install (and on UEFI with that different command);

grub2-install doesn't recreate or reinstall grub.cfg it only embeds the two stages of the bootloader: one at LBA 0, and one in either the MBR gap or the GPT BIOS Boot partition.

3) and this way -- creating plaintext file.

Different solution for a different problem, primarily /boot/efi/EFI/fedora/grub.cfg being deprecated yet found in stale documentation and search engine results.

I like explaining things to people but not in unmaintainable forms. I think the GRUB stuff is so esoteric, so conditional and overly complicated, that we shouldn't explain it. Explaining it will take a lot of resources, and then it has to be maintained or it goes stale again. So when in doubt, just say no and don't document it, in particular when the reason for the documentation in the first place is bad software design. And by that I mean grub-mkconfig does not write out its own configuration file(s) in the proper location as a function of its design. It demands the user discover esoteric knowledge to pass to the -o flag. That's just badly designed. The command stands for "make configuration" yet it doesn't do that. Oh but that's for documentation to paper over... yikes!

OK this is better:

If you have accidentally run 'grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg' on Fedora 34+, you can fix it by just doing:

sudo dnf reinstall grub2-common

That will move the grub.cfg to /boot/grub2 and also re-create the forwarding stub file on the EFI system partition.

"I think the GRUB stuff is so esoteric, so conditional and overly complicated, that we shouldn't explain it. Explaining it will take a lot of resources, and then it has to be maintained or it goes stale again. So when in doubt, just say no and don't document it,"

Is that really an option for GRUB ?

Is that really an option for GRUB ?

It's the only option because we just don't have the resources for an alternative.

The https://fedoraproject.org/wiki/GRUB_2 page is looking a lot better. The changes I still would like to see before migrating it to a quick doc:

• make the page Fedora 34+ centric, i.e. the exceptions should be for Fedora 33 and older
• replace the grub2-mkconfig paths with /etc/grub2.cfg and /etc/grub2-efi.cfg because doing both harms no one, and captures everyone regardless of BIOS or UEFI and release version.
• Obliterate the Appendix. Originally I thought that content was salvageable. On second read, I'm so confused that I wouldn't ask anyone to proofread it, test it, let alone trust it. Parts refer to Fedora 20 and even suggests its own unreliability.

I guess I'm really in a "less is more" camp, that's my bias. But also I'm thinking long term.

• rpm-ostree based installations don't behave like either UEFI or BIOS traditional Fedora installations; Fedora CoreOS intend to move to bootupd eventually, which will eventually include IoT, Silverblue.
• For a while, rpm-ostree folks have wanted to dump all the GRUB user space tools because they are quite honestly fraught with peril. I'm quickly getting on board with this because tons of bug reports and user threads are doing things we have no control over with documentation anyway.
• GRUB is such a complicated multitentacled beast that I don't think any documentation project can solve it.
• There are two camps of GRUB end users. The vast majority who never have to interact with GRUB at all. And handful of folks who have unusual use cases who do. And I do not think the latter should be supported at all in Fedora, I really don't. Custom is custom and you are on your own. Those folks should learn all about GRUB from upstream code and docs, and get support from upstream. Fedora users should get the simple, reliable, constrained, uncomplicated GRUB in Fedora by default - to such a degree they don't even need to know it's GRUB versus some other bootloader. I would like to prepare Fedora users for the possibility that we switch default bootloaders one day and for that process to be totally transparent for 80%.

@chrismurphy

i tried to follow your recommendations and i updated the wiki accordingly:

https://fedoraproject.org/wiki/GRUB_2

Please, let me know your thoughts on how to improve it further.

It's looking better.

In this section:
https://fedoraproject.org/wiki/GRUB_2?rd=Grub2#Discovering_computer_firmware

Consider combining the two commands into one:
[ -d /sys/firmware/efi ] && echo UEFI || echo BIOS
This outputs either UEFI or BIOS as the case may be.

About this phrase "To update the GRUB 2 configuration file on Fedora 33 and earlier use grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg." We can recommend grub2-mkconfig -o /etc/grub2-efi.cfg on Fedora 33 and older too, the symlink points to the correct path on each Fedora release. In fact, it's safe to suggests users run both commands, and then they don't have to correctly identify their firmware type for this step (it's needed for the reinstallation step though)
` grub2-mkconfig -o /etc/grub2-efi.cfg grub2-mkconfig -o /etc/grub2.cfg

https://fedoraproject.org/wiki/GRUB_2?rd=Grub2#Fixing_a_damaged_GRUB_2_configuration_file_using_a_plaintext_stub_file_on_UEFI-based_systems

Doing dnf reinstall grub2-common will recreate the forwarding stub file on the ESP. Maybe it's better to assume the worst case and give one set of instructions for BIOS users and another set for UEFI users, that basically does a heavy handed "reset": both reinstalls the bootloader and recreates the grub.cfg's? That way all they do is follow the steps, and no matter if their problem is simple or severe, they do the same thing to fix it?

https://fedoraproject.org/wiki/GRUB_2?rd=Grub2#Reinstalling_GRUB_2

This section might format better with separate BIOS and UEFI sections. Right now they're separated by bullet points, but the last bullet point is formatted as a 4th bullet instead of under the BIOS bullet (I think this is a MediaWiki formatting artifact, seems like the intent was to put it under the BIOS bullet).

@chrismurphy

Doing dnf reinstall grub2-common will recreate the forwarding stub file on the ESP. Maybe it's better to assume the worst case and give one set of instructions for BIOS users and another set for UEFI users, that basically does a heavy handed "reset": both reinstalls the bootloader and recreates the grub.cfg's? That way all they do is follow the steps, and no matter if their problem is simple or severe, they do the same thing to fix it?

Are you talking here about Reinstalling GRUB 2 https://fedoraproject.org/wiki/GRUB_2#Reinstalling_GRUB_2 section?

or Fixing a damaged GRUB 2 configuration file using a plaintext stub file on UEFI-based systems https://fedoraproject.org/wiki/GRUB_2#Fixing_a_damaged_GRUB_2_configuration_file_using_a_plaintext_stub_file_on_UEFI-based_systems. Im sorry, it wasnt clear to me.

Does dnf reinstall grub2-common command apply for both BIOS and UEFI? Do you suggest we use this command instead of steps mentioned in Fixing a damaged GRUB 2 configuration... section?

What set of instructions should we give to BIOS users?

What set of instructions to UEFI users?

https://fedoraproject.org/wiki/GRUB_2?rd=Grub2#Reinstalling_GRUB_2

This section might format better with separate BIOS and UEFI sections. Right now they're separated by bullet points, but the last bullet point is formatted as a 4th bullet instead of under the BIOS bullet (I think this is a MediaWiki formatting artifact, seems like the intent was to put it under the BIOS bullet).

done

maybe we could kindly ask @javierm for review of this updated GRUB2 wiki

https://fedoraproject.org/wiki/GRUB_2

https://bugzilla.redhat.com/show_bug.cgi?id=1958540#c12

This works on baremetal UEFI:

$ sudo rm /boot/efi/EFI/fedora/grub.cfg
$ sudo rm /boot/grub2/grub.cfg
$ sudo dnf reinstall grub2-common

I'll test soon in UEFI and BIOS VM, but I suspect it'll work properly there too; and also check it on Fedora 33.

It's Fedora 34 UEFI specific.

OK I took a stab at this. If it looks good, go ahead and close this ticket as fixed.

Hi @chrismurphy,

I checked the whole content and updated it where i saw fit. It looks good to me.

As a result, I am closing this ticket.

I am not able to close this ticket. Probably I have insufficient permissions. You can go ahead and close this yourself.

Thanks