Image Customizer PXE Support

Overview

Booting a host with an OS served over the network is one of the most popular methods for booting baremetal hosts. It requires no physical access to individual hosts and also centralizes the deployment configuration to a single server.

One way of enabling such setup is using the PXE (Preboot eXecution Environment) Boot protocol. The user can setup a server with all the OS artifacts, a DHCP endpoint, and a tftp connection endpoint. When a client machine is powered on, its firmware will look for a DHCP server on the same network and will find the one configured by the user.

The DHCP server will serve information about the tftp endpoint to the client, and the client firmware can then proceed with retrieving the OS artifacts over tftp, loading them into memory, and finally handing control over to the loaded OS.

The tftp protocol expects certain artifacts to be present on the server:

  • the boot loader (the shim and something like grub).
  • the boot loader configuration (like grub.cfg).
  • the kernel image.
  • the initrd image.

Once the PXE client retrieves those artifacts, the boot loader is run and it reads the boot loader configuration. It then transfers control over to the kernel image with the retrieved initrd image as its file system.

The initrd image is customized to perform the next set of tasks now that an OS is running. The tasks can range from just running some local scripts all the way to installing another OS.

PXE Support in The Image Customizer

The Image Customizer tool can take an input image, customize the OS, and produce the artifacts necessary to power the PXE flow described above.

In addition to customizing the OS contents, the user can also decide how it will be packaged. There are two supported options:

  • The initrd image is the full OS.
  • The initrd image is a bootstrap image with minimal contents, and the full OS is stored in a separate image.

There are pros and cons for each configuration - see the Live OS page for details.

When the bootstrap configuration is selected, The bootstrapped image is a bootable ISO (image.iso) containing the same PXE configuration (same bootloader configuration, same kernel, same full OS file system, etc.). This can be very handy when testing the PXE configuration without having to setup a PXE environment.

If the user needs to download additional artifacts after booting, the user can implement a user-space solution that will perform the download tasks.

Creating and Deploying PXE Boot Artifacts

The Image Customizer tool can create the PXE artifacts by simply setting the --output-image-format parameter to pxe-dir or pxe-tar on the command-line.

For additional details, see the PXE Configuration page.

Below is a list of the core artifacts and where on the PXE server they should be deployed:

artifacts output folder     target on PXE server
------------------------    ------------------------------
|                           <tftp-server-root>
|- bootx64.efi                |- bootx64.efi
|- grubx64.efi                |- grubx64.efi
|- boot                       |- boot
   |- grub2                      |- grub2
      |- grub.cfg                   |- grub.cfg
      |- grubenv                    |- grubenv
|- vmlinuz                    |- vmlinuz
|- initrd.img                 |- initrd.img
|
|                           <yyyy-server-root>
|- other-user-artifacts       |- other-user-artifacts
|- image.iso                  |- image.iso

Notes:

  • yyyy can be any protocol supported by Dracut’s livenet module (i.e tftp, http, etc).
  • image.iso is the bootstrapped image containing the full OS file system. It is generated by the Image Customizer tool when the output format is set to pxe-dir or pxe-tar.
  • The bootstrapped ISO image file location under the server root is customizable - but it must match what is specified in grub.cfg’s root=live:<URL> (configured through bootstrapBaseUrl or bootstrapFileUrl).