netboot 0.1.0__tar.gz

netboot-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Agent configs / private notes — never tracked in this repo
+.agents
+*.local.md
+CLAUDE*
+.claude/
+
+# Virtualenvs
+.venv*/
+venv/
+env/
+.env/
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Docs site build output
+/site/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store

netboot-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-21
+
+First packaged release: the `netboot` library with the `pixie` command line.
+
+### Added
+- Packaged as `netboot` (src layout, hatchling, `pixie` console script, `py.typed`).
+  Python 3.9+.
+- PXE provisioning engine: `Pixie` with target/image/dhcpzone/repo lookup, a
+  render `PixieContext`, and an `initialize`/`complete` lifecycle.
+- Event-hook system (`PixieEvent`, `Pixie(hooks=...)`) for customising lookup,
+  context construction and the init/complete lifecycle.
+- Template rendering via a URI-aware Jinja2 loader plus a `%`-delimited shell
+  template engine, selecting sources by MAC / hostname / IP.
+- Pluggable `DhcpServer` backends dispatched by URI scheme, discovered
+  recursively so plugin modules loaded via `--load-module` are honoured.
+- `pixie` CLI built on `duho` (PXE is pronounced "pixie"; `netboot` is the
+  library/import package): `initiate` and `complete` commands with layered YAML
+  config (`config/pixie.yaml` via `yaconfiglib`), command discovery, and
+  `--load-module`/`--cmdspath`.
+- App settings read through `duho.env.Env("pixie")`, so `PIXIE_*` variables
+  (notably `PIXIE_CMDS_PATH`) configure the CLI; the resolved accessor reaches
+  commands as `args._env_`.
+- Config objects use `yaconfiglib`'s `TypedNamespace` (`_parse_<field>` coercers)
+  and `OpaqueMerge` (last-object-wins) so fully-built targets/zones with
+  factory-function field hints are merged as opaque values (requires
+  `yaconfiglib>=0.10.0`).
+- Two-workflow CI (`test`, `Release`) and a MkDocs documentation site
+  (`docs/` + `mkdocs.yml`, API reference via mkdocstrings), plus a
+  `benchmarks/bench_netboot.py` micro-benchmark for the lookup/template hot paths.
+- IP/MAC/DNS helpers vendored in-tree as `netboot._netutils`; DNS lookup of
+  hostname targets is the optional `netboot[dns]` extra (`dnspython`).
+
+### Changed
+- Built on `duho` (args/command-discovery/app) rather than the in-house
+  `coquilib` layer; IP/MAC helpers are vendored in-tree; the `sys.path`
+  `vendor/` shim is gone. Version derives from installed package metadata.
+
+### Fixed
+- Target resolution no longer no-ops when the id is an IP address (`self.ip`
+  self-assignment and a `resolve - True` typo).
+- `utils.flatten` now produces a genuinely flat mapping and no longer raises
+  `TypeError` on nested lists, so shell-template rendering works.
+- `DhcpServer(uri)` raises a clear error for an unknown scheme instead of
+  silently returning an inert base, and zone `dhcpservers` URIs are constructed
+  into backends.
+- `make_context` no longer deletes `globals` off shared image/dhcpzone/target
+  objects, so a second target reusing an image keeps that image's globals.
+- `_template_names` accepts the loader's template `**options`; template names
+  stringify the target IP and skip an unspecified address.
+- Command dispatch introspects each module's `run` signature, so a user command
+  using duho's plain `run(args)` is dispatched via `duho.run_command`.
+- Shell templates render `None` as empty instead of the literal `"None"`;
+  config value construction no longer swallows non-`TypeError` errors; repo
+  `joinpath` keeps `.local` a path so chained joins work.
+
+[Unreleased]: https://github.com/jose-pr/netboot/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/netboot/releases/tag/v0.1.0

netboot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netboot-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: netboot
+Version: 0.1.0
+Summary: PXE provisioning management: render netboot artifacts and drive DHCP for targets
+Project-URL: Homepage, https://github.com/jose-pr/netboot/
+Project-URL: Issues, https://github.com/jose-pr/netboot/issues
+Project-URL: Repository, https://github.com/jose-pr/netboot
+Author: Jose A.
+License: MIT License
+        
+        Copyright (c) 2026 Jose A.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Boot
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: duho>=0.3.0
+Requires-Dist: jinja2
+Requires-Dist: pathlib-next[uri]>=0.8.2
+Requires-Dist: yaconfiglib>=0.10.0
+Provides-Extra: config
+Requires-Dist: pyyaml; extra == 'config'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: dnspython; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dns
+Requires-Dist: dnspython; extra == 'dns'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# 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
+
+```sh
+pip install netboot            # once published
+# or, from a checkout:
+pip install .
+```
+
+Optional extras:
+
+| Extra | Enables |
+| ----- | ------- |
+| `netboot[config]` | YAML config loading for the CLI (`pyyaml`) |
+| `netboot[dns]` | DNS resolution of hostname targets (`dnspython`) |
+| `netboot[docs]`   | Build the documentation site (`mkdocs`) |
+
+Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
+[`pathlib_next`](https://github.com/jose-pr/pathlib_next) (URI-aware paths),
+[`yaconfiglib`](https://github.com/jose-pr/yaconfiglib) (layered YAML), and
+Jinja2. IP/MAC/DNS helpers are vendored in-tree (`netboot._netutils`).
+
+## CLI
+
+The command is `pixie` (PXE is pronounced "pixie"); `netboot` is the library
+package it drives.
+
+```sh
+# 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:
+
+| Option | Purpose |
+| ------ | ------- |
+| `-c, --config PATH` | Explicit config file (yaml/cfg) |
+| `--baseconfig DIR`  | Base config directory to search (default `./config`) |
+| `-l, --load-module M` | Import module(s) before building netboot (config/hook deps) |
+| `--cmdspath PATH` | Extra directories/packages to search for commands |
+
+A target is looked up by exact id, or by hostname prefix / MAC / IP.
+
+## Library
+
+```python
+from netboot import Pixie
+
+netboot = Pixie(**config)                 # config: the merged YAML mapping
+target = netboot.lookup_target("my-host")
+ctx = netboot.make_context(target)       # render context (image + dhcpzone + target)
+print(ctx.render("boot.ipxe.j2"))     # render a template against the context
+netboot.initialize(target)               # arm DHCP for the target
+netboot.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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

netboot-0.1.0/README.md

@@ -0,0 +1,86 @@
+# 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
+
+```sh
+pip install netboot            # once published
+# or, from a checkout:
+pip install .
+```
+
+Optional extras:
+
+| Extra | Enables |
+| ----- | ------- |
+| `netboot[config]` | YAML config loading for the CLI (`pyyaml`) |
+| `netboot[dns]` | DNS resolution of hostname targets (`dnspython`) |
+| `netboot[docs]`   | Build the documentation site (`mkdocs`) |
+
+Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
+[`pathlib_next`](https://github.com/jose-pr/pathlib_next) (URI-aware paths),
+[`yaconfiglib`](https://github.com/jose-pr/yaconfiglib) (layered YAML), and
+Jinja2. IP/MAC/DNS helpers are vendored in-tree (`netboot._netutils`).
+
+## CLI
+
+The command is `pixie` (PXE is pronounced "pixie"); `netboot` is the library
+package it drives.
+
+```sh
+# 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:
+
+| Option | Purpose |
+| ------ | ------- |
+| `-c, --config PATH` | Explicit config file (yaml/cfg) |
+| `--baseconfig DIR`  | Base config directory to search (default `./config`) |
+| `-l, --load-module M` | Import module(s) before building netboot (config/hook deps) |
+| `--cmdspath PATH` | Extra directories/packages to search for commands |
+
+A target is looked up by exact id, or by hostname prefix / MAC / IP.
+
+## Library
+
+```python
+from netboot import Pixie
+
+netboot = Pixie(**config)                 # config: the merged YAML mapping
+target = netboot.lookup_target("my-host")
+ctx = netboot.make_context(target)       # render context (image + dhcpzone + target)
+print(ctx.render("boot.ipxe.j2"))     # render a template against the context
+netboot.initialize(target)               # arm DHCP for the target
+netboot.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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

netboot-0.1.0/benchmarks/bench_netboot.py

@@ -0,0 +1,116 @@
+"""netboot micro-benchmarks: the per-request hot paths.
+
+Measures the two operations netboot runs most often per PXE request:
+
+* ``lookup_target`` — a linear scan over the configured targets matching by
+  hostname prefix / MAC / IP;
+* ``_template_names`` — the candidate template-name list built for every render.
+
+Run:
+
+    python benchmarks/bench_netboot.py --iterations 20000
+    python benchmarks/bench_netboot.py --json-output results/netboot.json
+
+Each metric reports min/median/max ms-per-call over the sample; compare on the
+median (a single average hides run-to-run noise). Local timings are a sanity
+check only — a release perf claim comes from CI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import platform
+import statistics
+import sys
+import timeit
+from datetime import datetime, timezone
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, (REPO_ROOT / "src").as_posix())
+
+import netboot  # noqa: E402
+
+
+def _build_netboot(n_targets: int) -> "netboot.Pixie":
+    targets = {}
+    for i in range(n_targets):
+        targets[f"host{i}"] = {
+            "hostname": f"host{i}",
+            "ip": f"10.0.{i // 256}.{i % 256}",
+            "image": "debian",
+        }
+    return netboot.Pixie(
+        images={"debian": {"template_path": []}},
+        dhcpzones={"lan": {"network": "10.0.0.0/16"}},
+        targets=targets,
+    )
+
+
+def _sample(fn, iterations: int, repeats: int = 7) -> "dict[str, float]":
+    # ms per call, one timing per repeat; report min/median/max across repeats.
+    per_call = [
+        (timeit.timeit(fn, number=iterations) / iterations) * 1000.0
+        for _ in range(repeats)
+    ]
+    return {
+        "min_ms": min(per_call),
+        "median_ms": statistics.median(per_call),
+        "max_ms": max(per_call),
+    }
+
+
+def run_benchmarks(iterations: int, n_targets: int = 500) -> "dict[str, dict]":
+    p = _build_netboot(n_targets)
+    # Worst-case lookup: the last target, forcing a full scan.
+    last = f"host{n_targets - 1}"
+    ctx = p.make_context(p.lookup_target("host0"))
+
+    return {
+        "lookup_target_last": _sample(lambda: p.lookup_target(last), iterations),
+        "template_names": _sample(
+            lambda: ctx._template_names("boot.j2"), iterations
+        ),
+    }
+
+
+def _report(iterations: int, results: "dict[str, dict]") -> dict:
+    return {
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "iterations": iterations,
+        "python": platform.python_version(),
+        "platform": platform.platform(),
+        "netboot_version": netboot.Pixie.VERSION,
+        "metrics": results,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run netboot micro-benchmarks")
+    parser.add_argument("--iterations", type=int, default=20000)
+    parser.add_argument("--targets", type=int, default=500)
+    parser.add_argument(
+        "--json-output",
+        type=pathlib.Path,
+        help="Optional path to write the structured JSON report",
+    )
+    args = parser.parse_args()
+
+    results = run_benchmarks(args.iterations, args.targets)
+    report = _report(args.iterations, results)
+
+    for name, m in results.items():
+        print(
+            f"{name:24s} median={m['median_ms']:.6f} ms  "
+            f"(min={m['min_ms']:.6f} max={m['max_ms']:.6f})"
+        )
+
+    if args.json_output is not None:
+        args.json_output.parent.mkdir(parents=True, exist_ok=True)
+        args.json_output.write_text(json.dumps(report, indent=2), encoding="utf-8")
+        print(f"\nwrote {args.json_output}")
+
+
+if __name__ == "__main__":
+    main()

netboot-0.1.0/docs/api.md

@@ -0,0 +1,28 @@
+# API Reference
+
+The engine and its context objects. Rendered from source via
+[mkdocstrings](https://mkdocstrings.github.io/).
+
+## Engine
+
+::: netboot.Pixie
+
+## Context
+
+::: netboot.PixieContext
+
+## Targets and images
+
+::: netboot.PixieTarget
+
+::: netboot.PixieImage
+
+## Events
+
+::: netboot.PixieEvent
+
+## DHCP
+
+::: netboot.dhcp.DhcpZone
+
+::: netboot.dhcp.DhcpServer

netboot-0.1.0/docs/cli.md

@@ -0,0 +1,68 @@
+# CLI
+
+The `pixie` command line (the CLI of the `netboot` library; PXE is
+pronounced "pixie") is built on [`duho`](https://github.com/jose-pr/duho): it
+discovers commands, layers YAML config, then runs the selected command against a
+single `Pixie` engine built from that config.
+
+```sh
+# 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
+```
+
+A target argument is resolved by exact id, or by hostname prefix / MAC / IP.
+
+## Global options
+
+| Option | Purpose |
+| ------ | ------- |
+| `-c, --config PATH` | Explicit config file (yaml/cfg); overrides discovery |
+| `--baseconfig DIR`  | Base config directory to search (default `./config`) |
+| `-l, --load-module M` | Import module(s) before building netboot (config/hook deps) |
+| `--cmdspath PATH` | Extra directories/packages to search for commands |
+| `-v` / `-q` | Increase / decrease log verbosity (from duho's `LoggingArgs`) |
+
+## Commands
+
+### `initiate <target> [--iscsi]`
+
+Look up the target, build its render context, produce the netboot artifacts and
+arm every DHCP backend in the target's zone. `--iscsi` prepares the target as an
+iSCSI LUN.
+
+### `complete <target>`
+
+Run post-boot cleanup for the target and disarm its DHCP backends.
+
+## Adding your own commands
+
+Point `--cmdspath` (or the `PIXIE_CMDS_PATH` environment variable) at a package or
+directory of command modules. A netboot command module exposes:
+
+```python
+def register(parser, args):      # optional: add argparse arguments
+    ...
+
+def run(netboot, args, conf):       # required: the command body
+    ...
+```
+
+A module that instead follows duho's plain `run(args)` contract is dispatched by
+duho directly, so ordinary duho commands work too.
+
+## Environment
+
+App settings are read through `duho.env.Env("pixie")`, so they live under the
+`PIXIE_` prefix:
+
+- `PIXIE_CMDS_PATH` — extra command sources, `os.pathsep`-separated (see above).
+- A `pixie_env` Python module importable at startup (e.g. a `pixie_env.py` in
+  the working directory) may ship settings as `UPPER_CASE` module variables.
+  Note: as of current duho, these seeded values take precedence over real
+  `PIXIE_*` environment variables.
+
+Commands receive the resolved accessor as `args._env_`, so a custom command can
+read its own `PIXIE_<KEY>` settings without touching `os.environ`.

netboot-0.1.0/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+netboot loads a YAML config (via [`yaconfiglib`](https://github.com/jose-pr/yaconfiglib),
+so `!include` and deep-merge are available). By default it reads `pixie.yaml` from
+`./config`; override with `--config FILE` or `--baseconfig DIR`.
+
+The top-level keys map to the `Pixie` engine's collections:
+
+```yaml
+# Values shared into every render context.
+globals:
+  domain: example.com
+
+# Machines to provision, keyed by an id (hostname / MAC / IP).
+targets:
+  web01:
+    hostname: web01
+    ip: 10.0.0.10
+    image: debian
+  "aa:bb:cc:dd:ee:ff":       # a MAC-keyed target
+    image: debian
+
+# What a target boots. template_path is searched for that image's templates.
+images:
+  debian:
+    template_path: [templates/debian]
+    globals:
+      kernel: vmlinuz
+
+# The network a target lives on, plus its DHCP backend(s).
+dhcpzones:
+  lan:
+    network: 10.0.0.0/24
+    gateway: 10.0.0.1
+    nameservers: [10.0.0.53]
+    search: [example.com]
+    dhcpservers:
+      - dnsmasq://dhcp-host        # scheme selects the DhcpServer backend
+
+# Where boot artifacts are fetched / served from.
+repos:
+  mirror:
+    address: mirror.example.com
+    services:
+      http: http://mirror.example.com/debian
+    local: /srv/mirror/debian
+```
+
+## How values resolve
+
+- **Targets** normalise `ip`/`mac`/`hostname` at load time. If a field is
+  missing, netboot fills it in where it can (a MAC-shaped id becomes the `mac`; an
+  IP-shaped id becomes the `ip`; a hostname is resolved to an IP via DNS).
+- **Zones** derive `network` from a CIDR `gateway`, and coerce `nameservers` /
+  `search` to lists. `dhcpservers` URIs are constructed into backends by scheme.
+- **globals** are layered: engine globals, then per-image / per-zone / per-target
+  `globals`, are merged into the render context (later wins).
+
+## Templates
+
+`templates` is a list of search paths (local or URI). For each render netboot looks
+for a file named by the target's MAC (`aa-bb-cc-...`), hostname, or IP — falling
+back to the bare template name. A `.j2` / `.jinja` / `.jinja2` file is rendered
+with Jinja2; anything else is rendered with the `%`-delimited shell engine, whose
+`%{UPPER_SNAKE}` placeholders come from the flattened context.

netboot-0.1.0/docs/extending.md

@@ -0,0 +1,42 @@
+# Extending
+
+## Event hooks
+
+Pass `hooks=[...]` to `Pixie(...)` — each entry is a callable or a
+`"module.function"` import string. A hook
+
+```python
+def my_hook(event, netboot, value, kwargs):
+    ...
+    return value
+```
+
+is invoked for every `PixieEvent` and may transform the value flowing through it.
+Events fire around object creation (`NewPixieObject`, `SetPixieProperty`,
+`PixieInitiated`), lookup (`LookupTarget`, `FoundTarget`, `FoundTargetImage`,
+`FoundTargetDhcpzone`), context construction (`PixieContextForTarget`), and the
+init/complete lifecycle (`StartPixieInitialize` … `EndPixieComplete`). This is the
+seam for customising how targets/images/zones are resolved and how the render
+context is assembled.
+
+## Custom DHCP backends
+
+`netboot.dhcp.DhcpServer` dispatches on the URI scheme of a zone's `dhcpservers`
+entry: a subclass whose lowercased class name equals the scheme handles it.
+
+```python
+from netboot.dhcp import DhcpServer
+
+class dnsmasq(DhcpServer):        # handles dnsmasq://...
+    def add_target(self, ctx):
+        ...                       # arm DHCP for ctx.target
+    def remove_target(self, ctx):
+        ...                       # disarm it
+```
+
+Subclassing at any depth is honoured, so a backend may share an intermediate
+base. Import your plugin module before the config builds the zones — pass it via
+`--load-module your.plugin` (or list it under the config's module loading) so the
+`DhcpServer` subclass is registered when `dnsmasq://...` is resolved.
+
+An unknown scheme raises a clear `ValueError` rather than silently doing nothing.