From a3a503421af48053e23412267814565644d0c789 Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Fri, 28 Nov 2025 12:20:42 +0100 Subject: [PATCH 1/7] boot loaders file changes --- .../assembly_bootloader-binary-location.adoc | 4 +- .../common/modules/ref_http-bootloaders.adoc | 35 +++++ .../common/modules/ref_ipxe-bootloaders.adoc | 134 ------------------ .../modules/ref_shared-tftp-http-root.adoc | 78 ++++++++++ 4 files changed, 116 insertions(+), 135 deletions(-) create mode 100644 guides/common/modules/ref_http-bootloaders.adoc delete mode 100644 guides/common/modules/ref_ipxe-bootloaders.adoc create mode 100644 guides/common/modules/ref_shared-tftp-http-root.adoc diff --git a/guides/common/assembly_bootloader-binary-location.adoc b/guides/common/assembly_bootloader-binary-location.adoc index b909a27642a..625fc989578 100644 --- a/guides/common/assembly_bootloader-binary-location.adoc +++ b/guides/common/assembly_bootloader-binary-location.adoc @@ -8,4 +8,6 @@ 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] +include::modules/ref_http-bootloaders.adoc[leveloffset=+1] + +include::modules/ref_shared-tftp-http-root.adoc[leveloffset=+1] diff --git a/guides/common/modules/ref_http-bootloaders.adoc b/guides/common/modules/ref_http-bootloaders.adoc new file mode 100644 index 00000000000..41434ecd1b2 --- /dev/null +++ b/guides/common/modules/ref_http-bootloaders.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: REFERENCE + +[id="ref_http-bootloaders_{context}"] += HTTP-based boot loaders + +[role="_abstract"] +In addition to the *TFTP-based PXE* mechanism, {Project} supports boot methods that use *HTTP*. +HTTP-based boot methods use the {SmartProxy}’s *HTTPBoot* module to deliver bootloaders and installation files. +HTTP-based boot methods in {Project} are *iPXE*, *iPXE chainloading*, and *Grub2 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 {Project} 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`. +. iPXE initializes the network and switches to HTTP, requesting an iPXE script such as `menu.ipxe`. + +iPXE and Grub2 UEFI HTTP(S) boot:: + +UEFI firmware directly loads boot loaders by using HTTP or HTTPS without any TFTP step. ++ +iPXE and Grub2 UEFI HTTP(S) Boot use the following workflow: ++ +. UEFI firmware requests boot loader files from the {SmartProxy} via HTTP or HTTPS, for example, `ipxe-____.efi`. +. Grub2 loads `grub.cfg` and starts the OS installer. diff --git a/guides/common/modules/ref_ipxe-bootloaders.adoc b/guides/common/modules/ref_ipxe-bootloaders.adoc deleted file mode 100644 index e9104a2b39b..00000000000 --- a/guides/common/modules/ref_ipxe-bootloaders.adoc +++ /dev/null @@ -1,134 +0,0 @@ -:_mod-docs-content-type: REFERENCE - -[id="ref_ipxe-bootloaders_{context}"] -= iPXE / Grub2 UEFI HTTP(S) boot loaders - -This section describes HTTP-based boot methods such as *iPXE*, *iPXE chainloading* and *Grub2 UEFI HTTP(S) Boot*, which use the {SmartProxy}’s HTTPBoot module to deliver bootloaders and installation files. - -In addition to the *TFTP-based PXE* mechanism, {Project} supports boot methods that use *HTTP*. - -HTTP-based boot methods include: - -* *iPXE* -* *iPXE chainloading* -* *Grub2 UEFI HTTP Boot* - -All of these methods leverage the {SmartProxy}’s HTTPBoot module to deliver bootloaders and installation files. - -The *HTTPBoot* feature exposes the same files that are available via TFTP, but over the HTTP(S) protocol. -This can improve boot reliability in environments where TFTP is blocked, unreliable, or slow. - -== Boot Methods - -This section explains the two main boot workflows: *iPXE chainloading* and *iPXE*, *Grub2 UEFI HTTP(S) Boot*. -Each method offers advantages depending on the firmware type and network environment. - -=== iPXE Chainloading (PXE → HTTP) - -In this method, the boot process starts with a traditional PXE (TFTP) stage and then switches to HTTP for improved performance and flexibility. - -*Workflow:* - -1. The firmware downloads the appropriate iPXE loader via TFTP. - * BIOS downloads `undionly-ipxe.0`. - * UEFI downloads `ipxe.efi`. -2. iPXE then initializes the network and switches to HTTP, requesting an iPXE script such as `menu.ipxe`. - -This hybrid approach enables existing PXE infrastructure to use HTTP for the later boot stages without requiring firmware-level HTTP support. - -=== iPXE, Grub2 UEFI HTTP(S) Boot - -In this method, UEFI firmware directly loads boot loaders using HTTP or HTTPS without any TFTP step. - -*Workflow:* - -1. UEFI firmware requests boot loader files from the {SmartProxy} via HTTP or HTTPS. - * For example, it requests `ipxe-<__arch__>.efi`. -2. Grub2 then loads `grub.cfg` and starts the OS installer. - -== File Locations and Roles - -This section describes where iPXE and Grub2 HTTPBoot files are stored, what each file is used for, -and whether it must be provided manually or is created automatically. - -. File Locations and Roles - -[cols="1,1,1", options="header"] -|=== -| Path -| Purpose / Usage -| User Action - -| /var/lib/tftpboot/undionly-ipxe.0 -| 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 undionly-ipxe.0 binary in this directory. - -| /var/lib/tftpboot/ipxe.efi -| iPXE boot loader for **iPXE Chain UEFI**. -Used in UEFI environments to chainload into iPXE for HTTP-based provisioning. -| Place the ipxe.efi binary in this directory. - -| /var/lib/tftpboot/ipxe-.efi -| 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, ipxe-x64.efi) here. - -| /var/lib/tftpboot/grub2/grub.efi -| Grub2 UEFI boot loader for **Grub2 UEFI HTTP** or **HTTPS Boot**. -Used to start UEFI installations via the {SmartProxy}’s HTTPBoot module. -| Place the corresponding architecture-specific file (for example, grubx64.efi) in this directory. - -| /var/lib/tftpboot/grub2/shim.efi -| Secure Boot shim loader for Grub2. -Used when “Grub2 UEFI SecureBoot” or “Grub2 UEFI HTTPS SecureBoot” is selected. -| Place the matching shim binary (for example, shimx64.efi) in this directory. -|=== - -== Shared TFTP and HTTP Root - -The {SmartProxy}’s *HTTPBoot* module and *TFTP* service share the same root directory. -By default, this directory is `/var/lib/tftpboot/`. - -[subs="+quotes"] ----- -URL path: http://<__smartproxy-example-com__>/httpboot/ -Filesystem: /var/lib/tftpboot/ ----- - -This mapping means that the HTTP URL path `/httpboot/` 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: -[subs="+quotes"] ----- -http://<__smartproxy-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 Directory Layout - -This subsection provides an example layout of typical iPXE and HTTPBoot-related files under `/var/lib/tftpboot/`. - ----- -# tree /var/lib/tftpboot/ -/var/lib/tftpboot/ - ├── undionly-ipxe.0 - ├── ipxe.efi - ├── ipxe-x64.efi - └── grub2/ - ├── grubx64.efi - └── shimx64.efi ----- - -[NOTE] -==== -Grub2 UEFI HTTPS Boot relies on the {SmartProxy}’s HTTPS service to securely deliver boot loader binaries (`boot.efi`, `shim*.efi`, and similar) to UEFI clients. -The configuration for this HTTPS service is defined in the {SmartProxy}’s main settings file: -`/etc/foreman-proxy/settings.yml`. -==== diff --git a/guides/common/modules/ref_shared-tftp-http-root.adoc b/guides/common/modules/ref_shared-tftp-http-root.adoc new file mode 100644 index 00000000000..a682a34419c --- /dev/null +++ b/guides/common/modules/ref_shared-tftp-http-root.adoc @@ -0,0 +1,78 @@ +:_mod-docs-content-type: REFERENCE + +[id="ref_shared-tftp-http-root_{context}"] += Shared TFTP and HTTP root + +[role="_abstract"] +The {SmartProxy}’s *HTTPBoot* module and *TFTP* service share the same root directory. +By default, this directory is `/var/lib/tftpboot/`. + +[subs="+quotes"] +---- +URL path: http://_My_Smartproxy_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: +[subs="+quotes"] +---- +http://_My_Smartproxy_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. + +.Model 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 boot loader files + +[cols="1,1", options="header"] +|=== +| Default path +| Purpose + +| `/var/lib/tftpboot/undionly-ipxe.0` +| 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. + +| `/var/lib/tftpboot/ipxe.efi` +| iPXE boot loader for **iPXE Chain UEFI**. +Used in UEFI environments to chainload into iPXE for HTTP-based provisioning. + +| `/var/lib/tftpboot/ipxe-x64.efi` +| Architecture-specific iPXE binary for **iPXE UEFI HTTP** boot. +Used for direct iPXE boot via HTTP without TFTP chainloading. + +| `/var/lib/tftpboot/grub2/grubx64.efi` +| Grub2 UEFI boot loader for **Grub2 UEFI HTTP** or **HTTPS Boot**. +Used to start UEFI installations via the {SmartProxy}’s HTTPBoot module. + +| `/var/lib/tftpboot/grub2/shimx64.efi` +| Secure Boot shim loader for Grub2. +Used when **Grub2 UEFI SecureBoot** or **Grub2 UEFI HTTPS SecureBoot** is selected. +|=== + +[NOTE] +==== +Grub2 UEFI HTTPS Boot relies on the {SmartProxy}’s HTTPS service to securely deliver the `boot.efi`, `shim*.efi`, and similar boot loader binaries to UEFI clients. +The configuration for this HTTPS service is defined in the {SmartProxy}’s main settings file +`/etc/foreman-proxy/settings.yml`. +==== From db9f0f6653a08797f49b791e6ff7e76dfe454621 Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Fri, 28 Nov 2025 12:59:16 +0100 Subject: [PATCH 2/7] Further adjustments --- guides/common/modules/ref_http-bootloaders.adoc | 3 ++- .../common/modules/ref_shared-tftp-http-root.adoc | 14 ++------------ 2 files changed, 4 insertions(+), 13 deletions(-) diff --git a/guides/common/modules/ref_http-bootloaders.adoc b/guides/common/modules/ref_http-bootloaders.adoc index 41434ecd1b2..fb443c5af8e 100644 --- a/guides/common/modules/ref_http-bootloaders.adoc +++ b/guides/common/modules/ref_http-bootloaders.adoc @@ -16,7 +16,8 @@ The boot methods in {Project} 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. +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: + diff --git a/guides/common/modules/ref_shared-tftp-http-root.adoc b/guides/common/modules/ref_shared-tftp-http-root.adoc index a682a34419c..0a2b6e14d3f 100644 --- a/guides/common/modules/ref_shared-tftp-http-root.adoc +++ b/guides/common/modules/ref_shared-tftp-http-root.adoc @@ -14,17 +14,7 @@ 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: -[subs="+quotes"] ----- -http://_My_Smartproxy_Example.com_/httpboot/pxegrub2/grubx64.efi ----- +For example, a file located at `/var/lib/tftpboot/pxegrub2/grubx64.efi` is available over HTTP at `http://_My_Smartproxy_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. @@ -72,7 +62,7 @@ Used when **Grub2 UEFI SecureBoot** or **Grub2 UEFI HTTPS SecureBoot** is select [NOTE] ==== -Grub2 UEFI HTTPS Boot relies on the {SmartProxy}’s HTTPS service to securely deliver the `boot.efi`, `shim*.efi`, and similar boot loader binaries to UEFI clients. +Grub2 UEFI HTTPS Boot relies on the {SmartProxy}’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 {SmartProxy}’s main settings file `/etc/foreman-proxy/settings.yml`. ==== From 3cbe118c09dc7f5e4959071fa59f43c5d64ab77a Mon Sep 17 00:00:00 2001 From: jafiala <56597272+jafiala@users.noreply.github.com> Date: Mon, 1 Dec 2025 08:47:24 +0100 Subject: [PATCH 3/7] Add replaceable attribute Co-authored-by: Maximilian Kolb --- guides/common/modules/ref_shared-tftp-http-root.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/common/modules/ref_shared-tftp-http-root.adoc b/guides/common/modules/ref_shared-tftp-http-root.adoc index 0a2b6e14d3f..11426ac79eb 100644 --- a/guides/common/modules/ref_shared-tftp-http-root.adoc +++ b/guides/common/modules/ref_shared-tftp-http-root.adoc @@ -14,7 +14,7 @@ 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://_My_Smartproxy_Example.com_/httpboot/pxegrub2/grubx64.efi`. +For example, a file located at `/var/lib/tftpboot/pxegrub2/grubx64.efi` is available over HTTP at `http://_{smartproxy-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. From cdfce8ae4692179797f6eff12edaead547ce676a Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Mon, 1 Dec 2025 08:49:52 +0100 Subject: [PATCH 4/7] Add replaceable attribute --- guides/common/modules/ref_grub2-uefi-bootloaders.adoc | 3 ++- guides/common/modules/ref_shared-tftp-http-root.adoc | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc index bf99a098b2f..62401b9f98e 100644 --- a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc +++ b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc @@ -9,7 +9,8 @@ The `bootloader-universe` directory structure organizes Grub2 binaries by OS and PXEGrub2 is managed by the {SmartProxy}’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 {SmartProxy} uses the +This feature does not require explicit configuration. +It is automatically enabled when the {SmartProxy} uses the `/var/lib/tftpboot/bootloader-universe/pxegrub2/` directory structure. == Directory Structure: `bootloader-universe` diff --git a/guides/common/modules/ref_shared-tftp-http-root.adoc b/guides/common/modules/ref_shared-tftp-http-root.adoc index 11426ac79eb..4fec5090a8e 100644 --- a/guides/common/modules/ref_shared-tftp-http-root.adoc +++ b/guides/common/modules/ref_shared-tftp-http-root.adoc @@ -9,12 +9,12 @@ By default, this directory is `/var/lib/tftpboot/`. [subs="+quotes"] ---- -URL path: http://_My_Smartproxy_Example.com_/httpboot/ +URL path: http://__{smartproxy-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://_{smartproxy-example-com}_/httpboot/pxegrub2/grubx64.efi`. +For example, a file located at `/var/lib/tftpboot/pxegrub2/grubx64.efi` is available over HTTP at `http://__{smartproxy-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. From 0f6f21f80f0b955712290fb030ad9d356dfd5e40 Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Tue, 6 Jan 2026 11:05:37 +0100 Subject: [PATCH 5/7] fix pxelinux ref --- ...n_bootloader-binary-location-overview.adoc | 7 +++-- .../common/modules/ref_bootloader-types.adoc | 13 ++++---- .../modules/ref_pxelinux-bootloaders.adoc | 31 ++++++++----------- 3 files changed, 24 insertions(+), 27 deletions(-) diff --git a/guides/common/modules/con_bootloader-binary-location-overview.adoc b/guides/common/modules/con_bootloader-binary-location-overview.adoc index 7fa95bd1999..0c5129bc8e5 100644 --- a/guides/common/modules/con_bootloader-binary-location-overview.adoc +++ b/guides/common/modules/con_bootloader-binary-location-overview.adoc @@ -3,16 +3,17 @@ [id="con_bootloader-binary-location-overview_{context}"] = Boot loader management and file structure +[role="_abstract"] {Project} manages and serves boot loader binaries through the *{SmartProxy}*, which provides the network boot services used during automated host provisioning. {Project} supports PXE boot for BIOS and UEFI firmware on various architectures utilizing TFTP or HTTP(S). During a network-based installation, {SmartProxy} coordinates the following services: -* DHCP: DHCP: Assigns IP addresses and provides the boot loader filename and server information. +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:: Delivers boot loaders such as PXELinux, Grub2, or iPXE binaries to clients. -* HTTP(S): Serves boot loaders and installation files via the {SmartProxy}’s HTTPBoot module. +HTTP(S):: Serves boot loaders and installation files 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 *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. diff --git a/guides/common/modules/ref_bootloader-types.adoc b/guides/common/modules/ref_bootloader-types.adoc index c975ee5aec8..0d8c4a4cfce 100644 --- a/guides/common/modules/ref_bootloader-types.adoc +++ b/guides/common/modules/ref_bootloader-types.adoc @@ -3,18 +3,19 @@ [id="ref_bootloader-types_{context}"] = Boot loader types in {Project} +[role="_abstract"] {Project} uses multiple types of PXE boot loaders during network provisioning, depending on firmware type, protocol, and boot environment. In {Project}, 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 {SmartProxy} (via TFTP or HTTP). Select a PXE Loader based on whether the host uses **BIOS**, **UEFI**, **Secure Boot**, or **HTTP Boot**. -== PXE Loader Types and Boot Protocols in {Project} +== 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 +.PXE loader types and boot protocols [cols="1,1,1,1", options="header"] |=== @@ -109,13 +110,13 @@ iPXE Direct (HTTP):: Boots directly via embedded or firmware-level iPXE using on None:: {Project} does not specify a boot loader. -== Boot Loader File Mapping and Architecture Naming +== 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 +.PXE loader to boot loader mapping [cols="1,1,1", options="header"] |=== @@ -180,12 +181,12 @@ without requiring administrators to manage architecture-specific filenames. | ipxe.efi |=== -== Architecture-Based File Naming +== 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 +.Boot loader filenames by architecture [cols="1,1,1", options="header"] |=== diff --git a/guides/common/modules/ref_pxelinux-bootloaders.adoc b/guides/common/modules/ref_pxelinux-bootloaders.adoc index cff09cdf35c..76e269a56e1 100644 --- a/guides/common/modules/ref_pxelinux-bootloaders.adoc +++ b/guides/common/modules/ref_pxelinux-bootloaders.adoc @@ -3,44 +3,38 @@ [id="ref_pxelinux-bootloaders_{context}"] = PXELinux boot loaders +[role="_abstract"] *PXELinux* is a Syslinux-based PXE boot loader used by {Project} for BIOS and UEFI systems. In {Project}, PXELinux enables hosts to boot into the OS installer automatically during provisioning. When a host is set to *Build mode*, {Project} generates a host-specific configuration file and places it in the TFTP directory managed by the {SmartProxy}. -== File Locations and Roles - -This section describes where PXELinux-related files are stored, the role of each file, -and whether the user needs to create or provide them manually. - -. File Locations and Roles +.Default boot loader files [cols="1,2,1", options="header"] |=== -| Path -| Purpose / Usage -| User Action +| Default path +| Purpose +| User action -| /var/lib/tftpboot/pxelinux.0 +| `/var/lib/tftpboot/pxelinux.0` | The main PXELinux boot loader binary. Installed automatically by the {foreman-installer}. | *Auto-installed by {foreman-installer}* -| /var/lib/tftpboot/pxelinux.cfg/ -| Directory containing configuration files generated by {Project} for each host (for example, 01-52-54-00-ab-cd-ef). +| `/var/lib/tftpboot/pxelinux.cfg/` +| Directory that contains configuration files generated by {Project} for each host (for example, 01-52-54-00-ab-cd-ef). | *Auto-created during Build mode* -| /var/lib/tftpboot/ldlinux.c32 +| `/var/lib/tftpboot/ldlinux.c32` | Support module required by PXELinux for menu and filesystem operations. | **Provide manually** -| /var/lib/tftpboot/menu.c32, /var/lib/tftpboot/chain.c32 +| `/var/lib/tftpboot/menu.c32`, `/var/lib/tftpboot/chain.c32` | Optional Syslinux modules for displaying boot menus or chainloading. | **Provide manually** |=== -== Example Directory Layout - -This subsection shows an example of how PXELinux files are organized under the TFTP root directory. - +.Model PXELinux-related directory layout +==== ---- # tree /var/lib/tftpboot/ /var/lib/tftpboot/ @@ -52,6 +46,7 @@ This subsection shows an example of how PXELinux files are organized under the T ├── default └── 01-52-54-00-ab-cd-ef ---- +==== [NOTE] ==== From 2b627c41e27ecf5953925fa2ce25226c01596623 Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Tue, 6 Jan 2026 12:13:01 +0100 Subject: [PATCH 6/7] fix PXEGrub2ref --- .../modules/ref_grub2-uefi-bootloaders.adoc | 95 ++++++++----------- 1 file changed, 37 insertions(+), 58 deletions(-) diff --git a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc index 62401b9f98e..d9d260add8a 100644 --- a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc +++ b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc @@ -13,63 +13,50 @@ This feature does not require explicit configuration. It is automatically enabled when the {SmartProxy} uses the `/var/lib/tftpboot/bootloader-universe/pxegrub2/` directory structure. -== Directory Structure: `bootloader-universe` +== Directory structure: `bootloader-universe` -This section explains the purpose and layout of the `bootloader-universe` directory, which enables multiple OS versions and architectures to coexist cleanly. - -=== Organized Hierarchy by OS and Architecture +The `bootloader-universe` directory enables multiple OS versions and architectures to coexist without conflicts. When the {SmartProxy} recognizes the `/var/lib/tftpboot/bootloader-universe/pxegrub2/` structure, boot loaders are stored in an organized hierarchy by OS, version, and architecture. -This allows multiple distributions and versions to coexist without conflicts. - -Before placing boot loader binaries (`shim<__arch__>.efi`, `grub<__arch__>.efi`), you must manually create the corresponding directory hierarchy using the `mkdir` command. - -Example: ----- -mkdir -p /var/lib/tftpboot/bootloader-universe/pxegrub2/rocky/9.5/x86_64 ----- - -=== File Locations and Roles -The following table summarizes the purpose of each directory in the `bootloader-universe` hierarchy. - -. File Locations and Roles +Before placing boot loader binaries (`shim____.efi`, `grub____.efi`), you must manually create the corresponding directory hierarchy by using the `mkdir` command, for example, `# mkdir -p /var/lib/tftpboot/bootloader-universe/pxegrub2/____/____/____` +.Default `bootloader universe` files [cols="1,2,1", options="header"] |=== | Path | Purpose / Usage | User Action -| `/var/lib/tftpboot/bootloader-universe/pxegrub2/<__distro__>/<__version__>/<__arch__>/` -| Stores OS- and architecture-specific Grub2 binaries (shim<__arch__>.efi, grub<__arch__>.efi) and symbolic links (boot.efi, boot-sb.efi). +| `/var/lib/tftpboot/bootloader-universe/pxegrub2/____/____/____/` +| Stores OS- and architecture-specific Grub2 binaries (shim____.efi, grub____.efi) and symbolic links (boot.efi, boot-sb.efi). Used for version-specific boot loader management within the `bootloader-universe` hierarchy. | **Create manually** -| `/var/lib/tftpboot/bootloader-universe/pxegrub2/<__distro__>/default/<__arch__>/` -| Stores OS- and architecture-specific Grub2 binaries (shim<__arch__>.efi, grub<__arch__>.efi) and symbolic links (boot.efi, boot-sb.efi). +| `/var/lib/tftpboot/bootloader-universe/pxegrub2/____/default/____/` +| Stores OS- and architecture-specific Grub2 binaries (`shim____.efi`, `grub____.efi`) and symbolic links (`boot.efi`, `boot-sb.efi`). Used as a fallback directory when a specific version is not available. | **Create manually** -| /var/lib/tftpboot/host-config/<__My_MAC_Address__>/grub2/ +| `/var/lib/tftpboot/host-config/____/grub2/` | Host-specific directory automatically created when a host enters *Build mode*. -Contains symbolic links (boot.efi, boot-sb.efi) and a generated grub.cfg. +Contains symbolic links (`boot.efi`, `boot-sb.efi`) and a generated `grub.cfg`. | *Auto-created by {SmartProxy}* |=== -Example structure: - +.Model `bootloader-universe` directory layout +==== ---- # tree /var/lib/tftpboot/bootloader-universe/ /var/lib/tftpboot/bootloader-universe/ ├── pxegrub2/ - │ ├── rocky/9.5/x86_64/ + │ ├── ____/____/____/ │ │ ├── shimx64.efi │ │ ├── grubx64.efi │ │ ├── boot.efi -> grubx64.efi │ │ └── boot-sb.efi -> shimx64.efi - │ └── ubuntu/22.04/x86_64/ + │ └── ubuntu/22.04/____/ │ ├── shimx64.efi │ ├── grubx64.efi │ ├── boot.efi -> grubx64.efi @@ -77,27 +64,22 @@ Example structure: └── host-config/ └── 52-54-00-ab-cd-ef/ └── grub2/ - ├── boot.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/boot.efi - ├── boot-sb.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/boot-sb.efi + ├── boot.efi -> ../../../bootloader-universe/pxegrub2/____/____/____/boot.efi + ├── boot-sb.efi -> ../../../bootloader-universe/pxegrub2/____/____/____/boot-sb.efi ├── grub.cfg - ├── shimx64.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/shimx64.efi - └── grubx64.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/grubx64.efi + ├── shimx64.efi -> ../../../bootloader-universe/pxegrub2/____/____/____/shimx64.efi + └── grubx64.efi -> ../../../bootloader-universe/pxegrub2/____/____/____/grubx64.efi ---- -[NOTE] -==== -* In `bootloader-universe/pxegrub2/<__distro__>/<__version__>/<__arch__>/`, -`boot.efi` and `boot-sb.efi` are symbolic links to `grub<__arch__>.efi` and `shim<__arch__>.efi`, respectively. -The {SmartProxy} automatically creates host-specific links to these files under `host-config/<__My_MAC_Address__>/grub2/`. +In this structure, the following principles apply: -* In the {ProjectWebUI}, OS and distribution identifiers (`<__distro__>`) must not contain spaces. -==== +* `boot.efi` and `boot-sb.efi` are symbolic links to `grub____.efi` and `shim____.efi`, respectively. +The {SmartProxy} automatically creates host-specific links to these files under `host-config/____/grub2/`. -[IMPORTANT] -==== -You must manually create `boot.efi` and `boot-sb.efi` symbolic links within each `<__arch__>` directory. +* In the {ProjectWebUI}, the `____` OS and distribution identifiers must not contain spaces. -Example (x86_64): +* You must manually create `boot.efi` and `boot-sb.efi` symbolic links within each `____` directory, for example: ++ [subs="+quotes"] ---- $ ln -s grubx64.efi boot.efi @@ -108,47 +90,44 @@ $ chmod 644 grubx64.efi shimx64.efi The `chmod` command ensures that TFTP and HTTPBoot clients can read these files. ==== -== Legacy Layout (Non-`bootloader-universe`) +== Legacy layout -This section explains how boot loaders are handled when the `bootloader-universe` directory is not used. This layout remains supported for backward compatibility. If the `/var/lib/tftpboot/bootloader-universe/pxegrub2/` structure is not used, {Project} 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 {SmartProxy} creates a host-specific directory with the required configuration files and links. -=== File Locations and Roles - -. File Locations and Roles - +.Default legacy layout files [cols="1,1,1", options="header"] |=== | Path -| Purpose / Usage -| User Action +| Purpose +| User action -| /var/lib/tftpboot/grub2/ +| `/var/lib/tftpboot/grub2/` | Default directory used when `bootloader-universe` is not enabled. -Contains Grub2 UEFI boot loader binaries such as grubx64.efi, shimx64.efi, grubaa64.efi, and shimaa64.efi. -| Place the appropriate boot loader binaries (grub<__arch__>.efi, shim<__arch__>.efi) in this directory. +Contains Grub2 UEFI boot loader binaries such as `grubx64.efi`, `shimx64.efi`, `grubaa64.efi`, and `shimaa64.efi`. +| Place the appropriate boot loader binaries (`grub____.efi`, `shim____.efi`) in this directory. No subdirectory creation is required. -| /var/lib/tftpboot/host-config/<__My_MAC_Address__>/grub2/ +| `/var/lib/tftpboot/host-config/____/grub2/` | Host-specific directory automatically created when a host enters *Build mode*. -Contains symbolic links (boot.efi, boot-sb.efi) and a generated grub.cfg. +Contains symbolic links (`boot.efi`, `boot-sb.efi`) and a generated `grub.cfg`. | *Auto-created by {SmartProxy}* |=== -Example (x86_64): - +.Example `tftpboot/grub2/` structure: +==== ---- /var/lib/tftpboot/grub2/ ├── grubx64.efi └── shimx64.efi ---- +==== -When a host enters *Build mode*, the {SmartProxy} creates the following directory structure: +When a host enters *Build mode*, the {SmartProxy} creates the following directory structure: ---- # tree /var/lib/tftpboot/ /var/lib/tftpboot/ From 9fd1f0944baa795a5d68a3d2c1f0a01f3c2fdbe5 Mon Sep 17 00:00:00 2001 From: Jan Fiala Date: Tue, 6 Jan 2026 12:14:38 +0100 Subject: [PATCH 7/7] Fix heading --- guides/common/modules/ref_grub2-uefi-bootloaders.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc index d9d260add8a..4aa70a3b541 100644 --- a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc +++ b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc @@ -26,8 +26,8 @@ Before placing boot loader binaries (`shim____.efi`, `grub____ [cols="1,2,1", options="header"] |=== | Path -| Purpose / Usage -| User Action +| Purpose +| User action | `/var/lib/tftpboot/bootloader-universe/pxegrub2/____/____/____/` | Stores OS- and architecture-specific Grub2 binaries (shim____.efi, grub____.efi) and symbolic links (boot.efi, boot-sb.efi).