netboot 0.2.0__tar.gz → 0.2.2__tar.gz

{netboot-0.2.0 → netboot-0.2.2}/CHANGELOG.md

@@ -6,6 +6,102 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-21
+
+netboot moves to netimps 0.3.1 and yaconfiglib 0.13. If a plugin, hook or
+template compares `target.mac` with text, read the `MACAddress` entry below.
+
+### Changed
+- Dependencies move to their new series: `netimps>=0.3.1,<0.4` and
+  `yaconfiglib>=0.13.0,<0.14`. The old ceilings made netboot uninstallable
+  beside either release. netimps 0.3.0 is skipped on purpose: it raised from
+  `resolve()` when no resolver was reachable, which would have failed every
+  command at startup, and 0.3.1 answers `[]` again. netboot uses none of the
+  yaconfiglib APIs 0.13.0 removed.
+- **`MACAddress` no longer equals a `str`** (netimps 0.3.0, re-exported as
+  `netboot.utils.net.MACAddress`). `target.mac == "aa:bb:cc:dd:ee:ff"` is now
+  `False` — in a plugin, a hook or a Jinja template alike. Compare with
+  `MACAddress.try_parse(text) == target.mac`. In exchange a MAC is found in a
+  set or dict whichever spelling built it. netboot's own target lookup already
+  compared parsed MACs and is unaffected. A MAC that mixes separators
+  (`00-11:22-33:44-55`) is now rejected, and `aa.bb.cc.dd.ee.ff` is accepted.
+- `resolve()` keeps trying backends after an empty answer, so a hostname
+  target known only to the hosts file or NSS now gets its IP on Windows and
+  macOS. A name that exists nowhere costs two or three lookups instead of one.
+
+## [0.2.1] - 2026-09-17
+
+netboot ships DHCP backends. Additive: nothing documented changed behaviour,
+and a config that named no `dhcpservers` scheme netboot implements works as
+before.
+
+### Fixed
+- A repository `address` of the form `host:port` no longer sends the whole
+  string to DNS. The port is split off first, so `mirror.example:8080`
+  resolves `mirror.example` — the old lookup could only fail, and did so at
+  different speeds on different machines.
+
+### Added
+- `netboot.dhcp` is a package, and DHCP backends carry **client options**. A
+  `dhcpservers` entry is still a plain URI string; its query string now holds the
+  options the server should give the client (`?router=10.0.0.1`), alongside each
+  backend's own connection settings. `netboot.dhcp.options` models them:
+  `GENERIC_OPTIONS` for the names netboot translates, `option-<n>` for anything
+  else, `raw.<backend>=` for untranslated backend-native text, and
+  `options_builder=my.mod.fn` plus the new `PixieEvent.BuildDhcpOptions` for
+  building them from the context. Merge order, later winning: zone defaults, the
+  connection query, `image.dhcp_options`, `target.dhcp_options`, the callback,
+  the hook.
+- **A dnsmasq backend** (`dnsmasq://`), the first netboot ships. It writes
+  `dhcp-host`/`dhcp-option`/`dhcp-boot` entries through `pathlib_next` paths, so
+  the same configuration serves a local dnsmasq or one reached over `sftp://`
+  (`netboot[ssh]`). `hostsfile`/`optsfile` may be a **directory** (one file per
+  target — preferred, and with `--dhcp-hostsdir`/`--dhcp-optsdir` dnsmasq re-reads
+  them with no signal at all) or a **file**, where netboot edits only its own
+  marked region and never touches a line it did not write. `reload=` runs a
+  command, over ssh when the URI names a host; omitting it is fine for a watched
+  directory and an error for a file, which dnsmasq never re-reads by itself.
+- **A Kea backend** (`kea://`, `keas://` for https). It sends `reservation-add`
+  and `reservation-del` to the control agent, mapping `boot-file-name`,
+  `next-server` and `host-name` onto reservation *fields* and everything else
+  onto `option-data`. The `subnet-id` comes from the zone (`subnet_id:`) or is
+  discovered once by matching the zone's network against `config-get`; when
+  neither works netboot refuses rather than guessing, because a reservation in
+  the wrong subnet silently never matches. A `result: 2` from Kea is reported
+  with the likely cause (host_cmds not loaded, or a read-only hosts backend),
+  and an existing reservation for the same MAC is refused rather than
+  overwritten. Needs `netboot[kea]`.
+- **An ISC dhcpd backend** (`dhcpd://`) over OMAPI, the only way to give dhcpd a
+  reservation without rewriting and reloading its config. Options are rendered
+  into the host's `statements`, which is dhcpd config *source*: text values are
+  quoted with `"` and `\` escaped, a value meant to be an address must look like
+  one, and a newline is refused outright — a value cannot end its statement and
+  start another. The OMAPI secret comes from `keyfile=` or
+  `$PIXIE_DHCPD_OMAPI_KEY`, never from the URI. Needs `netboot[dhcpd]`. Note
+  that a host added over OMAPI does not survive a dhcpd restart by itself: that
+  is dhcpd's design, not netboot forgetting it.
+- **A Windows DHCP Server backend** (`windhcp://`), driving the `DhcpServer`
+  PowerShell module over **ssh** (the default, no dependency — it uses the system
+  `ssh` client, so your config, keys, agent and jump hosts apply) or **WinRM**
+  (`netboot[winrm]`). The transport host and the DHCP server are separate:
+  `server=` becomes `-ComputerName` when the cmdlets should act elsewhere. The
+  scope is the zone's network address, resolved when the target is applied and
+  overridable per zone. No value is interpolated into the script: parameters
+  travel as a JSON payload PowerShell parses, so a target name or option value
+  cannot become a statement.
+- New extras, each carrying exactly one backend's dependency: `netboot[kea]`,
+  `netboot[dhcpd]`, `netboot[winrm]`, and `netboot[ssh]` for dnsmasq over
+  `sftp://`. A local dnsmasq and `windhcp://` over ssh need none. Verified on a
+  clean wheel install: importing `netboot.dhcp` loads no backend dependency,
+  those two backends construct, and the other two raise `ImportError` naming
+  their extra.
+- Anything that varies per target is refused in a connection string and resolved
+  when the target is applied instead: `subnet_id`/`scope` belong to the zone,
+  `boot-file-name`/`next-server`/`tftp-server-name` to the image or target. The
+  error names where each belongs. `from netboot.dhcp import DhcpServer, DhcpZone`
+  is unchanged, and a backend module is imported only when a config names its
+  scheme.
+
 ## [0.2.0] - 2026-09-17
 
 A correctness and hardening release from a full review of the code base.
@@ -447,7 +543,9 @@ First packaged release: the `netboot` library with the `pixie` command line.
   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.2.0...HEAD
+[Unreleased]: https://github.com/jose-pr/netboot/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/jose-pr/netboot/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/jose-pr/netboot/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/jose-pr/netboot/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/jose-pr/netboot/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/jose-pr/netboot/compare/v0.1.1...v0.1.2

{netboot-0.2.0 → netboot-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netboot
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -27,9 +27,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: duho<0.6,>=0.5.0
 Requires-Dist: jinja2<4,>=3.0
-Requires-Dist: netimps<0.3,>=0.2.1
+Requires-Dist: netimps<0.4,>=0.3.1
 Requires-Dist: pathlib-next[uri]<0.10,>=0.9.9
-Requires-Dist: yaconfiglib<0.13,>=0.12.0
+Requires-Dist: yaconfiglib<0.14,>=0.13.0
 Provides-Extra: config
 Requires-Dist: pyyaml; extra == 'config'
 Provides-Extra: dev
@@ -37,11 +37,15 @@ Requires-Dist: black; extra == 'dev'
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: dnspython; extra == 'dev'
 Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pypureomapi; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pywinrm; extra == 'dev'
 Requires-Dist: pyyaml; extra == 'dev'
 Requires-Dist: requests; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dhcpd
+Requires-Dist: pypureomapi; extra == 'dhcpd'
 Provides-Extra: dns
 Requires-Dist: dnspython; extra == 'dns'
 Provides-Extra: docs
@@ -50,6 +54,12 @@ Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
 Provides-Extra: http
 Requires-Dist: requests; extra == 'http'
+Provides-Extra: kea
+Requires-Dist: requests; extra == 'kea'
+Provides-Extra: ssh
+Requires-Dist: pathlib-next[sftp]; extra == 'ssh'
+Provides-Extra: winrm
+Requires-Dist: pywinrm; extra == 'winrm'
 Description-Content-Type: text/markdown
 
 # netboot
@@ -88,6 +98,10 @@ Optional extras:
 | `netboot[config]` | YAML config loading for the CLI (`pyyaml`) |
 | `netboot[dns]` | The `dnspython` resolver backend (best coverage; without it hostname targets still resolve via the system/`nslookup` fallbacks) |
 | `netboot[http]` | `http`/`https` repository services (`requests`); `file`/`tftp` repos and rendering need nothing extra |
+| `netboot[kea]` | The `kea://` DHCP backend (`requests`) |
+| `netboot[dhcpd]` | The `dhcpd://` DHCP backend over OMAPI (`pypureomapi`) |
+| `netboot[winrm]` | `windhcp://` over WinRM (`pywinrm`); over ssh it needs nothing |
+| `netboot[ssh]` | `dnsmasq://` with remote `sftp://` paths (`pathlib_next[sftp]`) |
 | `netboot[docs]`   | Build the documentation site (`mkdocs`) |
 
 Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
@@ -140,10 +154,12 @@ pixie.complete(target)                   # cleanup once installed
   `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.
+- **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/`](https://github.com/jose-pr/netboot/tree/main/examples).

{netboot-0.2.0 → netboot-0.2.2}/README.md

@@ -34,6 +34,10 @@ Optional extras:
 | `netboot[config]` | YAML config loading for the CLI (`pyyaml`) |
 | `netboot[dns]` | The `dnspython` resolver backend (best coverage; without it hostname targets still resolve via the system/`nslookup` fallbacks) |
 | `netboot[http]` | `http`/`https` repository services (`requests`); `file`/`tftp` repos and rendering need nothing extra |
+| `netboot[kea]` | The `kea://` DHCP backend (`requests`) |
+| `netboot[dhcpd]` | The `dhcpd://` DHCP backend over OMAPI (`pypureomapi`) |
+| `netboot[winrm]` | `windhcp://` over WinRM (`pywinrm`); over ssh it needs nothing |
+| `netboot[ssh]` | `dnsmasq://` with remote `sftp://` paths (`pathlib_next[sftp]`) |
 | `netboot[docs]`   | Build the documentation site (`mkdocs`) |
 
 Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
@@ -86,10 +90,12 @@ pixie.complete(target)                   # cleanup once installed
   `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.
+- **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/`](https://github.com/jose-pr/netboot/tree/main/examples).

{netboot-0.2.0 → netboot-0.2.2}/docs/configuration.md

@@ -36,11 +36,9 @@ dhcpzones:
     nameservers: [10.0.0.53]
     search: [example.com]
     dhcpservers:
-      # The scheme selects the DhcpServer backend. netboot ships none, so a
-      # class named `dnsmasq` must be registered first -- see Extending -- and
-      # `--load-module` must import it, or resolving this entry raises
-      # ValueError for the unknown scheme.
-      - dnsmasq://dhcp-host
+      # The scheme selects the backend; the query carries what the server
+      # should tell the client. See "DHCP servers and options" below.
+      - dnsmasq:///?hostsfile=/etc/dnsmasq.d/netboot.d/&router=10.0.0.1
 
 # Where boot artifacts are fetched / served from.
 repos:
@@ -51,6 +49,67 @@ repos:
     local: /srv/mirror/debian
 ```
 
+## DHCP servers and options
+
+Each entry under a zone's `dhcpservers` is a URI. Its **scheme** picks the
+backend; its **query string** carries that backend's connection settings and the
+DHCP options the server should give the client.
+
+| Scheme | Server | How it applies a reservation | Needs |
+| ------ | ------ | ---------------------------- | ----- |
+| `dnsmasq://` | dnsmasq | writes `dhcp-host`/`dhcp-option` files, local or over `sftp://` | nothing locally; `netboot[ssh]` for remote paths |
+| `kea://`, `keas://` | ISC Kea | `reservation-add` / `reservation-del` via the control agent | `netboot[kea]` |
+| `dhcpd://` | ISC dhcpd | an OMAPI host object | `netboot[dhcpd]` |
+| `windhcp://` | Windows DHCP | its own PowerShell cmdlets over ssh or WinRM | nothing over ssh; `netboot[winrm]` for WinRM |
+
+Each has one thing that is easy to get wrong:
+
+- **dnsmasq** re-reads `--dhcp-hostsfile`/`--dhcp-optsfile` only on SIGHUP, and
+  never re-reads its main config — but `--dhcp-hostsdir`/`--dhcp-optsdir` pick up
+  changed files by themselves, which is why a directory needs no `reload=` and a
+  plain file does.
+- **Kea** needs the `host_cmds` hook loaded *and* a writable hosts backend; a
+  file-only Kea loads the hook and still refuses.
+- **dhcpd** hosts added over OMAPI do not survive a restart by themselves — that
+  is dhcpd's design.
+- **Windows** needs the `DhcpServer` module on the host PowerShell runs on, and
+  an account with DHCP-administrator rights.
+
+### Options
+
+Anything in the query that is not a connection setting is a client option:
+`router`, `domain-name-servers`, `domain-name`, `domain-search`, `ntp-servers`,
+`subnet-mask`, `broadcast-address`, `lease-time`, `vendor-class-identifier`, or
+`option-<n>` for anything netboot does not model. Repeat a key for a list.
+`raw.<backend>=` passes backend-native text through untranslated.
+
+Options are merged in this order, later winning:
+
+1. what the zone already knows (`gateway` → `router`, `nameservers`, `domain`…);
+2. the server URI's query;
+3. `images.<id>.dhcp_options`;
+4. `targets.<id>.dhcp_options`;
+5. an `options_builder=my.module.function` — `fn(ctx, options) -> options`;
+6. any hook on `PixieEvent.BuildDhcpOptions`.
+
+**Some things belong to the target, not the connection**, and netboot refuses
+them in a URI with a message saying where they go: `subnet_id` and `scope` on the
+**zone**, `boot-file-name`, `next-server`, `tftp-server-name` and `host-name` on
+the **image** or **target**. A boot file pinned to a connection would hand every
+target on that server the same one.
+
+```yaml
+dhcpzones:
+  lan:
+    network: 10.0.0.0/24
+    subnet_id: 44                      # kea; windhcp uses `scope`
+    dhcpservers:
+      - kea://10.0.0.1:8000/?domain-name-servers=10.0.0.53
+images:
+  debian:
+    dhcp_options: {boot-file-name: pxelinux.0, next-server: 10.0.0.2}
+```
+
 ## Where templates are looked for
 
 `templates` is the list of **template roots** — the CWD's `templates` directory

{netboot-0.2.0 → netboot-0.2.2}/docs/extending.md

@@ -62,6 +62,13 @@ class dnsmasq(DhcpServer):        # handles dnsmasq://...
         ...                       # disarm it
 ```
 
+netboot ships four backends — `netboot.dhcp.dnsmasq`, `.kea`, `.dhcpd` and
+`.windhcp` — and they are the worked examples: one writes files (locally or over
+`sftp://`), one speaks a REST API, one a binary protocol, and one runs
+PowerShell over ssh or WinRM. A backend gets its client options from
+`self.options_for(ctx)` and translates them; see the configuration guide for
+what an operator writes.
+
 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
 `--load-module your.plugin` (repeat or colon-separate for several) so the

{netboot-0.2.0 → netboot-0.2.2}/docs/index.md

@@ -30,6 +30,10 @@ pip install .
 | `netboot[config]` | YAML config loading for the CLI (`pyyaml`) |
 | `netboot[dns]` | The `dnspython` resolver backend (best coverage; without it hostname targets still resolve via the system/`nslookup` fallbacks) |
 | `netboot[http]` | `http`/`https` repository services (`requests`); `file`/`tftp` repos and rendering need nothing extra |
+| `netboot[kea]` | The `kea://` DHCP backend (`requests`) |
+| `netboot[dhcpd]` | The `dhcpd://` DHCP backend over OMAPI (`pypureomapi`) |
+| `netboot[winrm]` | `windhcp://` over WinRM (`pywinrm`); over ssh it needs nothing |
+| `netboot[ssh]` | `dnsmasq://` with remote `sftp://` paths (`pathlib_next[sftp]`) |
 | `netboot[docs]`   | Build this documentation site (`mkdocs`) |
 
 Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),

{netboot-0.2.0 → netboot-0.2.2}/examples/README.md

@@ -48,6 +48,11 @@ Expected output for `initiate web01`: the backend line, then the rendered
   renders it: `%{UPPER_SNAKE}` placeholders from the flattened context, and a
   bare `%` left alone (which is what lets a kickstart's `%packages` through).
   `install.ks.j2` is Jinja, with `ctx`, `shell_quote`, `Path` and `Uri` in scope.
+- **A real DHCP backend.** `config/pixie.yaml` carries a commented
+  `dnsmasq://` entry beside the recording stub: uncomment it (and drop the stub)
+  to write real reservation files. The image's `dhcp_options` — the boot file and
+  its server — reach whichever backend you use, because they belong to the image
+  rather than to the connection.
 - **Repo URLs.** `ctx.repos["mirror"].service("tftp")` builds
   `tftp://10.0.0.2/debian` from the repo's address and service path. An
   `http`/`https` service would additionally need `pip install netboot[http]`.

{netboot-0.2.0 → netboot-0.2.2}/examples/config/pixie.yaml

@@ -17,6 +17,11 @@ images:
     template_path: [debian]        # relative: searched inside the template root
     globals:
       kernel: vmlinuz
+    # What this image tells DHCP clients to boot. Merged into the options every
+    # backend sends; see docs/configuration.md.
+    dhcp_options:
+      boot-file-name: pxelinux.0
+      next-server: 10.0.0.2
 
 dhcpzones:
   lan:
@@ -26,8 +31,13 @@ dhcpzones:
     nameservers: [10.0.0.53]
     search: [example.com]
     dhcpservers:
-      # Handled by examples/plugins/recording.py, imported with --load-module.
+      # Handled by examples/plugins/recording.py, imported with --load-module,
+      # so this example runs with no DHCP server at all.
       - recording://dhcp-host
+      # A real one looks like this -- swap it in when you have a dnsmasq. The
+      # query carries the options the server hands the client; the boot file
+      # comes from the image below, because it varies per target.
+      # - dnsmasq:///?hostsfile=/etc/dnsmasq.d/netboot.d/&router=10.0.0.1
 
 repos:
   mirror:

{netboot-0.2.0 → netboot-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netboot"
-version = "0.2.0"
+version = "0.2.2"
 authors = [{ name = "Jose A." }]
 description = "PXE provisioning management: render netboot artifacts and drive DHCP for targets"
 readme = "README.md"
@@ -30,10 +30,12 @@ classifiers = [
 ]
 dependencies = [
     "duho>=0.5.0,<0.6",
-    # Above the .0 deliberately: netboot calls netimps' resolve() with no
-    # rdtype, and 0.2.1 is the release that auto-selects it ("ptr" for an
-    # address literal, "a" otherwise). Don't normalize this back to 0.2.0.
-    "netimps>=0.2.1,<0.3",
+    # Above the .0 deliberately: 0.3.0 made resolve() raise ResolutionError
+    # when no backend could even ask (a resolver outage), and 0.3.1 restored
+    # [] as the default (strict=False). PixieTarget and Host.try_ip rely on
+    # that: every target is built at startup, so a raise would fail every
+    # command. Don't normalize this back to 0.3.0.
+    "netimps>=0.3.1,<0.4",
     # Above the .0 deliberately, measured 2026-09-17: recursive `!include`
     # globs (`sub/**/*.yaml`) break on pathlib_next >=0.9.5 unless yaconfiglib
     # is >=0.12.0, and yaconfiglib 0.12.0 itself requires pathlib-next>=0.9.9.
@@ -44,9 +46,7 @@ dependencies = [
     # markupsafe.soft_unicode, removed in MarkupSafe 2.1, so an unpinned
     # resolve can install a jinja2/markupsafe pair that fails on import.
     "jinja2>=3.0,<4",
-    # Above a bare series base for the same measured reason: with the
-    # pathlib-next this project uses, recursive config discovery needs 0.12.0.
-    "yaconfiglib>=0.12.0,<0.13",
+    "yaconfiglib>=0.13.0,<0.14",
 ]
 
 [project.optional-dependencies]
@@ -57,13 +57,34 @@ config = ["pyyaml"]
 # pathlib_next[uri] does not. Repos served over file/tftp, and rendering in
 # general, need none of it, so this stays an extra rather than a dependency.
 http = ["requests"]
+# DHCP backends. Each is imported only when a config names its scheme, so a
+# netboot install carries none of these unless it asks for them. dnsmasq needs
+# nothing for a local server, and windhcp nothing over its default ssh
+# transport (it uses the system ssh client).
+kea = ["requests"]                       # kea:// control agent
+dhcpd = ["pypureomapi"]                  # dhcpd:// OMAPI
+winrm = ["pywinrm"]                      # windhcp://...?transport=winrm
+ssh = ["pathlib_next[sftp]"]             # dnsmasq:// over sftp:// paths
 # The dnspython resolver backend for netimps' resolve(), used to look up
 # hostname targets. netimps >=0.2.0 makes dnspython optional, so this extra is
 # the only thing that installs it: with it, resolution has full record-type and
 # explicit-nameserver support; without it, resolve() still works through
 # netimps' system/nslookup backends (address and reverse records only).
 dns = ["dnspython"]
-dev = ["black", "build", "hatchling", "pytest", "pytest-cov", "twine", "pyyaml", "dnspython", "requests"]
+dev = [
+    "black",
+    "build",
+    "hatchling",
+    "pytest",
+    "pytest-cov",
+    "twine",
+    "pyyaml",
+    "dnspython",
+    "requests",
+    # Backend dependencies, so their tests run rather than skip.
+    "pypureomapi",
+    "pywinrm",
+]
 docs = ["mkdocs", "mkdocs-material", "mkdocstrings[python]"]
 
 [project.scripts]

{netboot-0.2.0 → netboot-0.2.2}/src/netboot/AGENTS.md

@@ -98,8 +98,8 @@ is the same object. `netboot.netutils` remains an alias for
 - **`PixieEvent`** (`StrEnum`) — hook event names: `NewPixieObject`,
   `StartPixieInit`, `SetPixieProperty`, `PixieInitiated`, `LookupTarget`,
   `FoundTarget`, `FoundTargetImage`, `FoundTargetDhcpzone`,
-  `PixieContextForTarget`, `StartPixieInitialize`, `EndPixieInitialize`,
-  `StartPixieComplete`, `EndPixieComplete`.
+  `PixieContextForTarget`, `BuildDhcpOptions`, `StartPixieInitialize`,
+  `EndPixieInitialize`, `StartPixieComplete`, `EndPixieComplete`.
 
 - **`PixieTarget(**kwargs)`** (`argparse.Namespace` + `yaconfiglib.OpaqueMerge`)
   — `_id`, `hostname`, `ip` (`IPAddress`), `mac` (`MACAddress`), `image`,
@@ -110,9 +110,10 @@ is the same object. `netboot.netutils` remains an alias for
   non-MAC `_id` fills `hostname`; then, if `ip` is still unset and a hostname
   is known, **exactly one** forward lookup
   (`netboot.utils.net.resolve`, no reverse lookup) fills it. A name that does
-  not resolve leaves `ip` unset and logs a warning — it is never retried, and
-  never raises. `hostname` is lower-cased. The `dns` extra is optional: without
-  it netimps still resolves through its system/`nslookup` backends.
+  not resolve — including when no resolver is reachable at all — leaves `ip`
+  unset and logs a warning; it is never retried, and never raises. `hostname`
+  is lower-cased. The `dns` extra is optional: without it netimps still
+  resolves through its system/`nslookup` backends.
 
 - **`PixieImage(**kwargs)`** (`content.Resource`) — `template_path`,
   `globals`, plus `Resource`'s `src`/`path`, which address the image's
@@ -173,6 +174,12 @@ is the same object. `netboot.netutils` remains an alias for
   skips anything unparseable with a warning, and returns `default` when no
   server lies inside the zone's network.
 
+- **`DhcpServer.SETTINGS`** — the query keys a backend reads as *connection*
+  settings. Every other key in a `dhcpservers` URI query is a **client option**
+  (see `netboot.dhcp.options`), so the two vocabularies must stay disjoint.
+- **`DhcpServer.options_for(ctx) -> DhcpOptions`** — the merged client options
+  for this target on this server.
+
 - **`DhcpZone(**kwargs)`** (`Namespace` + `OpaqueMerge`) — `network`
   (`IPNetwork`), `gateway` (`IPAddress | None`), `domain` (`str | None`),
   `search` (`list[str]`), `nameservers` (`list[IPAddress]`), `globals`,
@@ -182,6 +189,64 @@ is the same object. `netboot.netutils` remains an alias for
   **`.get_local_server(servers, default)`** — first `server` contained in
   `.network`, else `default`.
 
+## DHCP backends (`netboot.dhcp.*`)
+
+Four ship, each imported only when a config names its scheme — so importing
+`netboot.dhcp` pulls in none of their dependencies. Every one takes its client
+options from the URI query (see below) and translates them.
+
+- **`dnsmasq://[host]/?hostsfile=&optsfile=&reload=&pidfile=`**
+  (`netboot.dhcp.dnsmasq`) — writes `dhcp-host`/`dhcp-option`/`dhcp-boot`
+  entries. Paths may carry their own scheme; a bare path is local when the URI
+  has no host and `sftp://<host>/<path>` when it does (`netboot[ssh]`). A
+  **directory** gets one file per target; a **file** gets a marked region netboot
+  owns. `reload=` runs a command, over ssh when the URI names a host — omit it
+  for a `--dhcp-hostsdir`, which dnsmasq re-reads by itself; a plain file
+  without it raises.
+- **`kea://`, `keas://`** (`netboot.dhcp.kea`, `netboot[kea]`) —
+  `reservation-add`/`reservation-del` through the control agent. `?service=`
+  selects `dhcp4`/`dhcp6`. Needs the **host_cmds** hook and a writable hosts
+  backend; `result: 2` is reported with that cause. `subnet-id` comes from the
+  zone (`subnet_id`) or a matched `config-get`.
+- **`dhcpd://host:7911/?keyname=&keyfile=`** (`netboot.dhcp.dhcpd`,
+  `netboot[dhcpd]`) — an OMAPI host object whose `statements` carry the options,
+  escaped. Secret from `keyfile=` or `$PIXIE_DHCPD_OMAPI_KEY`. A host added this
+  way does **not** survive a dhcpd restart by itself.
+- **`windhcp://[user@]host/?transport=ssh|winrm&server=&auth=&port=&ssl=`**
+  (`netboot.dhcp.windhcp`) — the `DhcpServer` PowerShell cmdlets over the system
+  `ssh` client (default, no dependency) or WinRM (`netboot[winrm]`, password
+  from `$PIXIE_WINDHCP_PASSWORD`). `server=` becomes `-ComputerName`. Parameters
+  travel as a JSON payload, never interpolated into the script. The scope is the
+  zone's network address, overridable with `scope` **on the zone**.
+
+Each raises `PixieLookupError` for a target with no MAC — every one of these
+servers identifies a reservation by it.
+
+## DHCP options (`netboot.dhcp.options`)
+
+- **`GENERIC_OPTIONS`** — the option names netboot models and every backend
+  translates (`router`, `domain-name-servers`, `domain-name`, `domain-search`,
+  `next-server`, `boot-file-name`, `tftp-server-name`, `host-name`,
+  `subnet-mask`, `broadcast-address`, `lease-time`, `ntp-servers`,
+  `vendor-class-identifier`). A numeric `option-<n>` or a bare number is always
+  accepted, for anything not modelled.
+- **`APPLY_TIME`** — names that are resolved **when a target is applied**, never
+  from a connection string: `subnet_id`/`scope` belong to the **zone**,
+  `boot-file-name`/`next-server`/`tftp-server-name` to the **image or target**,
+  `host-name` to the target itself. Passing one in a URI query raises
+  `PixieConfigError` naming where it belongs — a boot file pinned to a
+  connection would hand every target on that server the same one.
+- **`DhcpOptions(dict)`** — the merged options, plus **`.raw`** /
+  **`.raw_for(backend)`**: backend-native text from `raw.<backend>=` in the
+  query, never translated.
+- **`build_options(ctx, server) -> DhcpOptions`** — merges, later winning: zone
+  defaults (from `gateway`/`nameservers`/`domain`/`search`/`network`) → the
+  server URI's query → `image.dhcp_options` → `target.dhcp_options` → the
+  server's `options_builder=` callback (`fn(ctx, options) -> options`) → the
+  `PixieEvent.BuildDhcpOptions` hook. An unknown option name raises.
+- **`split_query(uri, settings, backend)`** → `(settings, options, builder)`.
+  A repeated key becomes a list, which is how a multi-valued option is written.
+
 ## Content (`netboot.content`)
 
 - **`Resource(**kwargs)`** — `path` (`Pathname`, coerced via `_parse_path`),
@@ -273,7 +338,8 @@ is the same object. `netboot.netutils` remains an alias for
 - **`Host(address: str | Host | None = None)`** — a hostname-or-IP repo
   address. **`.try_ip() -> IPAddress | str`** — resolves to an `IPAddress`
   (an IP literal as-is, a hostname through one forward lookup); falls back to
-  the original string on resolution failure. The `dns` extra is optional —
+  the original string on resolution failure, an unreachable resolver
+  included. The `dns` extra is optional —
   without it netimps resolves through its system/`nslookup` backends.
   Equality/hash by `.address`.
 - **`flatten(map, _prefix="") -> dict`** — recursively flattens a
@@ -304,13 +370,18 @@ is the same object. `netboot.netutils` remains an alias for
   - `parse(value, type, **kw)` raises on bad input; `try_parse(value, type)`
     returns `None` instead; `is_valid(value, type)` returns a bool. Networks
     parse non-strict, so `"10.0.0.5/24"` normalises rather than raising.
-  - `MACAddress` — colon/hyphen/Cisco-dot/bare text, `int` or `bytes`;
-    `.as_str(sep)`, `.packed`, `.oui`, hashable and ordered.
+  - `MACAddress` — colon/hyphen/per-octet-dot/Cisco-dot/bare text (one
+    separator per address), `int` or `bytes`; `.as_str(sep)`, `.packed`,
+    `.oui`, hashable and ordered. It equals only another `MACAddress`, never a
+    `str` — compare text with `MACAddress.try_parse(text) == mac`.
   - `resolve(query, rdtype=None)` → a list of **native** records (`A`/`AAAA`
     are `IPv4Address`/`IPv6Address`, not strings); `[]` on a genuine lookup
     failure, but a malformed query or unknown record type raises `ValueError`
     rather than looking like "no such record". `rdtype=None` auto-selects:
-    `"ptr"` when `query` is an address literal, `"a"` otherwise.
+    `"ptr"` when `query` is an address literal, `"a"` otherwise. Backends are
+    tried until one answers non-empty, so hosts-file and NSS-only names
+    resolve too. An unreachable resolver also answers `[]`; netimps'
+    `strict=True` raises `netimps.ResolutionError` instead.
   - `ping(dst)` → a `PingResult` that is truthy on success and also carries
     `.rtt_ms`/`.ttl`.
   - `get_interfaces()` / `iter_addresses()` — real adapter enumeration with

{netboot-0.2.0 → netboot-0.2.2}/src/netboot/content/__init__.py

@@ -14,6 +14,20 @@ from ..utils.net import Host
 _HTTP_SCHEMES = ("http", "https")
 
 
+def _split_port(text: str) -> "tuple[str, _ty.Optional[int]]":
+    """Split `host:port`, `[v6]:port` or a bare host into its two parts."""
+    if not text:
+        return "", None
+    if text.startswith("["):  # [2001:db8::1]:8080
+        literal, _, rest = text.partition("]")
+        port = rest.lstrip(":")
+        return literal + "]", int(port) if port.isdigit() else None
+    head, sep, tail = text.rpartition(":")
+    if sep and tail.isdigit() and head and ":" not in head:
+        return head, int(tail)
+    return text, None
+
+
 def _scheme_of(value: object) -> str:
     """The scheme of a configured service URI, or ``""`` for a bare path."""
     text = str(value)
@@ -124,18 +138,18 @@ class Repository(_NS):
     def _service_host(self, scheme: str) -> "tuple[str, _ty.Optional[int]]":
         """The authority for a relative service path: host and optional port.
 
-        TLS is the exception to resolving: a certificate is issued for a name,
-        and a name-based virtual host needs one too, so `https` keeps the
+        The port is split off **before** anything is resolved: an address like
+        `mirror.example:8080` is a host and a port, and asking DNS for the whole
+        string is a lookup that can only fail (slowly, and differently on every
+        machine).
+
+        TLS is the exception to resolving at all: a certificate is issued for a
+        name, and a name-based virtual host needs one too, so `https` keeps the
         address as configured. Other schemes use the resolved IP, because a PXE
         client often has no working DNS when it fetches its boot files.
         """
-        configured = str(self.address)
-        text = (
-            configured
-            if scheme == "https" and configured
-            else str(self.address.try_ip())
-        )
-        if not text:
+        host, port = _split_port(str(self.address))
+        if not host:
             LOGGER.warning(
                 "repository has no address, so %s:// URLs are built without a "
                 "host; give the repo an `address`, or write the service as a "
@@ -143,16 +157,9 @@ class Repository(_NS):
                 scheme,
             )
             return "", None
-        if text.startswith("["):  # [2001:db8::1]:8080
-            literal, _, rest = text.partition("]")
-            port = rest.lstrip(":")
-            return literal + "]", int(port) if port.isdigit() else None
-        head, sep, tail = text.rpartition(":")
-        if sep and tail.isdigit() and head and ":" not in head:
-            # "mirror.example:8080" is a host and a port, not a host whose name
-            # contains a colon (which percent-encoded into `%3A`).
-            return head, int(tail)
-        return text, None
+        if scheme == "https":
+            return host, port
+        return str(Host(host).try_ip()), port
 
     def service(self, name: str):
         """The base URI for a service name, `None` for `.local` when unset.