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:

*.erb and *.epp templates need no extra, but do need ruby or puppet installed: they render through the real program, so an existing template behaves as its author tested it. PIXIE_RUBY / PIXIE_PUPPET name it when it is not on PATH. Jinja2 (.j2) and the %{NAME} shell engine (.shtpl) are built in, and a file no engine claims is copied unchanged.

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. netboot ships four — dnsmasq://, kea://, dhcpd:// and windhcp:// (Windows, over ssh or WinRM) — each imported only when a config names its scheme. Write your own by subclassing netboot.dhcp.DhcpServer: the lowercased class name is the URI scheme it handles, and --load-module registers it before the config builds the zones. What the server should tell the client rides in the URI query; see the configuration guide.

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 (dev carries the template engines' libraries for the same reason; the .erb/.epp tests skip unless ruby/puppet are installed). 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.