iPXE Boot Setup

This guide covers advanced network boot configuration for different hardware environments.

How iPXE Boot Works

NodeFoundry uses iPXE to network-boot bare-metal servers. The boot flow:

1. Server powers on, firmware initiates PXE
2. DHCP provides an IP and points to the NodeFoundry boot server
3. iPXE downloads a boot script from /boot/config?mac=<mac>
4. The script loads the default OS image and boots the node
5. On first boot, a new node entry is created in the Sentinel database

BIOS vs UEFI

NodeFoundry supports both BIOS and UEFI PXE boot. The boot server automatically detects the firmware type and serves the appropriate boot loader.

Switch Configuration Terminals

Cisco IOS

ip dhcp pool NODEFOUNDRY
  network 10.10.1.0 255.255.255.0
  default-router 10.10.1.1
  next-server 10.10.1.10
  filename "ipxe/boot.ipxe"

MikroTik RouterOS

/ip dhcp-server network set 0 \
  next-server=10.10.1.10 \
  boot-file-name="ipxe/boot.ipxe"

Ubiquiti UniFi

In the UniFi Network console:

1. Go to Settings > Networks
2. Select your management network
3. Under DHCP, set DHCP Boot to enabled
4. Set Server to the master node IP
5. Set File to ipxe/boot.ipxe

Using NodeFoundry’s Built-in DHCP

If you don’t want to configure your switch, NodeFoundry can run its own DHCP server:

$ nf network create \
  --cidr 10.10.1.0/24 \
  --gateway 10.10.1.1 \
  --rangeStart 10.10.1.50 \
  --rangeEnd 10.10.1.250 \
  --nicId <nic-id>

Warning — Running two DHCP servers on the same network segment will cause conflicts. Disable your switch’s DHCP if using NodeFoundry’s built-in server.

Boot Images

Manage which OS image is served to booting nodes:

$ nf images available           # see what's in the registry
$ nf images download --id ...   # download to master
$ nf images default --id ...    # set as boot image

Troubleshooting