Skip to content

Commit 21f4436

Browse files
Yusuke Hirotavanou
Yusuke Hirota
and
vanou
committed
docs: add section "Bootloader binary location"
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 architectures and operating systems defined in the Foreman Web UI This commit adds a new section (8.3) to the Provisioning Hosts guide that explains: 1. The structure and purpose of /var/lib/tftpboot/ and bootloader-universe/ 2. Where to place PXE bootloader binaries for GRUB2, PXELinux, and iPXE 3. How symbolic links are automatically created for each host at build time This addition helps users to correctly prepare and manage PXE bootloader files for both x86 and non-x86 environments. Co-Authored-By: Vanou Ishii <[email protected]>
1 parent 21c8e2c commit 21f4436

7 files changed

+649
-0
lines changed

‎guides/common/assembly_bootloader-binary-location.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
include::modules/con_bootloader-binary-location-overview.adoc[]
4+
5+
include::modules/ref_bootloader-types.adoc[leveloffset=+1]
6+
7+
include::modules/ref_pxelinux-bootloaders.adoc[leveloffset=+1]
8+
9+
include::modules/ref_grub2-uefi-bootloaders.adoc[leveloffset=+1]
10+
11+
include::modules/ref_ipxe-bootloaders.adoc[leveloffset=+1]

‎guides/common/assembly_using-network-boot-to-provision-hosts.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ include::modules/con_network-boot-provisioning-workflow.adoc[leveloffset=+1]
1010

1111
include::modules/con_prerequisites-for-network-boot-provisioning.adoc[leveloffset=+1]
1212

13+
include::assembly_bootloader-binary-location.adoc[leveloffset=+1]
14+
1315
include::modules/ref_required-boot-order-for-network-boot.adoc[leveloffset=+1]
1416

1517
:extract_deb_prefix: cd /tmp && ar x /tmp

‎guides/common/modules/con_bootloader-binary-location-overview.adoc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con_bootloader-binary-location-overview_{context}"]
4+
= Bootloader Binary Location
5+
6+
This section describes how {Project} manages and serves bootloader binaries through the *{SmartProxy}*, which provides the underlying network boot services used during automated host provisioning.
7+
While traditional *PXE (Preboot Execution Environment)* remains a core method, {Project} also supports *HTTPBoot*, *iPXE*, and *UEFI HTTP(S) Boot* mechanisms.
8+
9+
During a network-based installation, {SmartProxy} coordinates multiple services:
10+
11+
* DHCP: Assigns IP addresses and provides the bootloader filename and `next-server` information.
12+
13+
* TFTP: Delivers bootloaders such as PXELinux, GRUB, or iPXE binaries to clients.
14+
15+
* HTTP(S): Serves bootloaders and installation images via the {SmartProxy}’s HTTPBoot module.
16+
17+
When a host begins a network boot, it retrieves the appropriate bootloader (for example, `pxelinux.0`, `grubx64.efi`, or `ipxe.efi`) according to its firmware type and *PXE Loader* setting in {Project}.
18+
The bootloader then loads {Project}-generated configuration files that define which kernel and initrd to boot, initiating the OS installation process.
19+
20+
The *{SmartProxy}* manages the distribution of these bootloader binaries and configuration files.
21+
All bootloaders, 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.
22+
Each bootloader binary is organized within a directory structure based on its type, architecture, and operating system version.
23+
24+
[NOTE]
25+
====
26+
The TFTP root directory is configured in `/etc/foreman-proxy/settings.d/tftp.yml` under the `:tftproot` parameter.
27+
In this document, the default path `/var/lib/tftpboot` is used for explanation.
28+
If your environment uses a different path, please substitute it accordingly.
29+
30+
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.
31+
This also defaults to `/var/lib/tftpboot`.
32+
If you have customized this setting, read the descriptions in this section using your configured directory path instead.
33+
====
34+

‎guides/common/modules/ref_bootloader-types.adoc‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="ref_bootloader-types_{context}"]
4+
= Bootloader Types in {Project}
5+
6+
This section describes the PXE bootloaders supported by {Project} and explains how each type is used during network provisioning, depending on firmware type, protocol, and boot environment.
7+
8+
{Project} allows you to configure a **PXE Loader** for each host.
9+
The PXE Loader determines which bootloader binary the host retrieves during network boot and how it communicates with the {SmartProxy} (via TFTP or HTTP).
10+
Selection depends on whether the host uses **BIOS**, **UEFI**, **Secure Boot**, or **HTTP Boot**.
11+
12+
== PXE Loader Types and Boot Protocols in {Project}
13+
14+
The following table lists the PXE Loader options available in the {Project}.
15+
Each loader is associated with a specific boot protocol and firmware type.
16+
17+
. PXE Loader Types and Boot Protocols
18+
19+
[cols="1,1,1,1", options="header"]
20+
|===
21+
| PXE Loader (UI Label)
22+
| Category
23+
| Firmware
24+
| Protocol
25+
26+
| None
27+
| None
28+
| -
29+
| -
30+
31+
| PXELinux BIOS
32+
| PXELinux
33+
| BIOS
34+
| DHCP → TFTP
35+
36+
| PXELinux UEFI
37+
| PXELinux
38+
| UEFI
39+
| DHCP → TFTP
40+
41+
| Grub UEFI
42+
| PXEGrub (Legacy)
43+
| UEFI
44+
| DHCP → TFTP
45+
46+
| Grub2 BIOS
47+
| PXEGrub2 (TFTP)
48+
| BIOS
49+
| DHCP → TFTP
50+
51+
| Grub2 ELF
52+
| PXEGrub2 (TFTP)
53+
| BIOS
54+
| DHCP → TFTP
55+
56+
| Grub2 UEFI
57+
| PXEGrub2 (TFTP)
58+
| UEFI
59+
| DHCP → TFTP
60+
61+
| Grub2 UEFI SecureBoot
62+
| PXEGrub2 (TFTP)
63+
| UEFI
64+
| DHCP → TFTP
65+
66+
| Grub2 UEFI HTTP
67+
| Grub2 (HTTP)
68+
| UEFI
69+
| DHCP → HTTP
70+
71+
| Grub2 UEFI HTTPS
72+
| Grub2 (HTTPS)
73+
| UEFI
74+
| DHCP → HTTPS
75+
76+
| Grub2 UEFI HTTPS SecureBoot
77+
| Grub2 (HTTPS)
78+
| UEFI
79+
| DHCP → HTTPS
80+
81+
| iPXE Embedded
82+
| iPXE Direct (HTTP)
83+
| BIOS / UEFI
84+
| DHCP → HTTP
85+
86+
| iPXE UEFI HTTP
87+
| iPXE Direct (HTTP)
88+
| UEFI
89+
| DHCP → HTTP
90+
91+
| iPXE Chain BIOS
92+
| iPXE Chainload
93+
| BIOS
94+
| DHCP → TFTP → HTTP
95+
96+
| iPXE Chain UEFI
97+
| iPXE Chainload
98+
| UEFI
99+
| DHCP → TFTP → HTTP
100+
|===
101+
102+
This table lists the available PXE Loader categories and describes how each type delivers bootloaders and installation files during network provisioning.
103+
104+
. PXE Loader categories
105+
106+
[cols="30%,70%",options="header"]
107+
|===
108+
| Category | Description
109+
110+
| PXELinux
111+
| Syslinux-based loaders for BIOS and UEFI environments.
112+
113+
| PXEGrub (Legacy)
114+
| Early GRUB-based loader for UEFI systems.
115+
116+
| PXEGrub2 (TFTP)
117+
| GRUB2-based loader supporting both BIOS and UEFI environments (including Secure Boot via `shim`).
118+
119+
| Grub2 (HTTP/HTTPS)
120+
| GRUB2-based UEFI bootloader fetched over HTTP or HTTPS using the {SmartProxy}’s HTTPBoot service.
121+
122+
| iPXE Chainload
123+
| A two-stage boot process in which the client first downloads an iPXE binary (`undionly-ipxe.0` or `ipxe.efi`) via TFTP.
124+
Once loaded, iPXE retrieves {Project}’s iPXE script and installation files over HTTP, enabling flexible configuration and network boot via HTTP.
125+
126+
| iPXE Direct (HTTP)
127+
| Boots directly via embedded or firmware-level iPXE using only HTTP.
128+
129+
| None
130+
| {Project} does not specify a bootloader.
131+
|===
132+
133+
== Bootloader File Mapping and Architecture Naming
134+
135+
{Project} automatically determines the correct bootloader filename for each host based on its *architecture* and the *PXE Loader* selected in the host settings.
136+
This mechanism ensures that the correct bootloader binary (such as `grubx64.efi` or `grubaa64.efi`) is selected automatically,
137+
without requiring administrators to manage architecture-specific filenames.
138+
139+
.PXE Loader to Bootloader Mapping
140+
141+
[cols="1,1,1", options="header"]
142+
|===
143+
| PXE Loader (UI Label)
144+
| Bootloader File (Template Path)
145+
| Example (x86_64)
146+
147+
| None
148+
| -
149+
| -
150+
151+
| PXELinux BIOS
152+
| pxelinux.0
153+
| pxelinux.0
154+
155+
| PXELinux UEFI
156+
| pxelinux.efi
157+
| pxelinux.efi
158+
159+
| Grub2 BIOS
160+
| grub<__arch__>.0
161+
| grubx64.0
162+
163+
| Grub2 ELF
164+
| grub<__arch__>.elf
165+
| grubx64.elf
166+
167+
| Grub2 UEFI
168+
| grub<__arch__>.efi
169+
| grubx64.efi
170+
171+
| Grub2 UEFI SecureBoot
172+
| shim<__arch__>.efi
173+
| shimx64.efi
174+
175+
| Grub2 UEFI HTTP
176+
| grub<__arch__>.efi (via HTTP)
177+
| grubx64.efi
178+
179+
| Grub2 UEFI HTTPS
180+
| grub<__arch__>.efi (via HTTPS)
181+
| grubx64.efi
182+
183+
| Grub2 UEFI HTTPS SecureBoot
184+
| shim<__arch__>.efi (via HTTPS)
185+
| shimx64.efi
186+
187+
| iPXE Embedded
188+
| Rendered dynamically as {Project}_url('iPXE')
189+
| -
190+
191+
| iPXE UEFI HTTP
192+
| ipxe-<__arch__>.efi
193+
| ipxe-x64.efi
194+
195+
| iPXE Chain BIOS
196+
| undionly-ipxe.0
197+
| undionly-ipxe.0
198+
199+
| iPXE Chain UEFI
200+
| ipxe.efi
201+
| ipxe.efi
202+
|===
203+
204+
== Architecture-Based File Naming
205+
206+
{Project} automatically determines the correct bootloader filename for each host based on its architecture.
207+
For example, `x86_64` hosts use `grubx64.efi`, while `aarch64` hosts use `grubaa64.efi`.
208+
209+
.Bootloader Filenames by Architecture
210+
211+
[cols="1,1,1", options="header"]
212+
|===
213+
| Architecture (Web UI)
214+
| Example Filename
215+
| Internal Suffix (for reference)
216+
217+
| i386, i686, x86
218+
| grubia32.efi
219+
| ia32
220+
221+
| x86_64, amd64
222+
| grubx64.efi, shimx64.efi
223+
| x64
224+
225+
| aarch64, aa64
226+
| grubaa64.efi, shimaa64.efi
227+
| aa64
228+
229+
| ppc64, ppc64le
230+
| grubppc64.efi
231+
| ppc64, ppc64le
232+
233+
| Other architectures (for example, riscv64, loongarch64)
234+
| grubriscv64.efi
235+
| normalized name
236+
|===
237+
238+
For instance, a host with architecture `aarch64` and PXE Loader set to “Grub2 UEFI” will use:
239+
240+
----
241+
/var/lib/tftpboot/grub2/grubaa64.efi
242+
----
243+
244+
This mechanism allows {Project} to select the correct bootloader automatically,
245+
without requiring users to manage architecture-specific filenames manually.

0 commit comments

Comments
 (0)