theforeman · spesnova717 · Oct 24, 2025
diff --git a/guides/common/assembly_bootloader-binary-location.adoc b/guides/common/assembly_bootloader-binary-location.adoc
@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+
+include::modules/con_bootloader-binary-location-overview.adoc[]
+
+include::modules/ref_bootloader-types.adoc[leveloffset=+1]
+
+include::modules/ref_pxelinux-bootloaders.adoc[leveloffset=+1]
+
+include::modules/ref_grub2-uefi-bootloaders.adoc[leveloffset=+1]
+
+include::modules/ref_ipxe-bootloaders.adoc[leveloffset=+1]
diff --git a/guides/common/modules/con_bootloader-binary-location-overview.adoc b/guides/common/modules/con_bootloader-binary-location-overview.adoc
@@ -0,0 +1,34 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con_bootloader-binary-location-overview_{context}"]
+= Boot loader management and file structure
+
+This section describes how {Project} manages and serves boot loader binaries through the *{SmartProxy}*, which provides the underlying network boot services used during automated host provisioning.
+While traditional *PXE (Preboot Execution Environment)* remains a core method, {Project} also supports *HTTPBoot*, *iPXE*, and *UEFI HTTP(S) Boot* mechanisms.
+
+During a network-based installation, {SmartProxy} coordinates multiple services:
+
+* DHCP: Assigns IP addresses and provides the boot loader filename and `next-server` information.
+
+* TFTP: Delivers boot loaders such as PXELinux, GRUB, or iPXE binaries to clients.
+
+* HTTP(S): Serves boot loaders and installation images via the {SmartProxy}’s HTTPBoot module
+
+When a host begins a network boot, it retrieves the appropriate boot loader (for example, `pxelinux.0`, `grubx64.efi`, or `ipxe.efi`) according to its firmware type and *PXE Loader* setting in {Project}.
+The boot loader then loads {Project}-generated configuration files that define which kernel and initrd to boot, initiating the OS installation process.
+
+The *{SmartProxy}* manages the distribution of these boot loader binaries and configuration files.
+All boot loaders, whether used for PXE, iPXE, or HTTPBoot, are stored under the {SmartProxy}’s TFTP root directory (`/var/lib/tftpboot/`), which is also shared by the HTTPBoot service.
+Each boot loader binary is organized within a directory structure based on its type, architecture, and operating system version.
+
+[NOTE]
+====
+The TFTP root directory is configured in `/etc/foreman-proxy/settings.d/tftp.yml` under the `:tftproot` parameter.
+In this document, the default path `/var/lib/tftpboot` is used for explanation.
+If your environment uses a different path, please substitute it accordingly.
+
+The directory used by *Grub2 UEFI HTTP* and *iPXE HTTP* for file delivery is defined in `/etc/foreman-proxy/settings.d/httpboot.yml` under the `:root_dir` parameter.
+This also defaults to `/var/lib/tftpboot`.
+If you have customized this setting, read the descriptions in this section using your configured directory path instead.
+====
+
diff --git a/guides/common/modules/ref_bootloader-types.adoc b/guides/common/modules/ref_bootloader-types.adoc
@@ -0,0 +1,245 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ref_bootloader-types_{context}"]
+= Boot loader types in {Project}
+
+This section describes the PXE boot loaders supported by {Project} and explains how each type is used during network provisioning, depending on firmware type, protocol, and boot environment.
+
+{Project} allows you to configure a **PXE Loader** for each host.  
+The PXE Loader determines which boot loader binary the host retrieves during network boot and how it communicates with the {SmartProxy} (via TFTP or HTTP).
+Selection depends on whether the host uses **BIOS**, **UEFI**, **Secure Boot**, or **HTTP Boot**.
+
+== PXE Loader Types and Boot Protocols in {Project}
+
+The following table lists the PXE Loader options available in the {Project}.
+Each loader is associated with a specific boot protocol and firmware type.
+
+. PXE Loader Types and Boot Protocols
+
+[cols="1,1,1,1", options="header"]
+|===
+| PXE Loader (UI Label)
+| Category
+| Firmware
+| Protocol
+
+| None
+| None
+| -
+| -
+
+| PXELinux BIOS
+| PXELinux
+| BIOS
+| DHCP → TFTP
+
+| PXELinux UEFI
+| PXELinux
+| UEFI
+| DHCP → TFTP
+
+| Grub UEFI
+| PXEGrub (Legacy)
+| UEFI
+| DHCP → TFTP
+
+| Grub2 BIOS
+| PXEGrub2 (TFTP)
+| BIOS
+| DHCP → TFTP
+
+| Grub2 ELF
+| PXEGrub2 (TFTP)
+| BIOS
+| DHCP → TFTP
+
+| Grub2 UEFI
+| PXEGrub2 (TFTP)
+| UEFI
+| DHCP → TFTP
+
+| Grub2 UEFI SecureBoot
+| PXEGrub2 (TFTP)
+| UEFI
+| DHCP → TFTP
+
+| Grub2 UEFI HTTP
+| Grub2 (HTTP)
+| UEFI
+| DHCP → HTTP
+
+| Grub2 UEFI HTTPS
+| Grub2 (HTTPS)
+| UEFI
+| DHCP → HTTPS
+
+| Grub2 UEFI HTTPS SecureBoot
+| Grub2 (HTTPS)
+| UEFI
+| DHCP → HTTPS
+
+| iPXE Embedded
+| iPXE Direct (HTTP)
+| BIOS / UEFI
+| DHCP → HTTP
+
+| iPXE UEFI HTTP
+| iPXE Direct (HTTP)
+| UEFI
+| DHCP → HTTP
+
+| iPXE Chain BIOS
+| iPXE Chainload
+| BIOS
+| DHCP → TFTP → HTTP
+
+| iPXE Chain UEFI
+| iPXE Chainload
+| UEFI
+| DHCP → TFTP → HTTP
+|===
+
+This table lists the available PXE Loader categories and describes how each type delivers boot loaders and installation files during network provisioning.
+
+. PXE Loader categories
+
+[cols="30%,70%",options="header"]
+|===
+| Category | Description
+
+| PXELinux
+| Syslinux-based loaders for BIOS and UEFI environments.
+
+| PXEGrub (Legacy)
+| Early GRUB-based loader for UEFI systems.
+
+| PXEGrub2 (TFTP)
+| GRUB2-based loader supporting both BIOS and UEFI environments (including Secure Boot via `shim`).
+
+| Grub2 (HTTP/HTTPS)
+| GRUB2-based UEFI boot loader fetched over HTTP or HTTPS using the {SmartProxy}’s HTTPBoot service. 
+
+| iPXE Chainload
+| A two-stage boot process in which the client first downloads an iPXE binary (`undionly-ipxe.0` or `ipxe.efi`) via TFTP.
+Once loaded, iPXE retrieves {Project}’s iPXE script and installation files over HTTP, enabling flexible configuration and network boot via HTTP.
+
+| iPXE Direct (HTTP)
+| Boots directly via embedded or firmware-level iPXE using only HTTP.
+
+| None
+| {Project} does not specify a boot loader.
+|===
+
+== Boot Loader File Mapping and Architecture Naming
+
+{Project} automatically determines the correct boot loader filename for each host based on its *architecture* and the *PXE Loader* selected in the host settings.
+This mechanism ensures that the correct boot loader binary (such as `grubx64.efi` or `grubaa64.efi`) is selected automatically,
+without requiring administrators to manage architecture-specific filenames.
+
+.PXE Loader to Boot Loader Mapping
+
+[cols="1,1,1", options="header"]
+|===
+| PXE Loader (UI Label)
+| Boot Loader File (Template Path)
+| Example (x86_64)
+
+| None
+| -
+| -
+
+| PXELinux BIOS
+| pxelinux.0
+| pxelinux.0
+
+| PXELinux UEFI
+| pxelinux.efi
+| pxelinux.efi
+
+| Grub2 BIOS
+| grub<__arch__>.0
+| grubx64.0
+
+| Grub2 ELF
+| grub<__arch__>.elf
+| grubx64.elf
+
+| Grub2 UEFI
+| grub<__arch__>.efi
+| grubx64.efi
+
+| Grub2 UEFI SecureBoot
+| shim<__arch__>.efi
+| shimx64.efi
+
+| Grub2 UEFI HTTP
+| grub<__arch__>.efi (via HTTP)
+| grubx64.efi
+
+| Grub2 UEFI HTTPS
+| grub<__arch__>.efi (via HTTPS)
+| grubx64.efi
+
+| Grub2 UEFI HTTPS SecureBoot
+| shim<__arch__>.efi (via HTTPS)
+| shimx64.efi
+
+| iPXE Embedded
+| Rendered dynamically as {Project}_url('iPXE')
+| -
+
+| iPXE UEFI HTTP
+| ipxe-<__arch__>.efi
+| ipxe-x64.efi
+
+| iPXE Chain BIOS
+| undionly-ipxe.0
+| undionly-ipxe.0
+
+| iPXE Chain UEFI
+| ipxe.efi
+| ipxe.efi
+|===
+
+== Architecture-Based File Naming
+
+{Project} automatically determines the correct boot loader filename for each host based on its architecture.
+For example, `x86_64` hosts use `grubx64.efi`, while `aarch64` hosts use `grubaa64.efi`.
+
+.Boot Loader Filenames by Architecture
+
+[cols="1,1,1", options="header"]
+|===
+| Architecture (Web UI)
+| Example Filename
+| Internal Suffix (for reference)
+
+| i386, i686, x86
+| grubia32.efi
+| ia32
+
+| x86_64, amd64
+| grubx64.efi, shimx64.efi
+| x64
+
+| aarch64, aa64
+| grubaa64.efi, shimaa64.efi
+| aa64
+
+| ppc64, ppc64le
+| grubppc64.efi
+| ppc64, ppc64le
+
+| Other architectures (for example, riscv64, loongarch64)
+| grubriscv64.efi
+| normalized name
+|===
+
+For instance, a host with architecture `aarch64` and PXE Loader set to “Grub2 UEFI” will use:
+
+----
+/var/lib/tftpboot/grub2/grubaa64.efi
+----
+
+This mechanism allows {Project} to select the correct boot loader automatically,
+without requiring users to manage architecture-specific filenames manually.