I just added a couple more small changes. This should be ready for review now.

I think more clear would be to link to "Create a GRUB2 configuration" because in this adding another operating system section, there are much more instructions.

. Regenerate the *GRUB2* configuration file, as described in xref:create-a-grub-2-configuration[Create a GRUB2 configuration].

md5 hurts my eyes, but if it works with grub2-mkpasswd-pbkdf2 I guess it is fine and shorter to use :)

Maybe users better create their own configuration file instead of modifying existing one. Or maybe remove that part of the page because this manual setup is much more complicated. Although it gives some clue about possibility to create more users and passwords, in which sense it is also good to stay..

Thank you, much clearer now!

The thing is, it's not an md5 password, and that option doesn't work with grub2-mkpasswd-pbkdf2:

$ grub2-mkpasswd-pbkdf2 --md5pass
grub2-mkpasswd-pbkdf2: unrecognized option '--md5pass'
Try 'grub2-mkpasswd-pbkdf2 --help' or 'grub2-mkpasswd-pbkdf2 --usage' for more
information.

I think those options are arguments to the bootloader Kickstart command, and --md5pass isn't documented as a valid option there, either, in our own Kickstart syntax reference. Those docs have an example bootloader command to set up Grub2 with a password, and they use --iscrypted --password=grub2_sha512_hash. Even if --md5pass is accepted as a legacy option, I don't think we should be documenting it here when none of the other docs acknowledge it as a valid option.

@mlewando, @akostadi @ferdnyc Sorry, I'm a bit lost by the comments. Is this now ready to be merged?

@pboy

The only remaining point of discussion is this change:

- Starting from Fedora 21, the `--md5pass` kickstart option must be used when using the `grub2-mkpasswd-pbkdf2` command.
+ Starting from Fedora 15, the `--md5pass` or the `--password=<encrypted_grub_passwd> --iscrypted` kickstart option must be used if setting an encrypted *GRUB2* password in the kickstart.

(Ugh, our highlight.js setup doesn't do diff highlighting?)

@akostadi was somewhat perturbed by the inclusion of --md5pass, but decided to live with it.

I feel it's a mistake to include, because it's not a valid option for grub2-mkpasswd-pbkdf2 (as the old text seemed to be implying), and if it's a valid option for the Kickstart bootstrap command (which is what accepts the alternative --iscrypted --password= arguments), then it [meaning --md5pass] is an undocumented, outdated option that IMHO we shouldn't be encouraging anyone to use anymore.

I also think that text could be clearer about what exactly it means that these "kickstart option must be used", since like I said AFAICT those are actually flags for Kickstart's bootstrap command, specifically.

But those are relatively minor concerns, and there is clearer information on those points in the Kickstart documentation itself. If the decision is made to merge it as-is, I have no strong objections.

The only place that I know of that --md5pass is documented is here: https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#bootloader and it does work, but I'm happy to remove that part if it's not in the other documentation and y'all prefer to discourage its use.

@mlewando

The only place that I know of that --md5pass is documented is here

Yeah, and even there it's documented as being simply an...

Alias for --password=MD5PASS --iscrypted.

So IMHO it makes sense to just document that one form, instead. I wouldn't be surprised if --md5pass ends up deprecated soon enough. It's been almost three decades since md5 was broken, and it's not accepted by any sort of security/cryptography code anymore, so that alias is just confusing.

@mlewando

I'm not sure quite what happened, but those last two commits you pushed to the branch are a bit off — the first one completely removes the entire grub2-bootloader.adoc file, and then the second one adds the whole thing back in.

It'd probably be helpful to squash them together, so that they're one small change instead of two huge ones.

@ferdnyc
Also not sure what happened... but it's done. sorry for the mess.

I'm not sure why my attempts to "heart" your last comment are being met with a message on the console that reads:

POST https://pagure.io/fedora-docs/quick-docs/pull-request/703 405 (Method Not Allowed)

...So I'll just say, "Thanks! LGTM."