photoncloud-monorepo/chainfire/baremetal/pxe-server/QUICKSTART.md

PXE Server Quick Start Guide

This is a condensed guide for getting the PXE boot server running quickly.

Prerequisites

• NixOS server
• Root access
• Network connectivity to bare-metal servers

5-Minute Setup

1. Run Setup Script

cd baremetal/pxe-server
sudo ./setup.sh --install --download --validate

2. Configure NixOS

Add to /etc/nixos/configuration.nix:

imports = [ /path/to/baremetal/pxe-server/nixos-module.nix ];

services.centra-pxe-server = {
  enable = true;
  interface = "eth0";               # YOUR NETWORK INTERFACE
  serverAddress = "10.0.100.10";   # YOUR PXE SERVER IP

  dhcp = {
    subnet = "10.0.100.0";         # YOUR SUBNET
    netmask = "255.255.255.0";
    broadcast = "10.0.100.255";
    range = {
      start = "10.0.100.100";      # DHCP RANGE START
      end = "10.0.100.200";        # DHCP RANGE END
    };
    router = "10.0.100.1";         # YOUR GATEWAY
  };
};

3. Deploy

sudo nixos-rebuild switch

4. Verify

sudo ./setup.sh --test

You should see:

• TFTP server running
• HTTP server running
• DHCP server running

5. Boot a Server

1. Configure server BIOS for PXE boot
2. Connect to same network
3. Power on
4. Watch for boot menu

Adding Nodes

Quick Add (No Auto-Selection)

Just boot the server and select profile from menu.

With Auto-Selection

1. Get MAC address from server
2. Edit ipxe/boot.ipxe, add line:

   iseq ${mac} AA:BB:CC:DD:EE:FF && set profile worker && set hostname worker-05 && goto boot ||
   

3. Optionally add to dhcp/dhcpd.conf:

   host worker-05 {
       hardware ethernet AA:BB:CC:DD:EE:FF;
       fixed-address 10.0.100.65;
       option host-name "worker-05";
   }
   

4. Restart DHCP: sudo systemctl restart dhcpd4

Troubleshooting

Server doesn't get IP

sudo tcpdump -i eth0 port 67 or port 68
sudo journalctl -u dhcpd4 -f

Check:

• DHCP server running on correct interface
• Network connectivity
• Firewall allows UDP 67/68

Server gets IP but no bootloader

sudo tcpdump -i eth0 port 69
sudo journalctl -u atftpd -f

Check:

• TFTP server running
• Bootloaders exist: ls /var/lib/tftpboot/
• Firewall allows UDP 69

iPXE loads but can't get boot script

curl http://localhost/boot/ipxe/boot.ipxe
sudo tail -f /var/log/nginx/access.log

Check:

• Nginx running
• boot.ipxe exists: ls /var/lib/pxe-boot/ipxe/
• Firewall allows TCP 80

Boot script loads but can't get kernel

This is expected until T032.S3 (Image Builder) is complete.

Check: ls /var/lib/pxe-boot/nixos/

Should have:

• bzImage
• initrd

These will be generated by the image builder.

Common Commands

# Check all services
sudo systemctl status dhcpd4 atftpd nginx

# View logs
sudo journalctl -u dhcpd4 -u atftpd -u nginx -f

# Test connectivity
curl http://localhost/health
tftp localhost -c get undionly.kpxe /tmp/test.kpxe

# Restart services
sudo systemctl restart dhcpd4 atftpd nginx

# Check firewall
sudo iptables -L -n | grep -E "67|68|69|80"

Boot Profiles

• control-plane: All services (FlareDB, IAM, PlasmaVMC, K8sHost, etc.)
• worker: Compute services (K8sHost, PlasmaVMC, ChainFire)
• all-in-one: Everything on one node (testing/homelab)

Next Steps

• Add more nodes (see "Adding Nodes" above)
• Wait for T032.S3 to generate NixOS boot images
• Configure monitoring for boot activity
• Set up DHCP relay for multi-segment networks

Full Documentation

See README.md for complete documentation.