netboot

PXE provisioning management: describe your netboot targets, images and DHCP zones in config, and let netboot render the per-target boot artifacts and arm (or disarm) DHCP for a machine as it enters and leaves the install process.

netboot is a small, hook-driven engine. A YAML config declares targets (host/MAC/IP), images (what to boot), dhcp zones (the network a target lives on) and content repos (where artifacts are fetched/served from). For a given target netboot builds a render context and produces netboot files from Jinja2 or shell-style templates, resolving names by MAC, hostname or IP with sensible fallbacks. Backends and behaviour are extensible through an event-hook system and pluggable DhcpServer handlers.

Install

pip install netboot            # the library
pip install netboot[config]    # ...plus what the `pixie` CLI needs to read a config
# or, from a checkout:
pip install .

Optional extras:

Built on duho (CLI/args/command discovery), pathlib_next (URI-aware paths), yaconfiglib (layered YAML), and Jinja2. IP/MAC/DNS helpers come from netimps, re-exported as netboot.utils.net.

CLI

The command is pixie (PXE is pronounced "pixie"); netboot is the library package it drives.

# Initiate the PXE process for a target (render artifacts + arm DHCP):
pixie initiate my-host

# Complete it (post-boot cleanup, disarm DHCP):
pixie complete my-host

Global options:

A target is looked up by exact id, or by hostname prefix / MAC / IP.

Library

from netboot import Pixie

pixie = Pixie(**config)                  # config: the merged YAML mapping
target = pixie.lookup_target("my-host")
ctx = pixie.make_context(target)         # render context (image + dhcpzone + target)
print(ctx.render("boot.ipxe.j2"))        # render a template against the context
pixie.initialize(target)                 # arm DHCP for the target
pixie.complete(target)                   # cleanup once installed

Extending

• Hooks. Pass hooks=[...] (callables or "module.func" import strings) to Pixie(...). Each hook f(event, netboot, value, kwargs) -> value is called for every PixieEvent and may transform the value flowing through it — used to customise lookup, context construction and the init/complete lifecycle.
• DHCP backends. Subclass netboot.dhcp.DhcpServer; the lowercased class name is the URI scheme it handles (class dnsmasq(DhcpServer) → dnsmasq://...). Import your plugin module via --load-module so it is registered before the config builds the zones.

A complete runnable setup — config, both template engines and a DHCP plugin — is in examples/.

Development

python -m venv .venv/3.14
.venv/3.14/bin/pip install -e ".[dev,docs,config,http]"   # Scripts/ on Windows
.venv/3.14/bin/python -m pytest -q -rs                    # the suite
.venv/3.14/bin/python -m black src tests benchmarks       # formatter
.venv/3.14/bin/python -m mkdocs build --strict            # docs

Install every extra that has tests — without http the repository-service tests skip instead of running, which -rs makes visible. Develop on the latest Python and also run the floor (3.9) before finishing a piece of work. More detail, plus the layout and CI notes, in AGENTS.md.

Releasing

Tags and CHANGELOG.md use SemVer; pyproject.toml uses PEP 440. Pre-1.0 the minor slot is reserved for breaking the documented API — additions and fixes are patches. Pushing a v* tag runs test → build → GitHub release → PyPI and then deploys the docs for that tag; the release body is scraped from the matching ## [x.y.z] changelog section.

License

MIT — see LICENSE.