Boot loader ref file changes

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]

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.

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"]
 |===

guides/common/modules/ref_grub2-uefi-bootloaders.adoc

@@ -9,94 +9,77 @@ 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__<My_Arch>__.efi`, `grub__<My_Arch>__.efi`), you must manually create the corresponding directory hierarchy by using the `mkdir` command, for example, `# mkdir -p /var/lib/tftpboot/bootloader-universe/pxegrub2/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__`
 
+.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/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__/`
+| Stores OS- and architecture-specific Grub2 binaries (shim__<My_Arch>__.efi, grub__<My_Arch>__.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/__<My_Distribution>__/default/__<My_Arch>__/`
+| Stores OS- and architecture-specific Grub2 binaries (`shim__<My_Arch>__.efi`, `grub__<My_Arch>__.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/__<My_MAC_Address>__/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/
+ │    ├── __<My_Distribution>__/__<My_Version>__/__<My_Arch>__/
  │    │    ├── shimx64.efi
  │    │    ├── grubx64.efi
  │    │    ├── boot.efi -> grubx64.efi
  │    │    └── boot-sb.efi -> shimx64.efi
- │    └── ubuntu/22.04/x86_64/
+ │    └── ubuntu/22.04/__<My_Arch>__/
  │         ├── shimx64.efi
  │         ├── grubx64.efi
  │         ├── boot.efi -> grubx64.efi
  │         └── boot-sb.efi -> shimx64.efi
  └── host-config/
       └── 52-54-00-ab-cd-ef/
            └── grub2/
-                ├── boot.efi -> ../../../bootloader-universe/pxegrub2/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/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__/boot.efi
+                ├── boot-sb.efi -> ../../../bootloader-universe/pxegrub2/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__/boot-sb.efi
                 ├── grub.cfg
-                ├── shimx64.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/shimx64.efi
-                └── grubx64.efi -> ../../../bootloader-universe/pxegrub2/rocky/9.5/x86_64/grubx64.efi
+                ├── shimx64.efi -> ../../../bootloader-universe/pxegrub2/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__/shimx64.efi
+                └── grubx64.efi -> ../../../bootloader-universe/pxegrub2/__<My_Distribution>__/__<My_Version>__/__<My_Arch>__/grubx64.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__<My_Arch>__.efi` and `shim__<My_Arch>__.efi`, respectively.
+The {SmartProxy} automatically creates host-specific links to these files under `host-config/__<My_MAC_Address>__/grub2/`.
 
-[IMPORTANT]
-====
-You must manually create `boot.efi` and `boot-sb.efi` symbolic links within each `<__arch__>` directory.
+* In the {ProjectWebUI}, the `__<My_Distribution>__` 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 `__<My_Arch>__` 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__<My_Arch>__.efi`, `shim__<My_Arch>__.efi`) in this directory.
 No subdirectory creation is required.
 
-| /var/lib/tftpboot/host-config/<__My_MAC_Address__>/grub2/
+| `/var/lib/tftpboot/host-config/__<My_MAC_Address>__/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/

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-__<arch>__.efi`.
+. Grub2 loads `grub.cfg` and starts the OS installer.