Locolomo

White Fox PXE Boot Server: Deployment and Management Manual

March 18, 2026

White Fox PXE Boot Server: Deployment and Management Manual

Scope and Prerequisites

This manual provides detailed instructions for deploying and managing the White Fox PXE (Preboot eXecution Environment) boot server. White Fox is an open-source, lightweight solution designed for automated, network-based provisioning of bare-metal servers and workstations, primarily within Linux-centric infrastructure. Its core value proposition lies in reducing hardware provisioning time from hours to minutes, eliminating manual media handling, and enabling consistent, repeatable deployments—key factors in improving operational efficiency and reducing total cost of ownership (TCO) for data center and lab environments.

Applicability: This guide is intended for system administrators, DevOps engineers, and IT infrastructure teams responsible for server lifecycle management. The primary use cases include automated OS installation (e.g., CentOS, Ubuntu), diskless booting for compute clusters, and large-scale system recovery scenarios.

Prerequisites:

  • A dedicated server running a supported Linux distribution (e.g., CentOS 8+, Ubuntu 20.04 LTS).
  • Root or sudo privileges on the server.
  • A static IP address configured on the server's network interface.
  • Access to the network's DHCP configuration (or administrative rights to configure DHCP scope options).
  • Sufficient disk space for OS images and tftp files (minimum 20GB recommended).
  • Basic familiarity with Linux command line, networking concepts (TFTP, HTTP, DHCP), and firewall management (firewalld or iptables).

Procedure

  1. System Preparation and White Fox Installation

    Update your system packages and install core dependencies. White Fox relies on several standard services.

    # For RHEL/CentOS/Rocky Linux
sudo dnf update -y
sudo dnf install -y tftp-server dhcp-server httpd syslinux-tftpboot wget

# For Ubuntu/Debian
sudo apt update && sudo apt upgrade -y
sudo apt install -y tftpd-hpa isc-dhcp-server apache2 wget syslinux-common

    Download and install the White Fox core package. It is typically distributed as a tarball or via a community repository.

    wget https://community.example.com/whitefox/releases/whitefox-2.1.0.tar.gz
tar -xzvf whitefox-2.1.0.tar.gz
cd whitefox-2.1.0
sudo ./install.sh

    Expected Result: The installation script configures directories (`/var/lib/tftpboot/`, `/srv/whitefox/`) and installs necessary bootloaders and menus. A success message confirms completion.

  2. Network Service Configuration

    Configure the DHCP server to point clients to the White Fox TFTP server. Edit the DHCP configuration file (`/etc/dhcp/dhcpd.conf` on RHEL, `/etc/dhcp/dhcpd.conf` on Ubuntu).

    # Example DHCP subnet declaration
subnet 192.168.1.0 netmask 255.255.255.0 {
    range 192.168.1.100 192.168.1.200;
    option routers 192.168.1.1;
    option subnet-mask 255.255.255.0;
    option domain-name-servers 8.8.8.8;
    # Critical PXE directives
    next-server 192.168.1.10;  # IP of your White Fox server
    filename "pxelinux.0";     # Bootloader file provided by White Fox
}

    Configure the firewall to allow PXE-related services.

    # Using firewalld (RHEL/CentOS)
sudo firewall-cmd --permanent --add-service={tftp,http,dhcp}
sudo firewall-cmd --reload

# Using ufw (Ubuntu)
sudo ufw allow 69/udp   # TFTP
sudo ufw allow 80/tcp   # HTTP (for Kickstart/Preseed files)
sudo ufw allow 67/udp   # DHCP
sudo ufw reload

    Start and enable all required services.

    sudo systemctl enable --now dhcpd tftp httpd
sudo systemctl enable --now whitefox-manager  # If a management service exists
  3. Adding Operating System Images

    White Fox uses a structured directory to hold OS images and associated configuration files. Place your OS ISO images in the designated directory, typically `/srv/whitefox/isos/`. You must then extract the kernel (`vmlinuz`) and initial ramdisk (`initrd.img`) files.

    # Mount the ISO and copy necessary files
sudo mount -o loop /path/to/ubuntu-22.04.3-live-server-amd64.iso /mnt
sudo mkdir -p /srv/whitefox/images/ubuntu2204
sudo cp /mnt/casper/vmlinuz /srv/whitefox/images/ubuntu2204/
sudo cp /mnt/casper/initrd /srv/whitefox/images/ubuntu2204/
sudo umount /mnt

    Next, configure a PXE menu entry. Edit the White Fox main menu file, often located at `/var/lib/tftpboot/pxelinux.cfg/default`.

    # Example menu entry for Ubuntu 22.04
LABEL ubuntu2204-auto
    MENU LABEL ^Ubuntu 22.04 Automated Install
    KERNEL images/ubuntu2204/vmlinuz
    APPEND initrd=images/ubuntu2204/initrd ip=dhcp url=http://192.168.1.10/ks/ubuntu2204.ks quiet

    Create the referenced Kickstart (`ubuntu2204.ks`) or Preseed file and place it in your web server's document root (`/var/www/html/ks/`).

  4. Client Boot and Validation

    Configure a target client machine to boot from the network (PXE). Upon startup, the client should receive an IP address from your DHCP server, download the `pxelinux.0` bootloader via TFTP, and present the White Fox boot menu.

    Expected Result: The client displays a textual or graphical menu with the options you configured (e.g., "Ubuntu 22.04 Automated Install"). Selecting an option begins the network-based installation process without local media.

Troubleshooting

Issue 1: Client fails to receive PXE boot menu, shows "PXE-E53: No boot filename received" or similar.

  • Cause: Incorrect DHCP configuration. The `next-server` or `filename` option is missing or wrong.
  • Resolution: Verify the DHCP configuration file syntax. Ensure the `next-server` IP matches the White Fox server's IP. Confirm the `filename` points to "pxelinux.0" and the file exists in `/var/lib/tftpboot/`. Restart the `dhcpd` service. Use `tcpdump` to monitor DHCP traffic: sudo tcpdump -i eth0 -n port 67 or port 68.

Issue 2: Client loads menu but fails to download kernel or initrd, resulting in TFTP timeout errors.

  • Cause: Firewall blocking TFTP (UDP port 69), incorrect file paths in the PXE menu, or TFTP server not running.
  • Resolution: Verify the TFTP service is running: sudo systemctl status tftp. Check that the paths in the `KERNEL` and `APPEND` directives are correct relative to `/var/lib/tftpboot/`. Ensure firewall rules for TFTP are active. Check TFTP server logs (`/var/log/messages` or `journalctl -u tftp`).

Issue 3: Automated installation starts but fails to fetch the Kickstart/Preseed file from the web server.

  • Cause: Incorrect URL in the `APPEND` line, HTTP server not running, or file permissions blocking access.
  • Resolution: Verify the URL is accessible from a client on the same network: curl http://192.168.1.10/ks/ubuntu2204.ks. Ensure the `httpd` service is running and the configuration file is present in the web root with appropriate read permissions (e.g., 644).

Issue 4: Performance is slow during file transfer (TFTP stage).

  • Cause: TFTP protocol is inherently slow; network congestion or server disk I/O bottlenecks.
  • Resolution: Consider using a faster network (1 Gbps+). For very large deployments, investigate alternative PXE stack options or ensure the White Fox server uses performant storage (SSDs). This is a known trade-off of the standard PXE/TFTP process.

White FoxtechnologyLinuxopen-source