Add section "Boot loader management and file structure"

[spesnova717]

What changes are you introducing?

This PR adds a new section “8.3. Bootloader Binary Location” to the Provisioning Hosts guide:
https://docs.theforeman.org/3.16/Provisioning_Hosts/index-foreman-el.html#using-network-boot-to-provision-hosts

This section explains how PXE bootloader binaries are managed and where they should be placed when setting up network-based provisioning environments.

The section includes:

• Overview of the /var/lib/tftpboot/ and bootloader-universe/ directory structures
• Description of how directories are organized by distribution, version, and architecture
• Instructions for obtaining and placing PXE bootloader binaries (GRUB2, PXELinux, and iPXE)
• Explanation of how Foreman automatically generates symbolic links for each host under /var/lib/tftpboot/boot/ or /var/lib/tftpboot/host-config/

---

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

When users install Foreman and Smart Proxy using foreman-installer, PXE bootloader binaries are automatically deployed under /var/lib/tftpboot/.
However, users who handle non-x86 architectures (for example, Arm or PowerPC), or who install these components manually, often find the following points unclear:

• Which bootloader binaries should be placed under which directories
• How the bootloader-universe/ structure should be organized
• How these files correspond to the architectures and operating systems defined in the Foreman Web UI

This update clarifies these points and provides concrete examples of directory layout and file placement.
It helps users correctly prepare and manage PXE bootloader binaries across different architectures and provisioning setups.

---

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

It improves clarity and usability for users who manually configure PXE, iPXE, or HTTPBoot provisioning environments, including non-x86 systems.

---

Contributor checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.16 / Katello 4.18 (Satellite 6.18)
• Foreman 3.15 / Katello 4.17
• Foreman 3.14 / Katello 4.16 (Satellite 6.17; orcharhino 7.4)
• Foreman 3.13 / Katello 4.15 (EL9 only)
• Foreman 3.12 / Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• Foreman 3.11 / Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
• Foreman 3.10 / Katello 4.12
• Foreman 3.9 / Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• We do not accept PRs for Foreman older than 3.9.

Any feedback or suggestions for improvement are very welcome.
Thank you.

[github-actions]

The PR preview for 162b582 is available at theforeman-foreman-documentation-preview-pr-4422.surge.sh

The following output files are affected by this PR:

• Provisioning_Hosts/index-foreman-deb.html
• Provisioning_Hosts/index-foreman-el.html
• Provisioning_Hosts/index-katello.html
• Provisioning_Hosts/index-orcharhino.html
• Provisioning_Hosts/index-satellite.html

show diff

show diff as HTML

[ekohl]

@jloeser I've seen you recently investigate and write down some great research into how things work (like https://community.theforeman.org/t/grub2-network-boot-tftp-http-https-for-legacy-bios-uefi/44755). I'd appreciate if you could take a look at the content.

To the writers: would this be better suited for an appendix, or is it too long for that?

[Lennonka]

Thank you, Yusuke, for your contribution!
This will take a decent amount of fine tuning, so brace yourself.
Let's start with moving the new assembly into an appendix and I'll get back to you with a more detailed review later.

@ekohl Should this replace the PXE loader reference?

[Lennonka]

Yes, I think it will be better as an appendix in doc-Provisioning_Hosts/master.adoc. It's no big deal that it's long.

[spesnova717]

Thank you, @Lennonka and @ekohl, for your feedback.

That makes sense — I’ll move the new assembly to an appendix section
under doc-Provisioning_Hosts/master.adoc as suggested.
Once that’s done, I’ll update the PR accordingly and ping you for the next review.

Thanks again for the guidance!

[spesnova717]

Hi @Lennonka,
I’ve updated the PR as discussed — the new assembly has been moved to the appendix section under
doc-Provisioning_Hosts/master.adoc.
Thanks again for your helpful feedback!
Please take another look when you have a moment.

[stejskalleos]

cc @jafiala