PxeOS

Cross-OS PXE boot provisioning system supporting Linux, BSD, and Windows.

Overview

PxeOS is a PXE provisioning tool with a plugin architecture that supports automated installation across 10 OS families. Define a profile once, PxeOS renders the correct native autoinstall format for the target OS.

Foundation layer: PxeOS builds on TftpOS for host matching, provisioning state, and path resolution. See docs/CONTRACT.md for the composition boundary.

Works standalone for bare-metal provisioning, or as a composable service that VirtOS can call for VM provisioning.

Project Status

Version 0.2.0 — Alpha. PxeOS has extensive unit tests but has not yet been validated with real PXE-booting hardware. Treat every feature claim as "generates plausible output" until end-to-end proof exists.

See:

• Deployment Guide — Installation, systemd, firewall, TLS, HA
• Known Limitations — Honest assessment of gaps
• Comparison with Other Tools — Cobbler, Foreman, MAAS, Ironic
• TftpOS ↔ PxeOS Contract — Foundation vs decorator boundary

Alpha Status & Known Limitations

PxeOS is alpha software (Development Status :: 3 - Alpha). It has never been used to PXE-boot a real machine, physical or virtual.

No real-world PXE boot validation

This is the single largest gap. Unit tests validate that PxeOS produces correct-looking output. None of them verify that the output actually boots and installs an OS. Specifically:

• No generated Kickstart file has been consumed by Anaconda.
• No generated Preseed file has been consumed by debian-installer.
• No generated Unattend.xml file has been consumed by Windows Setup.
• No generated bsdinstall config has been consumed by FreeBSD's installer.
• No iPXE boot script has been loaded by actual iPXE firmware.
• TFTP delivery has never been proven end-to-end (see TftpOS issue #5 and PxeOS #62).

Tracked as #59 and #62.

Hardware testing coverage

Zero. No servers, desktops, Raspberry Pis, or even QEMU/KVM end-to-end installs have been completed and recorded.

OS family maturity levels

OS Family	Template Coverage	Real Installer Testing	Honest Assessment
Fedora/RHEL (Kickstart)	76%	None	Most likely to work — Kickstart is well-documented
Debian (Preseed)	Good	None	Likely for basic installs
Ubuntu (Autoinstall)	70%	None	Format changes between 22.04/24.04
SUSE (AutoYaST)	63%	None	SLES vs openSUSE gaps
Arch (archinstall)	Good	None	Rolling release drift risk
FreeBSD (bsdinstall)	72%	None	Unvalidated
OpenBSD (autoinstall)	76%	None	Simple format
NetBSD (sysinst)	69%	None	Least mature upstream
DragonFly BSD	98%	None	High coverage, no real users
Windows	64%	None	Least mature. No driver injection, WinPE, or schema validation

Windows/BSD honesty tracked as #63.

Bottom line

Suitable for experimentation and development. Not ready for production. Prefer Cobbler, Foreman, or MAAS for production today.

Supported OS Families

OS Family	Autoinstall Mechanism	Config File
Fedora / RHEL / CentOS	Kickstart	ks.cfg
Debian	Preseed	preseed.cfg
Ubuntu (22.04+)	Cloud-Init Autoinstall	user-data
SUSE / openSUSE	AutoYaST	autoinst.xml
FreeBSD	bsdinstall	installerconfig
OpenBSD	autoinstall(8)	install.conf
NetBSD	sysinst	auto_install.cfg
Arch Linux	archinstall	user_configuration.json
Windows	Unattended Install	unattend.xml

Quick Start

pip install pxeos

# Import using mnemonics
pxeos import --iso Fedora-42-x86_64.iso --distro fedora42

# Start the server
pxeos server start --config /etc/pxeos/pxeos.toml

# Register a host
pxeos host add --mac aa:bb:cc:dd:ee:f1 --profile webserver --os fedora --vendor fedora --version 42

pxeos profile list

Architecture

CLI / REST API (PxeOS)
         │
    PXE-specific layer (iPXE scripts, autoinstall templates, web UI)
         │
    ┌────┴────┐
    │ TftpOS  │  ← foundation: host matching, state, path resolution
    └────┬────┘
         │
    OS Plugins (PxeOS entry points)
    fedora │ debian │ ubuntu │ suse │ freebsd │ openbsd │ netbsd │ arch │ windows
         │
    Jinja2 Templates → OS-native configs

See docs/CONTRACT.md for what each layer owns.

Vendor / OS Family Taxonomy

os_family = autoinstall mechanism (kickstart, preseed, …).
vendor = derivative (fedora vs rhel vs rocky, all os_family = "fedora").

Host Matching

Priority chain (implemented in TftpOS, consumed by PxeOS):

MAC → MAC prefix → hostname glob → subnet → serial → group → arch → default

PXE Boot Flow

1. Machine PXE boots; DHCP points to iPXE
2. iPXE fetches GET /api/v1/boot/{mac}
3. PxeOS (via TftpOS matching) returns iPXE script with kernel/initrd
4. Installer fetches GET /api/v1/autoinstall/{mac}
5. Post-install calls POST /api/v1/provision/{mac}/disable-netboot (boot-once)

Boot-Once Provisioning

pxeos host disable-netboot aa:bb:cc:dd:ee:f1
pxeos host enable-netboot aa:bb:cc:dd:ee:f1

Distro Mnemonics

pxeos distro aliases
pxeos distro resolve rhel9

Built-ins include fedora42, rhel9, rocky9, deb12, ubuntu2404, fbsd14, win11, etc.

Cloud-Init, Web UI, REST API

See previous sections in history or the full docs. Core endpoints remain:

Method	Endpoint	Description
GET	/api/v1/boot/{mac}	iPXE boot script
GET	/api/v1/autoinstall/{mac}	Rendered autoinstall
POST	/api/v1/provision/{mac}/disable-netboot	Boot-once
GET	/api/v1/health	Health check

Development

pip install -e ".[dev]"
pytest
ruff check pxeos/
mypy pxeos/

Versioning

• 0.x while alpha and while real PXE validation is missing.
• 1.0 only after TftpOS ≥ 1.0 and at least one proven end-to-end PXE install.

License

GNU General Public License v3.0 — see LICENSE.