Skip to content

Configuring PXE Boot with an External DHCP Server

This guide explains how to configure MOJO's PXE boot infrastructure when using your own DHCP server instead of MOJO's built-in DHCP service.

Overview

MOJO uses a two-stage PXE boot process for OS provisioning:

  1. Initial PXE Boot: The client receives DHCP configuration and downloads an iPXE boot file via TFTP
  2. iPXE Chain-loading: iPXE fetches the boot menu and OS configuration via HTTP from MOJO's pxe-helper service

When using an external DHCP server, you configure your DHCP to point clients to MOJO's TFTP server. MOJO's TFTP and pxe-helper services handle the rest of the boot process.

Prerequisites

Before configuring external DHCP for PXE boot, ensure:

  • MOJO is installed and running
  • You have administrative access to your DHCP server
  • Network connectivity exists between your DHCP server, MOJO server, and PXE clients
  • You know MOJO's IP address on the provisioning network

MOJO Configuration

Enabling Provisioning Services

MOJO's TFTP and pxe-helper services are part of the "provision" profile. To ensure these services start, the MOJO_SINGLE_NETWORK_DHCP_RUN setting must be set to y in your configuration.

Edit /opt/mojo/configs/mojo.env and verify:

MOJO_SINGLE_NETWORK_DHCP_RUN="y"

Why Enable DHCP When Using External?

Setting this to y enables the provision profile, which starts TFTP, pxe-helper, and the iPXE deployer services. While MOJO's DHCP service will also start, your external DHCP server will handle PXE boot requests if configured correctly.

If you need to avoid DHCP conflicts, you can configure MOJO's DHCP range to be minimal or on a different subnet that won't conflict with your external DHCP server.

Verifying Boot Files

After starting MOJO, verify the iPXE boot files are deployed to the TFTP directory:

ls -la /opt/mojo/volumes/tftpd/

You should see the following boot files:

File Purpose
snponly.efi x86_64 UEFI boot (most modern servers)
ipxe_i386.efi x86 32-bit UEFI boot
undionly.kpxe Legacy BIOS boot

If these files are missing, restart MOJO to trigger the iPXE deployer:

cd /opt/mojo
sudo ./mojo-launcher restart mojo

Verifying Services Are Running

Check that the required services are running:

# For Docker
sudo docker ps | grep -E "tftpd|pxe-helper"

# For Podman
sudo podman ps | grep -E "tftpd|pxe-helper"

You should see mojo-tftpd and mojo-pxe-helper containers running.

External DHCP Configuration

Configure your DHCP server with the following PXE options to point clients to MOJO's TFTP server.

Required DHCP Options

Option Name Value
66 next-server / TFTP Server MOJO server IP address
67 bootfile-name / Boot Filename Architecture-specific (see below)

Boot Filenames by Architecture

Different client architectures require different boot files:

Client Architecture DHCP Option 93 Value Boot Filename
x86 BIOS (Legacy) 00:00 undionly.kpxe
x86 32-bit UEFI 00:06 ipxe_i386.efi
x86_64 UEFI 00:07, 00:09 snponly.efi

Simplify for Modern Hardware

If all your servers use UEFI boot (most modern servers), you can simply use snponly.efi as the default boot filename without architecture-specific logic.

ISC DHCP Server Configuration

For ISC DHCP Server (commonly used on Linux), add the following to your dhcpd.conf:

# Define client architecture option
option client-arch code 93 = unsigned integer 16;

# MOJO TFTP server address
next-server 192.168.20.101;  # Replace with your MOJO server IP

# PXE client class with architecture-specific boot files
class "pxeclients" {
    match if substring (option vendor-class-identifier, 0, 9) = "PXEClient";

    if option client-arch = 00:00 {
        # x86 BIOS
        filename "undionly.kpxe";
    } elsif option client-arch = 00:06 {
        # x86 32-bit UEFI
        filename "ipxe_i386.efi";
    } else {
        # x86_64 UEFI (default for modern servers)
        filename "snponly.efi";
    }
}

After making changes, restart your DHCP server:

sudo systemctl restart isc-dhcp-server

Windows Server DHCP Configuration

For Windows Server DHCP:

  1. Open DHCP Manager
  2. Navigate to your scope's Scope Options
  3. Configure the following options:
  4. Option 066 (Boot Server Host Name): Enter MOJO's IP address
  5. Option 067 (Bootfile Name): Enter snponly.efi for UEFI clients

For architecture-specific boot files on Windows Server, you'll need to configure DHCP policies:

  1. Right-click your scope and select Policies > New Policy
  2. Create conditions based on the client's architecture (Vendor Class or User Class)
  3. Assign the appropriate boot filename for each architecture

Cisco IOS DHCP Configuration

For Cisco routers/switches acting as DHCP servers:

ip dhcp pool PXE-POOL
   network 192.168.20.0 255.255.255.0
   default-router 192.168.20.1
   dns-server 192.168.20.1
   next-server 192.168.20.101
   bootfile snponly.efi

pfSense/OPNsense Configuration

For pfSense or OPNsense firewalls:

  1. Navigate to Services > DHCP Server
  2. Select the appropriate interface
  3. Scroll to TFTP section
  4. Set TFTP Server to MOJO's IP address
  5. Scroll to Network Booting section
  6. Enable Network Booting
  7. Set Next Server to MOJO's IP address
  8. Set Default BIOS file name to snponly.efi

How PXE Boot Works with MOJO

Understanding the boot flow helps troubleshoot issues:

Stage 1: DHCP (Your External Server)

Step From To Action
1 PXE Client Your DHCP Server DHCP Request
2 Your DHCP Server PXE Client DHCP Response with IP, next-server (MOJO IP), and boot filename

Stage 2: TFTP and iPXE (MOJO Server)

Step From To Action
3 PXE Client MOJO TFTP (port 69) Download iPXE boot file (e.g., snponly.efi)
4 iPXE MOJO pxe-helper (port 80) HTTP request for boot configuration
5 MOJO pxe-helper iPXE Return boot menu and OS provisioning config
6 PXE Client MOJO Proceed with OS installation

Troubleshooting

Boot Files Not Found

If PXE clients timeout waiting for TFTP:

  1. Verify boot files exist: 

    ls -la /opt/mojo/volumes/tftpd/

  2. Check TFTP container is running: 

    sudo podman ps | grep tftpd

  3. Test TFTP connectivity from another machine: 

    tftp 192.168.20.101 -c get snponly.efi

DHCP Not Providing PXE Options

Verify your DHCP server is sending the correct options:

  1. On a Linux client, use tcpdump to capture DHCP traffic: 

    sudo tcpdump -i eth0 -vvv port 67 or port 68

  2. Look for next-server and file fields in the DHCP response

iPXE Loads But Can't Reach pxe-helper

If iPXE starts but fails to load the boot menu:

  1. Verify pxe-helper is running: 

    sudo podman ps | grep pxe-helper

  2. Test HTTP connectivity to pxe-helper: 

    curl -v http://192.168.20.101/configuration

  3. Check firewall rules allow HTTP (port 80) traffic to MOJO

Network Isolation Considerations

If you have multiple DHCP servers on the same network segment, PXE clients may receive conflicting responses. Consider:

  • Using VLANs to isolate the provisioning network
  • Configuring DHCP relay/helper addresses to route PXE requests to specific servers
  • Ensuring only one DHCP server responds to PXE boot requests on the provisioning network

Support

If you encounter issues configuring PXE boot with an external DHCP server, contact us at support@metify.io.