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.