FAQ

Common questions and answers about using PxeLab.

Docs: Getting Started | Troubleshooting | Config Reference

---

Installation & Startup

Q: What operating systems does PxeLab support?

A: Windows 10+ / Linux / macOS 12+, on amd64 / arm64. Full requirements see Getting Started: System Requirements.

Q: What dependencies do I need to install?

A: None. PxeLab is a single executable — download and run. Installation steps see Getting Started: Download & Install.

Q: How to run as a system service?

A: On Linux, use systemd:

# Create service file
sudo tee /etc/systemd/system/pxelab.service << 'EOF'
[Unit]
Description=PxeLab PXE Server
After=network.target

[Service]
ExecStart=/usr/local/bin/pxelab
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable --now pxelab

Q: Can't access Web UI after first start?

A: Check the following:

1. Confirm service is running: curl http://localhost:8080/api/v1/services
2. Check port usage: netstat -tlnp | grep 8080
3. Check firewall rules for port 8080
4. Check logs: ./pxelab --log-level debug

---

Network Configuration

Q: How to choose a DHCP mode?

A: Choose based on your network environment:

Scenario	Recommended Mode	Notes
Standalone network, no existing DHCP	server	PxeLab as complete DHCP server
Existing DHCP server	proxy	Overlay PXE functionality
TFTP/HTTP only	off	Disable DHCP, configure clients manually

Q: What's the difference between ProxyDHCP and Full DHCP?

A:

• Full DHCP: PxeLab acts as complete DHCP server, assigns IPs and PXE boot info
• ProxyDHCP: PxeLab only provides PXE boot info, IPs come from existing DHCP server

ProxyDHCP is ideal for environments with existing DHCP servers — no changes to existing DHCP config needed.

Q: How to configure multiple NICs?

A: Each network interface can have an independent DHCP mode (the mode is configured under each interface's subnets):

interfaces:
  - name: eth0
    ip: 192.168.1.1
    auto_start: true
    subnets:
      - cidr: 192.168.1.0/24
        dhcp: server          # server: full DHCP service
        pool: 192.168.1.100-192.168.1.200
  - name: eth1
    ip: 10.0.0.1
    auto_start: true
    subnets:
      - cidr: 10.0.0.0/24
        dhcp: proxy           # proxy: PXE boot info only
  - name: eth2
    ip: 172.16.0.1
    auto_start: true
    subnets:
      - cidr: 172.16.0.0/24
        dhcp: off             # off: DHCP disabled on this subnet

Q: DHCP port 67 is occupied, what to do?

A: Two solutions:

1. Stop the service occupying the port (recommended)
2. Switch to ProxyDHCP mode (port 4011, usually not conflicting) — set the DHCP mode to proxy in the subnet config:

interfaces:
  - name: eth0
    ip: 192.168.1.1
    subnets:
      - cidr: 192.168.1.0/24
        dhcp: proxy           # Uses port 4011, does not occupy 67

---

iPXE & Boot

Q: What is iPXE?

A: iPXE is open-source network boot firmware supporting HTTP, iSCSI, AoE and more. Compared to traditional PXE:

• HTTP boot support (faster, more flexible)
• Script programming (conditionals, variables)
• More architectures and boot methods

PxeLab includes pre-compiled iPXE — no self-compilation needed.

Q: How to customize the boot menu?

A: In Web UI: Settings → Boot Menu → Custom iPXE Script

#!ipxe
dhcp || clear
menu Choose an OS
item ubuntu Ubuntu 22.04
item centos CentOS 9
item local Boot from local disk
choose --timeout 10000 target
goto ${target}

:ubuntu
chain http://192.168.1.10:8080/netboot/ubuntu.ipxe || shell

:centos
chain http://192.168.1.10:8080/netboot/centos.ipxe || shell

:local
sanboot || exit

Q: What is Secure Boot? How to enable it?

A: Secure Boot is a UEFI security mechanism ensuring only signed bootloaders are loaded.

PxeLab supports Secure Boot for x86_64 and ARM64. In Web UI: Settings → Boot Settings → Secure Boot

Q: What boot types are supported?

A:

Type	Description	Typical Use
menu	Built-in boot menu (Profile list)	Default boot entry
direct	Directly load kernel + initrd	Linux installation
chain	Chain-load to another script	Multi-stage boot
wds	Windows WDS deployment	Windows installation
sanboot	iSCSI SAN boot	Diskless workstations
netboot	Enter the OS Install Catalog	Network installation
local	Local disk boot	Default boot entry
custom	Custom iPXE script	Advanced scenarios

---

Hosts & Profiles

Q: What's the relationship between Hosts and Profiles?

A:

• Host: Represents a device on the network, identified by MAC address
• Profile: Boot configuration file defining how a host boots

One host binds to one profile, which determines its boot behavior.

Q: How to batch import hosts?

A: There is no /hosts/import endpoint. Create hosts one by one via the REST API, or use BMC's CSV batch import:

# Create hosts one by one (REST API)
curl -X POST http://localhost:8080/api/v1/hosts \
  -H "Content-Type: application/json" \
  -d '{"name":"server-01","mac":"AA:BB:CC:DD:EE:01","ip":"192.168.1.10"}'

# Batch import BMC info (CSV; raw CSV body or JSON {"csv":"..."})
curl -X POST http://localhost:8080/api/v1/bmc/configs/import \
  -d @bmc.csv

Q: What is Profile script versioning?

A: PxeLab records every modification history of Profile scripts:

• View historical versions
• Compare version differences
• Roll back to any version

Ideal for team collaboration and change auditing.

---

OS Install Catalog

Q: How to add a new Linux distro?

A: Via Web UI: Netboot Catalog → Add Group

1. Upload ISO image to OS Image Management
2. Create a group (e.g., "Ubuntu")
3. Add entries pointing to ISO mount path
4. Configure answer file template (optional)

Q: What are answer file templates for?

A: Answer file templates automate installation without manual interaction:

• Ubuntu/Debian: preseed.cfg
• CentOS/RHEL: kickstart.cfg
• Windows: unattend.xml

PxeLab provides preset templates with variable substitution and customization.

---

Hardware Management

Q: How does WOL work?

A: Wake-on-LAN sends magic packets to wake network devices:

1. Add target host MAC address in Web UI
2. Click wake button
3. PxeLab sends UDP broadcast magic packet
4. Target device powers on

Scheduled wake tasks are also supported.

Q: What BMC/IPMI operations are supported?

A:

Operation	Description
power on	Power on
power off	Power off
power cycle	Restart
power status	Query power status
set boot device	Set the next boot device (PXE / disk / optical, etc.)

CSV batch import for BMC info is supported, ideal for large-scale deployments.

---

Performance & Scaling

Q: How many hosts can PxeLab support?

A: Depends on which kind of "support":

• Managed scale (DHCP leases / online hosts): DHCP is a lightweight protocol — a single core / 512 MB handles hundreds of clients comfortably; CPU/RAM is not the bottleneck in steady state
• Concurrent booting: the real capacity limit — momentary load spikes far above steady state when many clients download boot files/ISOs at once, bounded by network bandwidth, disk I/O, and boot method (TFTP is serial; HTTP/iPXE is an order of magnitude faster). For mass deployment, trigger boots in batches (20–50)

See Performance & Large-Scale Deployment for details.

Q: How to monitor PxeLab status?

A: Three monitoring methods:

1. Web UI Dashboard: Real-time service status, traffic, events
2. Metrics snapshot: GET /api/v1/metrics (JSON format)
3. Logs: Real-time log stream + audit logs

Q: Where is data stored?

A: Defaults to a .pxelab folder in the user's home directory (the same on all platforms — no per-OS path differences):

Platform	Path
Linux	~/.pxelab/
macOS	~/.pxelab/ (i.e. /Users/<username>/.pxelab/)
Windows	~/.pxelab/ (i.e. C:\Users\<username>\.pxelab\)

Customizable via --data-dir flag.

---

Operations

Q: How to upgrade PxeLab?

A:

1. Stop the currently running PxeLab
2. Download the new version binary and replace the old file
3. Data directory ~/.pxelab/ needs no changes — new version auto-migrates
4. Restart

Q: How to backup data?

A: Back up the entire ~/.pxelab/ directory. Core data is in pxelab.db and config.yaml.

Q: Is Docker deployment supported?

A: Not yet, on the roadmap. Currently recommended to run the binary directly.

For client boot failure issues (no IP, interrupted boot), see Troubleshooting.