Troubleshooting PXE Booting and Node Provisioning

Introduction

As explained in the Warewulf Provisioning Guide, Warewulf provisions nodes configured to PXE boot.
If a local disk is present and bootable, change the boot order in the node’s BIOS—this step precedes provisioning.

When a node boots via PXE, its firmware initializes hardware and requests a BOOTP/DHCP address from the network. The DHCP server (either the Warewulf controller or an external server) responds with a next-server directive and a filename. PXE then downloads that file via TFTP and executes a bootloader (iPXE or GRUB).

The bootloader retrieves the kernel, image, and overlays from the Warewulf HTTP server.
In single-stage provisioning, the image and overlays combine immediately as the kernel’s initial root filesystem.
In two-stage provisioning, the bootloader loads a minimal initial rootfs (via dracut), and the kernel later retrieves and deploys the full image and overlays.

The wwclient daemon runs on the node after boot to refresh runtime overlays as needed.

Problem

Nodes fail to boot after being set to boot from PXE.

Resolution

Node boot failures can occur for several reasons. Follow these steps to isolate the issue.

Verify Services

Ensure that you enable and start all necessary Warewulf and system services:

systemctl status httpd dhcpd tftp-server.socket warewulfd

If any of these services are inactive or failed, start and enable them:

systemctl enable --now httpd dhcpd tftp-server.socket warewulfd

Confirm that warewulfd is running correctly:

systemctl status warewulfd

A healthy service should display as active (running) and include logs like:

[Thu May 29 18:26:46 UTC 2025] send /etc/warewulf/ipxe/default.ipxe -> n1
[Thu May 29 18:26:46 UTC 2025] request from hwaddr:5a:00:05:78:dc:f8 ipaddr:10.0.0.103:8209 | stage:kernel
[Thu May 29 18:26:46 UTC 2025] SERV   : stage_file '/var/lib/warewulf/chroots/rockylinux-9.4/rootfs/lib/modules/.../vmlinuz'

If warewulfd is active but nodes still fail to retrieve boot files, proceed to firewall and network checks.

Check firewall and network access

A misconfigured or active firewall is a common cause of PXE and iPXE boot issues.
To quickly rule out the firewall as the problem, temporarily stop it:

systemctl stop firewalld

If you prefer to keep the firewall enabled, ensure Warewulf-related services and interfaces are correctly allowed:

firewall-cmd --permanent --zone=internal --add-interface=<your_interface>
firewall-cmd --permanent --zone=internal --add-service=warewulf
firewall-cmd --permanent --zone=internal --add-service=http
firewall-cmd --permanent --zone=internal --add-service=tftp
firewall-cmd --reload

Then verify:

firewall-cmd --list-all --zone=internal

Your configuration should include at least the following services:

services: http tftp warewulf

💡 TIP Most PXE boot issues trace back to blocked TFTP or HTTP traffic, even when warewulfd appears healthy.

Test TFTP server

Check that the TFTP service can serve files correctly:

tftp <tftpserverIPADDR> -c get /var/lib/warewulf/bin-x86_64-efi-snponly.efi

💡 TIP Run this test from a node in the same subnet as the Warewulf headnode to verify network and TFTP service status.

Check SELinux

Warewulf supports provisioning nodes with SELinux enabled, but the image must reside on a filesystem that supports labeling.

If you enable SELinux on a filesystem without labeling support, such as ramfs, the following warning may appear:

Skipping SELinux configuration: rootfs does not support SELinux contexts

To turn off SELinux during provisioning:

wwctl node set --kernelargs="selinux=0"

To keep SELinux enabled, set the root filesystem to tmpfs:

wwctl node set --root=tmpfs n1

⚠️ WARNING In Warewulf v4.6.0 and v4.6.1, a bug in wwinit causes SELinux to fail due to improper labeling of the /run/ filesystem. You can backport the fix manually if needed.

iPXE troubleshooting

If you’re using iPXE (the default bootloader), access its command prompt by pressing Ctrl + B during boot.
From the prompt, run commands similar to those in default.ipxe to troubleshoot boot issues.

For example:

set uri http://10.0.0.1:9873/provision/00:00:00:00:00:00
kernel --name kernel ${uri}?stage=kernel
imgextract --name image ${uri}?stage=image&compress=gz
imgextract --name system ${uri}?stage=system&compress=gz
imgextract --name runtime ${uri}?stage=runtime&compress=gz
boot kernel initrd=image initrd=system initrd=runtime

• uri defines the Warewulf server and identifies the node by MAC address.
• kernel fetches the kernel image.
• imgextract downloads and decompresses the image and overlays that form the node’s root filesystem.
• boot loads the kernel and ramdisks to start the system.

Optional:

To boot into a pre-init shell for debugging, replace the last line with:

boot kernel initrd=image initrd=system initrd=runtime rdinit=/bin/sh

Use rdinit (not init) because Warewulf boots nodes using an initial ramdisk.

References and related articles

Warewulf iPXE Troubleshooting
Node Provisioning Guide
Security and SELinux Configuration