Add documentation for PXE bootloader binary location

[spesnova717]

URL of the document

https://docs.theforeman.org/3.16/Provisioning_Hosts/index-foreman-el.html#using-network-boot-to-provision-hosts

---

Describe the issue

Currently, the Provisioning Hosts guide assumes that users install Foreman and Smart Proxy using foreman-installer, which automatically deploys PXE bootloader files under /var/lib/tftpboot/.
However, it is not obvious which PXE bootloader binaries (for example, grubaa64.efi) should be placed under which directories, or how the bootloader-universe layout should be structured.

As a result:

• Users who install Foreman and Smart Proxy manually often find it unclear where PXE bootloader binaries should be placed.
• Provisioning on architectures other than x86_64 can be more challenging. For example, on ARM (AArch64), GRUB2 UEFI PXE boot binaries (grubaa64.efi) must be manually extracted and placed under the appropriate bootloader-universe directory.

---

Anything else to add? (context, suggestions for a fix, etc.)

Suggestion:
Add a new section under Using network boot to provision hosts between:

8.2. Prerequisites for network-boot provisioning
→ 8.3. PXE bootloader binary location (new)
8.4. Required boot order for network boot

Proposed section title:

8.3. PXE bootloader binary location

---

Additionally, I’d like to explicitly state in 8.2. Prerequisites for network-boot provisioning that the required PXE bootloader binaries must be placed under /var/lib/tftpboot/ or bootloader-universe/ before starting network-boot provisioning.

This section (8.3. PXE bootloader binary location) should include:

• Explanation of the structure, purpose, and working of /var/lib/tftpboot/ and bootloader-universe/.
  This should describe:

  • How the directory hierarchy under bootloader-universe/ is organized by distribution, version, and architecture.
  • How these directories correspond to the settings in the Foreman Web UI under Operating Systems, Architecture.
  • Describe how placing a file under bootloader-universe/ automatically creates a symbolic link for the host under /var/lib/tftpboot/boot/ or /var/lib/tftpboot/host-config/ at build time.

• Description of binary placement & location of each bootloader, including where to obtain and where to place the binaries:

  • GRUB2 UEFI bootloaders
    • Place GRUB2 EFI binaries under
      /var/lib/tftpboot/bootloader-universe/pxegrub2/<distro>/<version>/<arch>/.
    • Typical source packages:
      • x86_64: grubx64.efi (from grub2-efi-x64)
      • AArch64: grubaa64.efi (from grub2-efi-aa64)
  • PXELinux bootloaders
    • Describe the process for obtaining PXELinux boot binaries and placing.
  • iPXE bootloaders
    • Describe the process for obtaining iPXE boot binaries and placing.

• Operational notes:

  • Obtain the necessary bootloader binaries from the relevant OS or package sources.
  • Copy them into the appropriate location under /var/lib/tftpboot/bootloader-universe/.
  • Set correct ownership and permissions.
  • Verify that symbolic links are automatically created under /var/lib/tftpboot/host-config/ when a host is built.

---

Expected benefits:

• Unifies instructions for GRUB2, PXELinux, and iPXE file placement.
  • Helps users who build Foreman and Smart Proxy without foreman-installer understand how to manually manage PXE bootloader files.
  • Documents the correct process for placing AArch64 (ARM) PXE boot binaries (grubaa64.efi).

I’d be grateful if the documentation maintainers could confirm whether this proposal fits the current documentation structure.
Any feedback or suggestions for improvement are very welcome.
Thank you.

[Lennonka]

I'm not sure if we should support installation without foreman-installer in documentation (currently we don't). Why would someone choose this way?

@ekohl Mind taking a look at this?

[ekohl]

However, it is not obvious which PXE bootloader binaries (for example, grubaa64.efi) should be placed under which directories.

We don't have non-arch-native grub packages (so no aarch64 if you're on x86_64 or vice versa). and worse, they need to match the target OS for SecureBoot to work.

Or how the bootloader-universe layout should be structured.

This is indeed what we should be using going forward. I've always been of the opinion that our current solution isn't very user friendly, which I'm guess is what you're now also finding.

Rather than describing it for every OS in a row I think we should provide scripts instead.

I'll admit I'm a bit fuzzy on the details but https://community.theforeman.org/t/add-secureboot-support-for-arbitrary-distributions/32601 was the initial discussion.

However, I think https://community.theforeman.org/t/rfc-distribution-of-netboot-files-via-oci-registry/36791 also has potential for the future as a mechanism to transfer these files. Fedora actually now publishes those as containers (https://quay.io/repository/fedora/kickstart-artifacts?tab=tags) and I think the intention was to push other distros to do the same.

[spesnova717]

Thanks for the comment, @Lennonka — I really appreciate your feedback.
I’ll continue the discussion with @ekohl to align on the best direction.

Thanks for the comment, @ekohl.

Just to confirm — when you mentioned “providing scripts,” did you mean actual shell scripts, or rather a generic and structured description that explains the logic in a reusable way?

I interpreted it as the latter — a more generic documentation approach rather than OS-specific instructions.

Specifically, what we’d like to document is:

• A generic explanation of how Foreman maps the values defined in the Web UI (Operating System, Version, Architecture, etc.) to the directory structure under bootloader_universe/ (for example, <distro>/<version>/<arch>/).
  • We want to describe this generically, without listing steps per OS (unlike the Secure Boot section).
• To consolidate this explanation in a single section (the new section to be added), covering
  • the binary placement and location of each bootloader type (GRUB2, PXELinux, iPXE).

We also created a figure — “Figure: Mapping between Foreman Web UI settings and bootloader_universe.” — to illustrate this relationship.
This figure and explanation aim to help users understand how Foreman determines which bootloader path is used, without going into OS-specific details or installation scripts.

In short, our intention is to document this generic mapping so that the structure and logic of bootloader_universe are clear to all users, regardless of architecture.

Thank you.

[maximiliankolb]

Ping @jloeser Just FYI for now; maybe later on you could provide some insights/reviews on this.

[stejskalleos]

Adding to my sprint backlog

[ekohl]

Just to confirm — when you mentioned “providing scripts,” did you mean actual shell scripts, or rather a generic and structured description that explains the logic in a reusable way?

I think it's not a question of either or. IMHO we need to have the structure, layout and design documented. I consider that something for developers and advanced users. For the average user I'd prefer a more automated way. For example, using shell scripts. That documentation can be extremely helpful in building that automated way.

So certainly 👍 for your effort here. I'd raise some questions about where we document it. If we zoom out, I'm not entirely happy with https://docs.theforeman.org/ when you look at how the various guides are built up. I'm a big fan of https://dunnhq.com/posts/2023/documentation-quadrants/ and most of our guides are more in the how-to guides category. This would fall squarely into the reference quadrant and we don't really have that now. I wish we had.

Btw, I'm sure you already found the PRs that added the functionality. #2145 points to theforeman/smart-proxy#877 and theforeman/foreman#9864. However, those are long discussions and perhaps harder to digest that you'd like.

[spesnova717]

Thanks, @ekohl

Including the link to the Documentation Quadrants was very helpful — it made your explanation much clearer.
I fully understand your point that we should avoid mixing reference-style content into how-to guides like “Using PXE to provision hosts.”

This topic clearly belongs to the Reference quadrant.
It focuses on describing structure and relationships
(for example, how bootloader_universe/ maps to tftp/host-config/), rather than guiding users through steps.

I noticed that the Foreman documentation already includes a Reference section:
https://docs.theforeman.org/release/3.16/

If that section is intended to collect reference material,
perhaps it would make sense to place this PXE bootloader topic there instead.
That way, we could keep the procedural (how-to) and structural (reference) documentation clearly separated.

Would that placement align with your view of what belongs in the Reference section?

[spesnova717]

@ekohl , @Lennonka

I have opened a related Pull Request: #4422 – Add section "Boot loader management and file structure".

This PR implements the proposal discussed in this issue and introduces the new section “8.3. Boot loader management and file structure” in the Provisioning Hosts guide.

This topic is reference-oriented, but I believe that PXE-related explanations are currently centralized within the Provisioning Hosts guide,
so I decided to add it there first, as it is likely the most accessible place for users looking for PXE-related information.

If maintainers later decide that this content fits better under a different section,
I’m happy to adjust its placement accordingly.

Any feedback on content or placement would be very welcome.