netboot 0.3.0__tar.gz → 0.3.1__tar.gz

{netboot-0.3.0 → netboot-0.3.1}/CHANGELOG.md

@@ -4,6 +4,46 @@ 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).
 
+## [0.3.1] - 2026-10-02
+
+### Fixed
+- **`windhcp://` could not set a multi-valued option** (two name servers, two NTP
+  servers) with its default PowerShell method, and the failure took the rest of
+  the reservation with it. The value was sent comma-joined, and
+  `Set-DhcpServerv4OptionValue -Value` takes `String[]`: Windows answered
+  "Parameters for option value to be set for option ID 6 do not match with option
+  definition" and, under `ErrorActionPreference = 'Stop'`, every option after it
+  was abandoned — so the target got a router and **no boot file**. Values are now
+  sent as a list. Present since the backend shipped in 0.2.0; found by running it
+  against a real Windows Server 2025 DHCP server rather than reading the script.
+
+### Added
+- **`DhcpServer.extras(ctx, phase)`** — one documented extension point for
+  backend-native fragments netboot does not model: an extra statement, an extra
+  command, or a condition such as the iPXE chainload (serve the iPXE binary to a
+  PXE ROM, the script to iPXE). It defaults to the configured `raw.<backend>`
+  fragments, and a subclass overrides it to decide per target. All four shipped
+  backends consume it, and `raw.<backend>.remove=` is new: a fragment that
+  belongs to teardown rather than to arming. For `windhcp://` a fragment may be a
+  PowerShell line or a `{"Args": [...], "Ignore": bool}` netsh command, which
+  works under either `method`.
+- `method=netsh` **verifies what the server actually applied**. netsh exits 0 and
+  prints its success line even when it rejected what it was told — measured: a
+  `domain-name-servers` option with one unreachable address keeps the other, says
+  "not a valid DNS Server", says "Command completed successfully", exits 0. So
+  after applying, netboot reads the state back with `netsh ... dump` (the one
+  netsh output that is command syntax rather than localised prose) and fails
+  naming any option that is missing or short of values. The cmdlet method needs
+  none of this: Windows raises there by itself.
+- `windhcp://` takes **`method=powershell|netsh`**. The default is unchanged (the
+  `DhcpServer` cmdlets); `method=netsh` drives `netsh dhcp server ...` instead,
+  for a host where that PowerShell module is not installed. It is independent of
+  `transport=`, and netsh is invoked from PowerShell with each argument an array
+  element, so no value is spliced into a command line. Success is `$LASTEXITCODE`
+  rather than netsh's localised success line, a removal tolerates a reservation
+  that is not there, option data types are declared per option (unmapped ones as
+  `STRING`), and a multi-valued option becomes one argument per value.
+
 ## [0.3.0] - 2026-10-02
 
 ### Changed
@@ -631,7 +671,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.3.0...HEAD
+[Unreleased]: https://github.com/jose-pr/netboot/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/jose-pr/netboot/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/jose-pr/netboot/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/jose-pr/netboot/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/jose-pr/netboot/compare/v0.2.2...v0.2.3

{netboot-0.3.0 → netboot-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netboot
-Version: 0.3.0
+Version: 0.3.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

{netboot-0.3.0 → netboot-0.3.1}/docs/configuration.md

@@ -60,7 +60,7 @@ DHCP options the server should give the client.
 | `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 |
+| `windhcp://` | Windows DHCP | its PowerShell cmdlets *or* `netsh`, over ssh or WinRM | nothing over ssh; `netboot[winrm]` for WinRM |
 
 Each has one thing that is easy to get wrong:
 
@@ -72,8 +72,35 @@ Each has one thing that is easy to get wrong:
   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.
+- **Windows** validates some option values as it stores them, whichever method
+  you use: a name server that does not answer is refused rather than stored. An
+  arm that fails part-way leaves the reservation with the options applied so far
+  — the next successful arm fixes it, and `pixie complete` removes it.
+- **Windows** needs an account with DHCP-administrator rights, and — for the
+  default `method=powershell` — the `DhcpServer` module on the host the shell runs
+  on. Where that module is missing (Server Core without the RSAT feature, or an
+  older release) `method=netsh` drives `netsh dhcp server ...` instead. The two
+  choices are independent: `transport=` is how netboot gets a shell (`ssh` or
+  `winrm`), `method=` is what it runs there.
+
+  netsh is still invoked *from* PowerShell, with each argument an element of a
+  JSON array — so no value is ever spliced into a command line, which is the same
+  guarantee the cmdlet path gives. Extra commands (a policy, say) go through
+  `raw.windhcp=` or a subclass's `extras()`; see
+  [Extra commands and conditions](extending.md#extra-commands-and-conditions),
+  which is also where the iPXE chainload recipe lives.
+
+  **netsh cannot be trusted to report failure.** Given an option value it dislikes
+  — a name server that does not answer — it keeps the rest, prints "not a valid DNS
+  Server", prints "Command completed successfully" and exits 0 (measured on
+  Windows Server 2025). So netboot reads the state back afterwards with
+  `netsh ... dump`, the one netsh output that is command syntax rather than
+  localised prose, and fails naming any option that did not land or lost values.
+  The cmdlet method needs no such check: Windows raises there by itself. A few behaviours are
+  netsh's own rather than netboot's: an option's data type has to be declared
+  (netboot maps the modelled options, and sends anything else as `STRING`), a
+  multi-valued option is passed as one argument per value, and the reservation is
+  created as `BOTH` (DHCP and BOOTP) to match what the cmdlets do by default.
 
 ### Options
 

{netboot-0.3.0 → netboot-0.3.1}/docs/extending.md

@@ -148,3 +148,68 @@ base. Import your plugin module before the config builds the zones — pass
 `DhcpServer` subclass is registered when `dnsmasq://...` is resolved.
 
 An unknown scheme raises a clear `ValueError` rather than silently doing nothing.
+
+### Extra commands and conditions
+
+netboot models the options it can translate everywhere, and `extras()` is the way
+in for everything else — an extra statement, an extra command, or a condition
+that makes the server answer two kinds of client differently. The canonical case
+is the **iPXE chainload**: hand a PXE ROM the iPXE binary, then hand iPXE itself
+the script, or iPXE loads iPXE forever.
+
+Two ways in, both ending up in the same list:
+
+```yaml
+dhcpservers:
+  # from config, per connection
+  - dhcpd://key@dhcp01/?raw.dhcpd=if exists user-class and option user-class = "iPXE" { filename "boot.ipxe"; } else { filename "undionly.kpxe"; }
+```
+
+```python
+# from code, which is the one that can look at the target
+from netboot.dhcp.dhcpd import dhcpd
+
+class dhcpd(dhcpd):                      # still handles dhcpd://
+    def extras(self, ctx, phase="add"):
+        lines = super().extras(ctx, phase)   # keep the config's own fragments
+        if phase == "add" and ctx.image.globals.get("ipxe"):
+            lines.append(
+                'if exists user-class and option user-class = "iPXE" '
+                '{ filename "boot.ipxe"; } else { filename "undionly.kpxe"; }'
+            )
+        return lines
+```
+
+`phase` is `add` or `remove`. A bare `raw.<backend>=` belongs to `add`;
+`raw.<backend>.remove=` is for a fragment that undoes something at teardown (a
+policy created while arming, say). What a fragment *is* belongs to the backend:
+
+| Backend | A fragment is | Where it lands |
+| ------- | ------------- | -------------- |
+| `dhcpd://` | dhcpd config **statements** | appended to the host object's `statements`, after the modelled options — so a conditional written there wins |
+| `dnsmasq://` | config **lines** (`dhcp-match=set:ipxe,77,iPXE`, `dhcp-boot=tag:ipxe,boot.ipxe`) | the options file for that target's tag |
+| `kea://` | an **`option-data` entry** | the reservation's `option-data` |
+| `windhcp://` | a **PowerShell line**, or a `{"Args": [...], "Ignore": false}` **netsh command** | after the reservation and its options |
+
+A netsh command works under either windhcp `method`: with `method=netsh` it joins
+the command list, and with `method=powershell` it becomes the `netsh` call it
+describes rather than being dropped. `Args` may be a list, or one string that is
+split on whitespace — a query string has nowhere to put a list. `Ignore` marks a
+command whose failure is acceptable, which is what a teardown usually wants.
+
+Fragments are emitted **verbatim**: netboot does not parse, validate or escape
+them. That is the point of an escape hatch, and its risk — a value that ends a
+dhcpd statement early, or a PowerShell line that does more than it looks like,
+is yours to get right. Where netboot builds the text itself (a netsh command
+under `method=powershell`) it quotes it properly.
+
+Order is defined: modelled options first, then `extras()`, in the order given
+(unsuffixed `raw.<backend>` before `raw.<backend>.add`). A condition that
+overrides an option therefore comes after the thing it overrides, which is what
+both dhcpd's last-write-wins statements and a Windows policy need.
+
+A declarative, cross-backend way to say "serve this file to iPXE and that one to
+a PXE ROM" is not here yet, because the backends disagree about where a condition
+lives — dhcpd puts it on the host, Windows in a scope-level policy, dnsmasq in a
+tag, Kea in a client class. `extras()` is what makes it expressible today.
+

{netboot-0.3.0 → netboot-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netboot"
-version = "0.3.0"
+version = "0.3.1"
 authors = [{ name = "Jose A." }]
 description = "PXE provisioning management: render netboot artifacts and drive DHCP for targets"
 readme = "README.md"

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/AGENTS.md

@@ -212,16 +212,45 @@ options from the URI query (see below) and translates them.
   `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**.
+- **`windhcp://[user@]host/?transport=ssh|winrm&method=powershell|netsh&server=&auth=&port=&ssl=`**
+  (`netboot.dhcp.windhcp`) — Windows DHCP over the system `ssh` client (default,
+  no dependency) or WinRM (`netboot[winrm]`, password from
+  `$PIXIE_WINDHCP_PASSWORD`). **`transport=` is how we get a shell, `method=` is
+  what runs there**: `powershell` (default) for the `DhcpServer` module's
+  cmdlets, `netsh` for `netsh dhcp server ...` on a host without that module.
+  `server=` becomes `-ComputerName`, or netsh's `\\server` (already-`\\`-prefixed
+  is left alone). An option's value is always a **list** in the payload, because
+  `Set-DhcpServerv4OptionValue -Value` takes `String[]` and refuses a joined
+  `"a,b"`; netsh takes one argument per value. Under `method=netsh` the script
+  **reads the state back** (`netsh ... dump`) and fails naming any option that is
+  missing or short of values, because netsh exits 0 and claims success after
+  silently dropping a value it dislikes. Parameters travel as a JSON payload, never interpolated into
+  the script — including under `netsh`, which is invoked as
+  `& netsh @($c.Args)` so every argument stays an array element. netsh is judged
+  by `$LASTEXITCODE`, not its localised success line; a `delete` carries
+  `Ignore` so cleanup can re-run; option data types come from `_OPTION_TYPES`
+  (unlisted → `STRING`), a multi-valued option becomes one argument per value
+  (the cmdlets take it comma-joined instead), and a reservation is added as
+  `BOTH`. 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.
 
+- **`DhcpServer.extras(ctx, phase="add") -> list`** — the extension point for
+  anything netboot does not model: an extra statement, an extra command, or a
+  condition (the iPXE chainload is the usual one). The default returns the
+  configured `raw.<backend>` fragments for that phase; a subclass overrides it to
+  decide **per target**, and should call `super()` to keep the config's own. The
+  fragment shape is the backend's: dhcpd statements, dnsmasq config lines, a kea
+  `option-data` entry, or — for windhcp — a PowerShell line or a
+  `{"Args": [...], "Ignore": bool}` netsh command, which is rendered as a quoted
+  `netsh` call when the method is `powershell` rather than dropped. `phase` is
+  `add` or `remove` (**`PHASES`**); a bare `raw.<backend>` is `add`,
+  `raw.<backend>.remove` is teardown. Fragments are emitted **verbatim** — no
+  parsing, validation or escaping — and always **after** the modelled options,
+  so a conditional overrides them.
+
 ## DHCP options (`netboot.dhcp.options`)
 
 - **`GENERIC_OPTIONS`** — the option names netboot models and every backend

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/dhcp/__init__.py

@@ -13,7 +13,7 @@ if _ty.TYPE_CHECKING:
 
 from urllib.parse import urlparse
 
-from .options import DhcpOptions, build_options, split_query
+from .options import PHASES, 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.
@@ -115,6 +115,45 @@ class DhcpServer:
         """The client options for this target on this server, fully merged."""
         return build_options(ctx, self)
 
+    def extras(self, ctx, phase: str = "add") -> "list":
+        """Backend-native fragments to apply along with the reservation.
+
+        This is the extension point for anything netboot does not model: an
+        extra statement, an extra command, a conditional that makes the server
+        answer two kinds of client differently (the iPXE chainload is the usual
+        one -- hand a PXE ROM the iPXE binary, then hand iPXE the script).
+
+        Two ways in, and they end up in the same list:
+
+        - **from config**, `raw.<backend>=...` on the connection, or
+          `raw.<backend>.remove=...` for teardown;
+        - **from code**, by overriding this method in a `DhcpServer` subclass,
+          which is the one that can look at `ctx` and decide per target:
+
+          ```python
+          class dhcpd(netboot.dhcp.dhcpd.dhcpd):
+              def extras(self, ctx, phase="add"):
+                  lines = super().extras(ctx, phase)
+                  if phase == "add" and ctx.image._id.startswith("ipxe"):
+                      lines.append('if exists user-class ... { filename "boot.ipxe"; }')
+                  return lines
+          ```
+
+        What a fragment *is* belongs to the backend and is documented there:
+        dhcpd takes config statements, dnsmasq config lines, kea `option-data`
+        entries, windhcp PowerShell lines (or, under `method=netsh`, a
+        `{"Args": [...], "Ignore": bool}` command). A backend calls this once
+        per phase and emits whatever comes back **verbatim** -- netboot does not
+        parse, validate or escape it, which is the point of an escape hatch and
+        also the risk of one.
+        """
+        if phase not in PHASES:
+            raise ValueError(f"phase must be one of {PHASES}, not {phase!r}")
+        options = getattr(self, "options", None)
+        if options is None:  # pragma: no cover - a subclass that skips __init__
+            return []
+        return options.raw_for(type(self).__name__, phase)
+
     def remove_target(self, netboot: "PixieContext"):
         """Disarm this backend for the target in `netboot` (a `PixieContext`)."""
         pass

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/dhcp/dhcpd.py

@@ -109,7 +109,7 @@ class dhcpd(DhcpServer):  # noqa: N801 - the class name is the URI scheme
         target = netboot.target
         mac = _mac(target)
         options = self.options_for(netboot)
-        statements = render_statements(options, self.options.raw_for("dhcpd"))
+        statements = render_statements(options, self.extras(netboot, "add"))
         connection = self.connect()
         try:
             connection.add_host_supersede(

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/dhcp/dnsmasq.py

@@ -95,7 +95,11 @@ class dnsmasq(DhcpServer):  # noqa: N801 - the class name is the URI scheme
         tag = _tag(target)
         self._write(self.hostsfile, tag, [_host_line(target, tag)])
         if self.optsfile is not None:
-            self._write(self.optsfile, tag, _option_lines(tag, options))
+            self._write(
+                self.optsfile,
+                tag,
+                _option_lines(tag, options, self.extras(netboot, "add")),
+            )
         self._reload()
 
     def remove_target(self, netboot: "_ty.Any"):
@@ -226,7 +230,7 @@ def _host_line(target, tag: str) -> str:
     return "dhcp-host=" + ",".join(fields)
 
 
-def _option_lines(tag: str, options) -> "list[str]":
+def _option_lines(tag: str, options, extras: "list[str]|None" = None) -> "list[str]":
     """Translate the generic options into dnsmasq's own syntax."""
     lines: "list[str]" = []
     boot_file = options.get("boot-file-name")
@@ -244,7 +248,10 @@ def _option_lines(tag: str, options) -> "list[str]":
         if code is None:
             code = name[len("option-") :] if name.startswith("option-") else name
         lines.append(f"dhcp-option=tag:{tag},{code},{_value(value)}")
-    lines.extend(options.raw_for("dnsmasq"))
+    # `extras` comes from the server's `extras()` hook when there is one, so a
+    # subclass can add a `dhcp-match`/`dhcp-boot` pair per target; falling back
+    # to the options' own raw lines keeps this usable without a server.
+    lines.extend(extras if extras is not None else options.raw_for("dnsmasq"))
     return lines
 
 

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/dhcp/kea.py

@@ -145,7 +145,7 @@ class kea(DhcpServer):  # noqa: N801 - the class name is the URI scheme
                 option_data.append({"code": int(code), "data": _value(value)})
             else:
                 option_data.append({"name": name, "data": _value(value)})
-        option_data.extend(options.raw_for("kea"))
+        option_data.extend(self.extras(ctx, "add"))
         if option_data:
             reservation["option-data"] = option_data
         return reservation

{netboot-0.3.0 → netboot-0.3.1}/src/netboot/dhcp/options.py

@@ -59,9 +59,17 @@ APPLY_TIME = {
 OPTIONS_BUILDER = "options_builder"
 
 #: Query-key prefix for backend-native text netboot never translates:
-#: ``raw.dnsmasq=dhcp-option=tag:x,66,10.0.0.2``.
+#: ``raw.dnsmasq=dhcp-option=tag:x,66,10.0.0.2``. A phase may be appended --
+#: ``raw.dhcpd.remove=...`` -- for a fragment that belongs to teardown rather
+#: than to arming; a bare ``raw.<backend>`` is ``add``.
 RAW_PREFIX = "raw."
 
+#: The phases a raw fragment (or a backend's `extras()`) can belong to.
+PHASES = ("add", "remove")
+
+#: Separator in a `raw` key between backend and phase.
+RAW_PHASE_SEP = "."
+
 
 def is_option(name: str) -> bool:
     """Is `name` a client option netboot can carry to some backend?"""
@@ -83,9 +91,17 @@ class DhcpOptions(dict):
         super().__init__(*args, **kwargs)
         self.raw: "dict[str, list[str]]" = {k: list(v) for k, v in (raw or {}).items()}
 
-    def raw_for(self, backend: str) -> "list[str]":
-        """The untranslated lines this backend should emit verbatim."""
-        return list(self.raw.get(backend, ()))
+    def raw_for(self, backend: str, phase: str = "add") -> "list[str]":
+        """The untranslated lines this backend should emit verbatim.
+
+        `phase` is `add` or `remove`. A key with no phase (`raw.dhcpd=`) belongs
+        to `add`, which is what a fragment almost always is -- an extra
+        statement or command applied along with the reservation.
+        """
+        lines = list(self.raw.get(f"{backend}{RAW_PHASE_SEP}{phase}", ()))
+        if phase == "add":
+            lines = list(self.raw.get(backend, ())) + lines
+        return lines
 
     def copy(self) -> "DhcpOptions":
         return DhcpOptions(self, raw=self.raw)
@@ -111,7 +127,12 @@ def split_query(uri: str, settings: "_ty.Iterable[str]", backend: str):
         elif key == OPTIONS_BUILDER:
             builder = value
         elif key.startswith(RAW_PREFIX):
-            options.raw.setdefault(key[len(RAW_PREFIX) :], []).append(value)
+            name = key[len(RAW_PREFIX) :]
+            backend_name, _, phase = name.rpartition(RAW_PHASE_SEP)
+            if backend_name and phase in PHASES:
+                # `raw.dhcpd.remove=...` -- a teardown fragment.
+                name = f"{backend_name}{RAW_PHASE_SEP}{phase}"
+            options.raw.setdefault(name, []).append(value)
         elif key in APPLY_TIME:
             raise PixieConfigError(
                 f"{key!r} cannot be set on a {backend} connection: it depends on "