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/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_grub2-uefi-bootloaders.adoc b/guides/common/modules/ref_grub2-uefi-bootloaders.adoc index bf99a098b2f..4aa70a3b541 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: - +.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 @@ -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,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/ diff --git a/guides/common/modules/ref_http-bootloaders.adoc b/guides/common/modules/ref_http-bootloaders.adoc new file mode 100644 index 00000000000..fb443c5af8e --- /dev/null +++ b/guides/common/modules/ref_http-bootloaders.adoc @@ -0,0 +1,36 @@ +:_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_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] ==== 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..4fec5090a8e --- /dev/null +++ b/guides/common/modules/ref_shared-tftp-http-root.adoc @@ -0,0 +1,68 @@ +:_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://__{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. + +.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`, `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`. +====