netboot 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -6,6 +6,79 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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 +520,8 @@ 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.1...HEAD
+[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netboot
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netboot"
-version = "0.2.0"
+version = "0.2.1"
 authors = [{ name = "Jose A." }]
 description = "PXE provisioning management: render netboot artifacts and drive DHCP for targets"
 readme = "README.md"
@@ -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.1}/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`,
@@ -173,6 +173,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 +188,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`),

{netboot-0.2.0 → netboot-0.2.1}/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.

netboot-0.2.0/src/netboot/dhcp.py → netboot-0.2.1/src/netboot/dhcp/__init__.py

@@ -1,17 +1,51 @@
+import importlib as _importlib
 import typing as _ty
 from argparse import Namespace
 
-from .utils import net as netutils
+from ..utils import net as netutils
 from yaconfiglib import OpaqueMerge
 
-from .logging import LOGGER
-from .utils.net import IPAddress, IPInterface, IPNetwork
+from ..logging import LOGGER
+from ..utils.net import IPAddress, IPInterface, IPNetwork
 
 if _ty.TYPE_CHECKING:
-    from . import PixieContext
+    from .. import PixieContext
 
 from urllib.parse import urlparse
 
+from .options import DhcpOptions, build_options, split_query
+
+#: Backends netboot ships, and the extra each needs. Used only to turn "no
+#: backend for scheme" into a message that names the fix.
+_SHIPPED = {
+    "dnsmasq": "netboot[ssh] for remote paths (local needs nothing)",
+    "kea": "netboot[kea]",
+    "dhcpd": "netboot[dhcpd]",
+    "windhcp": "netboot[winrm] for WinRM (ssh needs nothing)",
+}
+
+#: Scheme -> the module that defines it, when they differ (`keas://` is the
+#: same backend as `kea://`, over https).
+_ALIASES = {"keas": "kea"}
+
+
+def _load_backend(scheme: "str|None") -> None:
+    """Import the shipped backend for `scheme`, if there is one.
+
+    Keeps `import netboot.dhcp` free of requests/paramiko/pywinrm: a backend and
+    its dependency are only imported when a config actually names its scheme. A
+    missing *backend module* is not an error (a plugin may provide the scheme),
+    but a backend that fails to import for its own reasons must say so.
+    """
+    if not scheme or not scheme.isidentifier():
+        return
+    module = _ALIASES.get(scheme, scheme)
+    try:
+        _importlib.import_module(f"{__name__}.{module}")
+    except ModuleNotFoundError as exc:
+        if exc.name != f"{__name__}.{module}":
+            raise  # the backend imported, one of *its* imports is missing
+
 
 def _iter_subclasses(cls: type) -> "_ty.Iterator[type]":
     """Yield every subclass of ``cls``, recursively (not just direct children).
@@ -35,10 +69,15 @@ class DhcpServer:
 
     DEFAULT_SCHEME = None
 
+    #: Query keys this backend reads as connection settings. Everything else in
+    #: the query is a client option -- the two sets must stay disjoint.
+    SETTINGS: "frozenset[str]" = frozenset()
+
     def __new__(cls, uri: str):
         if cls is DhcpServer:
             parsed = urlparse(uri)
             scheme = parsed.scheme or cls.DEFAULT_SCHEME
+            _load_backend(scheme)
             handlers = [
                 sub for sub in _iter_subclasses(cls) if sub.__name__.lower() == scheme
             ]
@@ -54,14 +93,27 @@ class DhcpServer:
                 )
             if handlers:
                 return object.__new__(handlers[-1])
+            hint = _SHIPPED.get(scheme)
             raise ValueError(
                 f"No DhcpServer backend registered for scheme {scheme!r} "
-                f"(uri={uri!r}); import a plugin module providing it via --load-module"
+                f"(uri={uri!r}); "
+                + (
+                    f"install {hint}"
+                    if hint
+                    else "import a plugin module providing it via --load-module"
+                )
             )
         return object.__new__(cls)
 
     def __init__(self, uri: str):
         self.uri = uri
+        self.settings, self.options, self.options_builder = split_query(
+            uri, self.SETTINGS, type(self).__name__
+        )
+
+    def options_for(self, ctx) -> DhcpOptions:
+        """The client options for this target on this server, fully merged."""
+        return build_options(ctx, self)
 
     def remove_target(self, netboot: "PixieContext"):
         """Disarm this backend for the target in `netboot` (a `PixieContext`)."""