diff --git a/guides/common/assembly_bootloader-binary-location.adoc b/guides/common/assembly_bootloader-binary-location.adoc index b909a27642a..91657060ef0 100644 --- a/guides/common/assembly_bootloader-binary-location.adoc +++ b/guides/common/assembly_bootloader-binary-location.adoc @@ -8,4 +8,4 @@ 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] diff --git a/guides/common/modules/con_bootloader-binary-location-overview.adoc b/guides/common/modules/con_bootloader-binary-location-overview.adoc index 7fa95bd1999..8086326453c 100644 --- a/guides/common/modules/con_bootloader-binary-location-overview.adoc +++ b/guides/common/modules/con_bootloader-binary-location-overview.adoc @@ -3,22 +3,47 @@ [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. TFTP also servers the following resources: +. Configuration files for boot loaders +. Kernels and `initramdisk` -* 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. HTTP(S) also serves the following resources: +. Configuration files for bootloaders +. Kernels & initramdisk +. Installation config files (Kickstart) +. Repository content +. Communication between Host <> 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 *PXE Loader* setting in {Project}. +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 {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 their configuration files. -All boot loaders are stored under the {SmartProxy}’s TFTP root directory (/var/lib/tftpboot/), which is also shared by the HTTPBoot service. +All boot loaders are stored on {SmartProxy} under the TFTP root directory (`/var/lib/tftpboot/`), which is also shared by the HTTPBoot service. + +The {SmartProxy} also generates a directory for each provisioned host and names the directory with the host MAC address. In these directories, the {SmartProxy} 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 {ProjectName} 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`). diff --git a/guides/common/modules/ref_bootloader-types.adoc b/guides/common/modules/ref_bootloader-types.adoc index c975ee5aec8..20d24bd2926 100644 --- a/guides/common/modules/ref_bootloader-types.adoc +++ b/guides/common/modules/ref_bootloader-types.adoc @@ -3,22 +3,23 @@ [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"] |=== -| PXE Loader (UI Label) +| PXE loader (UI label) | Category | Firmware | Protocol @@ -109,18 +110,18 @@ 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"] |=== -| PXE Loader (UI Label) -| Boot Loader File (Template Path) +| PXE loader (UI label) +| Boot loader file (template path) | Example (x86_64) | None @@ -128,64 +129,64 @@ without requiring administrators to manage architecture-specific filenames. | - | PXELinux BIOS -| pxelinux.0 -| pxelinux.0 +| `pxelinux.0` +| `pxelinux.0` | PXELinux UEFI -| pxelinux.efi -| pxelinux.efi +| `pxelinux.efi` +| `pxelinux.efi` | Grub2 BIOS -| grub<__arch__>.0 -| grubx64.0 +| `grub<__arch__>.0` +| `grubx64.0` | Grub2 ELF -| grub<__arch__>.elf -| grubx64.elf +| `grub<__arch__>.elf` +| `grubx64.elf` | Grub2 UEFI -| grub<__arch__>.efi -| grubx64.efi +| `grub<__arch__>.efi` +| `grubx64.efi` | Grub2 UEFI SecureBoot -| shim<__arch__>.efi -| shimx64.efi +| `shim<__arch__>.efi` +| `shimx64.efi` | Grub2 UEFI HTTP -| grub<__arch__>.efi (via HTTP) -| grubx64.efi +| `grub<__arch__>.efi` (via HTTP) +| `grubx64.efi` | Grub2 UEFI HTTPS -| grub<__arch__>.efi (via HTTPS) -| grubx64.efi +| `grub<__arch__>.efi` (via HTTPS) +| `grubx64.efi` | Grub2 UEFI HTTPS SecureBoot -| shim<__arch__>.efi (via HTTPS) -| shimx64.efi +| `shim<__arch__>.efi` (via HTTPS) +| `shimx64.efi` | iPXE Embedded -| Rendered dynamically as {Project}_url('iPXE') +| Rendered dynamically as `{Project}_url('iPXE')` | - | iPXE UEFI HTTP -| ipxe-<__arch__>.efi -| ipxe-x64.efi +| `ipxe-<__arch__>.efi` +| `ipxe-x64.efi` | iPXE Chain BIOS -| undionly-ipxe.0 -| undionly-ipxe.0 +| `undionly-ipxe.0` +| `undionly-ipxe.0` | iPXE Chain UEFI -| ipxe.efi -| ipxe.efi +| `ipxe.efi` +| `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"] |=== @@ -194,23 +195,23 @@ For example, `x86_64` hosts use `grubx64.efi`, while `aarch64` hosts use `grubaa | Internal Suffix (for reference) | i386, i686, x86 -| grubia32.efi -| ia32 +| `grubia32.efi` +| `ia32` | x86_64, amd64 -| grubx64.efi, shimx64.efi -| x64 +| `grubx64.efi`, `shimx64.efi` +| `x64` | aarch64, aa64 -| grubaa64.efi, shimaa64.efi -| aa64 +| `grubaa64.efi`, `shimaa64.efi` +| `aa64` | ppc64, ppc64le -| grubppc64.efi -| ppc64, ppc64le +| `grubppc64.efi` +| `ppc64`, `ppc64le` | Other architectures (for example, riscv64, loongarch64) -| grubriscv64.efi +| `grubriscv64.efi` | normalized name |=== @@ -220,5 +221,4 @@ For example, a host with architecture `aarch64` and PXE Loader set to `Grub2 UEF /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. +This mechanism allows {Project} to select the correct boot loader automatically, without requiring users to manage architecture-specific filenames manually. diff --git a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc index bf99a098b2f..20f22faefdb 100644 --- a/guides/common/modules/ref_grub2-uefi-bootloaders.adoc +++ b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc @@ -9,66 +9,54 @@ 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` +== 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 +| Purpose +| 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: - +.`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 @@ -76,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 @@ -107,47 +90,43 @@ $ 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. +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): - +.`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*, {SmartProxy} creates the following directory structure: ---- # tree /var/lib/tftpboot/ /var/lib/tftpboot/ diff --git a/guides/common/modules/ref_http-compatible-boot-loaders.adoc b/guides/common/modules/ref_http-compatible-boot-loaders.adoc new file mode 100644 index 00000000000..57e2c14b928 --- /dev/null +++ b/guides/common/modules/ref_http-compatible-boot-loaders.adoc @@ -0,0 +1,107 @@ +:_mod-docs-content-type: REFERENCE + +[id="http-compatible-boot-loaders_{context}"] += HTTP-compatible boot loaders + +[role="_abstract"] +In addition to the TFTP-based PXE mechanism, {Project} supports boot methods that use HTTP. +These methods use the *HTTPBoot* module of {SmartProxy} to deliver boot loaders and installation files. +HTTP-compatible boot methods in {Project} 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 {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, 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 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. + +== 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 `/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`. + +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. + +.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,1", options="header"] +|=== +| Default path +| Purpose +| 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-compatible provisioning. +| *Place the `ipxe.efi` binary in this directory.* + +| `/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. +| *Place the architecture-matched file, for example, `ipxe-x64.efi`, in this directory.* + +| `/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. +| *Place the corresponding architecture-specific file, for example, `grubx64.efi`, in this directory.* + +| `/var/lib/tftpboot/grub2/shimx64.efi` +| 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, `shimx64.efi`, in this directory.* +|=== + +[NOTE] +==== +Grub2 and 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`. +==== 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_pxelinux-bootloaders.adoc b/guides/common/modules/ref_pxelinux-bootloaders.adoc index cff09cdf35c..ece30863e9c 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. - +.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] ====