Skip to content

PXE

Overview

PXE (Preboot Execution Environment) discovery is the primary mechanism by which bare-metal servers and virtual machines that support network boot are introduced into DRP. When a machine is powered on with PXE boot enabled, it contacts DRP's DHCP service, receives boot files, loads the Sledgehammer discovery OS, and registers itself as a Machine object in DRP. This entire process is automatic: no human interaction is required between powering on the hardware and the machine appearing, fully inventoried, in DRP.

DHCP Handshake and Boot File Delivery

Discovery begins when the machine's NIC firmware sends a DHCP Discover broadcast. DRP's built-in DHCP server responds with an offer that includes the standard IP/gateway/DNS settings along with PXE-specific options: the filename of the bootloader and the TFTP/HTTP server address from which to retrieve it. DRP supports both legacy BIOS (TFTP-based PXELinux) and UEFI (HTTP-based iPXE or Grub) boot paths, auto-detecting the appropriate mode from the client's DHCP request.

The bootloader DRP delivers is iPXE, which then makes a second HTTP request to DRP to retrieve the iPXE script for the machine. This script is generated per-machine from the machine's assigned BootEnv template. For a newly seen machine (one that does not yet exist in DRP's database), the endpoint's unknownBootEnv preference determines what BootEnv to use — by default this is configured to serve Sledgehammer, the DRP discovery OS.

Sledgehammer and Machine Inventory

Sledgehammer is a minimal Linux environment built specifically for hardware discovery. It runs entirely in RAM and is never installed to disk. Once Sledgehammer boots, a startup script automatically launches the machine agent (dr-provision-agent) and runs the join-up sequence.

The join-up process collects a detailed inventory of the physical system:

  • Hardware UUID (from SMBIOS/DMI)
  • MAC addresses for all network interfaces
  • Memory configuration and capacity
  • CPU count and model
  • Serial numbers and chassis information
  • Any cloud provider metadata if running as a VM

This inventory is submitted to the DRP endpoint, which uses it to determine whether the machine is already known (matched by hardware address or UUID) or is genuinely new. If no match is found, DRP creates a new Machine object. If a match is found, DRP updates the existing object and returns its current configuration, including an API token for the agent to use for subsequent operations.

From Unknown to Discovered

Once the Machine object exists in DRP and the agent is connected, DRP sets the machine's workflow to the default discovery workflow (typically universal-discover in Universal Workflow deployments). The agent begins executing the task list, which drives the machine through deeper inventory (firmware, RAID, BIOS settings), classification (matching hardware profiles), and validation stages. At the end of the discovery workflow, the machine's status reflects a fully inventoried, classified system ready for application deployment.

The machine's BootEnv is updated by the workflow to local once discovery is complete and no further PXE boot is needed. Subsequent power cycles cause the machine to boot from its local disk rather than restarting discovery.

Role of Preferences in PXE Boot

DRP's preferences (unknownBootEnv, defaultBootEnv, defaultWorkflow, defaultStage) control the default behavior for every machine that PXE boots. The unknownBootEnv determines what to serve to a machine with no existing record. The defaultWorkflow determines what workflow is automatically assigned when a new machine is created via PXE. These preferences allow operators to configure the discovery behavior centrally rather than per-machine, enabling zero-touch provisioning for large environments.

Read More