Red Hat SummitAppendix E. Boot loader management and file structure
Satellite manages and serves boot loader binaries through the Capsule, which provides the network boot services used during automated host provisioning. Satellite supports PXE boot for BIOS and UEFI firmware on various architectures utilizing TFTP or HTTP(S).
During a network-based installation, Capsule coordinates the following services:
- DHCP
- Assigns IP addresses and provides the boot loader filename and server information.
- TFTP
Delivers boot loaders such as PXELinux, Grub2, or iPXE binaries to clients. TFTP also serves the following resources:
- Configuration files for boot loaders
-
Kernels and
initramdisk
- HTTP(S)
Serves boot loaders and installation files through the HTTPBoot module of your Capsule. HTTP(S) also serves the following resources:
- Configuration files for bootloaders
- Kernels & initramdisk
- Installation config files (Kickstart)
- Repository content
- Communication between Host <> Smart Proxy <> Foreman
When a host begins a network boot, it retrieves the appropriate boot loader (for example, pxelinux.0, grubx64.efi, or ipxe.efi) according to the PXE Loader option in Satellite. The boot loader then loads Satellite-generated configuration files that define which kernel and initrd to boot, initiating the operating system installation process.
The Capsule manages the distribution of these boot loader binaries and their configuration files. All boot loaders are stored on Capsule under the TFTP root directory (/var/lib/tftpboot/), which is also shared by the HTTPBoot service.
The Capsule also generates a directory for each provisioned host and names the directory with the host MAC address. In these directories, the Capsule creates symlinks to the boot files and configuration files, for example:
├── host-config
│ └── 00-aa-aa-99-99-04
│ └── grub2
│ ├── boot.efi -> ../../../grub2/grubx64.efi
│ ├── boot-sb.efi -> ../../../grub2/shimx64.efi
│ ├── grub.cfg-00:aa:aa:99:99:04 -> ../../../grub2/grub.cfg-00:aa:aa:99:99:04
│ ├── grub.cfg-01-00-aa-aa-99-99-04 -> ../../../grub2/grub.cfg-01-00-aa-aa-99-99-04
│ ├── grubx64.efi -> ../../../grub2/grubx64.efi
│ └── shimx64.efi -> ../../../grub2/shimx64.efi
This is useful for placing your own boot loader binaries in the bootloader_universe directory and use them instead of the default ones provided in /var/lib/tftpboot/boot. This is useful, for example, when you provision ARM hosts, for which Red Hat Satellite does not provide boot loaders.
By default, boot loader binaries are placed directly under service-specific directories such as grub2/, for example, /var/lib/tftpboot/grub2/grubx64.efi.
If the bootloader-universe structure is enabled, boot loaders are instead organized into a hierarchy based on type, architecture, and operating system version.
The TFTP root directory is configured in /etc/foreman-proxy/settings.d/tftp.yml under the :tftproot parameter. The default path is /var/lib/tftpboot/.
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. The default path is also /var/lib/tftpboot/.
This document uses the default paths. If your environment uses a different path, replace the default paths with your custom paths.
E.1. Boot loader types in Satellite
Satellite uses multiple types of PXE boot loaders during network provisioning, depending on firmware type, protocol, and boot environment.
In Satellite, you can 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 Capsule (via TFTP or HTTP). Select a PXE Loader based on whether the host uses BIOS, UEFI, Secure Boot, or HTTP Boot.
| PXE loader (UI label) | Category | Firmware | Protocol |
|---|---|---|---|
| None | None | - | - |
| PXELinux BIOS | PXELinux | BIOS |
DHCP |
| PXELinux UEFI | PXELinux | UEFI |
DHCP |
| Grub2 BIOS | PXEGrub2 (TFTP) | BIOS |
DHCP |
| Grub2 ELF | PXEGrub2 (TFTP) | BIOS |
DHCP |
| Grub2 UEFI | PXEGrub2 (TFTP) | UEFI |
DHCP |
| Grub2 UEFI SecureBoot | PXEGrub2 (TFTP) | UEFI |
DHCP |
| Grub2 UEFI HTTP | Grub2 (HTTP) | UEFI |
DHCP |
| Grub2 UEFI HTTPS | Grub2 (HTTPS) | UEFI |
DHCP |
| Grub2 UEFI HTTPS SecureBoot | Grub2 (HTTPS) | UEFI |
DHCP |
| iPXE Embedded | iPXE Direct (HTTP) | BIOS / UEFI |
DHCP |
| iPXE UEFI HTTP | iPXE Direct (HTTP) | UEFI |
DHCP |
| iPXE Chain BIOS | iPXE Chainload | BIOS |
DHCP |
| iPXE Chain UEFI | iPXE Chainload | UEFI |
DHCP |
Each type of PXE Loader categories delivers boot loaders and installation files during network provisioning. In Satellite, you can select from the following PXE Loader categories:
- PXELinux
- Syslinux-based loaders for BIOS and UEFI environments.
- 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 Capsule’s HTTPBoot service.
- iPXE Chainload
-
A two-stage boot process in which the client first downloads an iPXE binary (
undionly-ipxe.0oripxe.efi) via TFTP. When loaded, iPXE retrieves Satellite’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
- Satellite does not specify a boot loader.
Satellite 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 (UI label) | Boot loader file (template path) | Example (x86_64) |
|---|---|---|
| None | - | - |
| PXELinux BIOS |
|
|
| PXELinux UEFI |
|
|
| Grub2 BIOS |
|
|
| Grub2 ELF |
|
|
| Grub2 UEFI |
|
|
| Grub2 UEFI SecureBoot |
|
|
| Grub2 UEFI HTTP |
|
|
| Grub2 UEFI HTTPS |
|
|
| Grub2 UEFI HTTPS SecureBoot |
|
|
| iPXE Embedded |
Rendered dynamically as | - |
| iPXE UEFI HTTP |
|
|
| iPXE Chain BIOS |
|
|
| iPXE Chain UEFI |
|
|
Satellite 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.
| Architecture (Web UI) | Example Filename | Internal Suffix (for reference) |
|---|---|---|
| i386, i686, x86 |
|
|
| x86_64, amd64 |
|
|
| aarch64, aa64 |
|
|
| ppc64, ppc64le |
|
|
| Other architectures (for example, riscv64, loongarch64) |
| normalized name |
For example, a host with architecture aarch64 and PXE Loader set to Grub2 UEFI uses:
/var/lib/tftpboot/grub2/grubaa64.efiThis mechanism allows Satellite to select the correct boot loader automatically, without requiring users to manage architecture-specific filenames manually.
E.2. PXELinux boot loaders
PXELinux is a Syslinux-based PXE boot loader used by Satellite for BIOS and UEFI systems. In Satellite, PXELinux enables hosts to boot into the OS installer automatically during provisioning. When a host is set to Build mode, Satellite generates a host-specific configuration file and places it in the TFTP directory managed by the Capsule.
| Default path | Purpose | User action |
|---|---|---|
|
| The main PXELinux boot loader binary. Installed automatically by the satellite-installer. | Auto-installed by satellite-installer |
|
| Directory that contains configuration files generated by Satellite for each host (for example, 01-52-54-00-ab-cd-ef). | Auto-created during Build mode |
|
| Support module required by PXELinux for menu and filesystem operations. | Provide manually |
|
| Optional Syslinux modules for displaying boot menus or chainloading. | Provide manually |
Example E.1. PXELinux-related directory layout
# tree /var/lib/tftpboot/
/var/lib/tftpboot/
├── pxelinux.0
├── ldlinux.c32
├── menu.c32
├── chain.c32
└── pxelinux.cfg/
├── default
└── 01-52-54-00-ab-cd-ef
When a host is set to Build mode, Satellite automatically generates the configuration file under pxelinux.cfg/ based on the host’s OS, architecture, and installation template. The Capsule’s TFTP service then serves both the PXELinux binary and its configuration file to the client during network boot.
E.3. Grub2 UEFI boot loader and the bootloader-universe structure
PXEGrub2 GRUB-based PXE boot loader supports BIOS and UEFI environments, as well as Secure Boot environments. The bootloader-universe directory structure organizes Grub2 binaries by OS and architecture.
PXEGrub2 is managed by the Capsule’s TFTP service, which provides PXE clients with the appropriate boot loader binaries and configuration files.
By using the bootloader-universe directory structure, Grub2-based UEFI boot loaders can be organized and managed by distribution, version, and architecture. This feature does not require explicit configuration. It is automatically enabled when the Capsule uses the /var/lib/tftpboot/bootloader-universe/pxegrub2/ directory structure.
The bootloader-universe directory enables multiple operating system versions and architectures to coexist without conflicts.
When the Capsule recognizes the /var/lib/tftpboot/bootloader-universe/pxegrub2/ structure, boot loaders are stored in an organized hierarchy by OS, version, and architecture.
Before placing boot loader binaries (shimMy_Arch.efi, grubMy_Arch.efi), you must manually create the corresponding directory hierarchy by using the mkdir command, for example, # mkdir -p /var/lib/tftpboot/bootloader-universe/pxegrub2/My_Distribution/My_Version/My_Arch.
| Path | Purpose | User action |
|---|---|---|
|
|
Stores OS- and architecture-specific Grub2 binaries (shimMy_Arch.efi, grubMy_Arch.efi) and symbolic links (boot.efi, boot-sb.efi). Used for version-specific boot loader management within the | Create manually |
|
|
Stores OS- and architecture-specific Grub2 binaries ( | Create manually |
|
|
Host-specific directory automatically created when a host enters Build mode. Contains symbolic links ( | Auto-created by Capsule |
Example E.2. bootloader-universe directory layout
# tree /var/lib/tftpboot/bootloader-universe/
/var/lib/tftpboot/bootloader-universe/
├── pxegrub2/
│ ├── My_Distribution/My_Version/My_Arch/
│ │ ├── shimx64.efi
│ │ ├── grubx64.efi
│ │ ├── boot.efi -> grubx64.efi
│ │ └── boot-sb.efi -> shimx64.efi
│ └── ubuntu/22.04/My_Arch/
│ ├── shimx64.efi
│ ├── grubx64.efi
│ ├── boot.efi -> grubx64.efi
│ └── boot-sb.efi -> shimx64.efi
└── host-config/
└── 52-54-00-ab-cd-ef/
└── grub2/
├── boot.efi -> ../../../bootloader-universe/pxegrub2/My_Distribution/My_Version/My_Arch/boot.efi
├── boot-sb.efi -> ../../../bootloader-universe/pxegrub2/My_Distribution/My_Version/My_Arch/boot-sb.efi
├── grub.cfg
├── shimx64.efi -> ../../../bootloader-universe/pxegrub2/My_Distribution/My_Version/My_Arch/shimx64.efi
└── grubx64.efi -> ../../../bootloader-universe/pxegrub2/My_Distribution/My_Version/My_Arch/grubx64.efiIn this structure, the following principles apply:
-
boot.efiandboot-sb.efiare symbolic links togrubMy_Arch.efiandshimMy_Arch.efi, respectively. The Capsule automatically creates host-specific links to these files underhost-config/My_MAC_Address/grub2/. -
In the Satellite web UI, the
My_DistributionOS and distribution identifiers must not contain spaces. You must manually create
boot.efiandboot-sb.efisymbolic links within eachMy_Archdirectory, for example:$ ln -s grubx64.efi boot.efi $ ln -s shimx64.efi boot-sb.efi $ chmod 644 grubx64.efi shimx64.efiThe
chmodcommand ensures that TFTP and HTTPBoot clients can read these files.
In addition to the bootloader-universe layout, Satellite also supports the Legacy layout for backward compatibility.
If the /var/lib/tftpboot/bootloader-universe/pxegrub2/ structure is not used, Satellite falls back to the legacy /var/lib/tftpboot/grub2/ directory. Boot loaders are stored in a flat layout, but when a host enters Build mode, the Capsule creates a host-specific directory with the required configuration files and links.
| Path | Purpose | User action |
|---|---|---|
|
|
Default directory used when |
Place the appropriate boot loader binaries ( |
|
|
Host-specific directory automatically created when a host enters Build mode. Contains symbolic links ( | Auto-created by Capsule |
Example E.3. tftpboot/grub2/ structure
/var/lib/tftpboot/grub2/
├── grubx64.efi
└── shimx64.efiWhen a host enters Build mode, Capsule creates the following directory structure:
# tree /var/lib/tftpboot/
/var/lib/tftpboot/
└── host-config/
└── 52-54-00-ab-cd-ef/
└── grub2/
├── boot.efi -> ../../../grub2/grubx64.efi
├── boot-sb.efi -> ../../../grub2/shimx64.efi
├── grub.cfg
├── grub.cfg-01-52-54-00-ab-cd-ef
└── grub.cfg-52:54:00:ab:cd:efE.4. HTTP-capable boot loaders
In addition to the TFTP-based PXE mechanism, Satellite supports boot methods that use HTTP. These methods use the HTTPBoot module of Capsule to deliver boot loaders and installation files. HTTP-capable boot methods in Satellite are iPXE, iPXE chainloading, Grub2, and UEFI HTTP Boot. Each method offers advantages depending on the firmware type and network environment.
The HTTPBoot feature exposes the same files that are available via TFTP, but over the HTTP or HTTPS protocol. This can improve boot reliability in environments where TFTP is blocked, unreliable, or slow.
The boot methods in Satellite use the following boot workflows:
- iPXE chainloading (PXE to HTTP)
The boot process starts with a traditional PXE (TFTP) stage and then switches to HTTP for improved performance and flexibility. With this hybrid approach, existing PXE infrastructure can use HTTP for the later boot stages without requiring firmware-level HTTP support.
iPXE chainloading uses the following workflow:
The firmware downloads the appropriate iPXE loader via TFTP.
-
BIOS downloads
undionly-ipxe.0. -
UEFI downloads
ipxe.efi.
-
BIOS downloads
-
iPXE initializes the network and switches to HTTP, requesting an iPXE script such as
menu.ipxe.
- iPXE, Grub2, and UEFI HTTP(S) boot
UEFI firmware directly loads boot loaders by using HTTP or HTTPS without any TFTP step.
iPXE, Grub2, and UEFI HTTP(S) Boot use the following workflow:
-
UEFI firmware requests boot loader files from the Capsule via HTTP or HTTPS, for example,
ipxe-My_Architecture.efi. -
Grub2 loads
grub.cfgand starts the OS installer.
-
UEFI firmware requests boot loader files from the Capsule via HTTP or HTTPS, for example,
The Capsule’s HTTPBoot module and TFTP service share the same root directory. By default, this directory is /var/lib/tftpboot/.
URL path: http://capsule.example.com/httpboot/
Filesystem: /var/lib/tftpboot/
This mapping means that the /httpboot/ HTTP URL path directly corresponds to the local filesystem under /var/lib/tftpboot/. For example, a file located at /var/lib/tftpboot/pxegrub2/grubx64.efi is available over HTTP at http://capsule.example.com/httpboot/pxegrub2/grubx64.efi.
This shared structure simplifies management by ensuring that both PXE (TFTP) and HTTP clients use the same set of boot loader binaries and configuration files.
Example E.4. iPXE and HTTPBoot-related directory layout
# tree /var/lib/tftpboot/
/var/lib/tftpboot/
├── undionly-ipxe.0
├── ipxe.efi
├── ipxe-x64.efi
└── grub2/
├── grubx64.efi
└── shimx64.efi| Default path | Purpose | User action |
|---|---|---|
|
| iPXE boot loader for iPXE Chain BIOS. Used in BIOS environments as the first-stage loader that transitions from TFTP-based PXE to HTTP-based iPXE boot. |
Place the |
|
| iPXE boot loader for iPXE Chain UEFI. Used in UEFI environments to chainload into iPXE for HTTP-capable provisioning. |
Place the |
|
| Architecture-specific iPXE binary for iPXE UEFI HTTP boot. Used for direct iPXE boot via HTTP without TFTP chainloading. |
Place the architecture-matched file, for example, |
|
| Grub2 UEFI boot loader for Grub2, UEFI HTTP, or HTTPS Boot. Used to start UEFI installations via the Capsule’s HTTPBoot module. |
Place the corresponding architecture-specific file, for example, |
|
| Secure Boot shim loader for Grub2. Used when Grub2 UEFI SecureBoot, Grub2, or UEFI HTTPS SecureBoot is selected. |
Place the matching shim binary, for example, |
Grub2 and UEFI HTTPS Boot relies on the Capsule’s HTTPS service to securely deliver the boot.efi, shimx64.efi, and similar boot loader binaries to UEFI clients. The configuration for this HTTPS service is defined in the Capsule’s main settings file /etc/foreman-proxy/settings.yml.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}