NextBSD IPConfiguration — porting plan Filed under: freebsd-launchd-mach (v2) effort SHIPPED through iter 8

A phased plan to replace dhcpcd in this project with a port of Apple's IPConfiguration daemon. Targets freebsd-launchd-mach (v2) — the Mach IPC + libxpc + libdispatch track. Shipped through iter 8 as a standalone Mach daemon at src/IPConfiguration/, NOT as a configd plugin (this repo's configd has no plugin loader). DHCPv4 INIT→BOUND, RFC 5227 ARP probe, IPv6 RA/SLAAC, SCDynamicStore publish, MIG service worker, and the Apple-shape ipconfig(8) CLI are live.

1. Goal & non-goals

1.1 Goal

Replace dhcpcd in the freebsd-launchd-mach (v2) project with a port of Apple's IPConfiguration. End state (now reached through iter 8): a standalone Mach daemon /usr/sbin/ipconfigd owns DHCPv4 / RA-SLAAC / ARP processing for the first non-loopback Ethernet; state lands in this repo's SCDynamicStore (via Mach RPC to configd at com.apple.SystemConfiguration) under the canonical Apple key namespace (State:/Network/Service/<UUID>/IPv4 + /IPv6); client tools (scutil, ipconfig(8)) reach the daemon via MIG over mach_msg on service name com.apple.IPConfiguration.

1.2 Non-goals

• No configd-plugin model. This repo's configd has no plugin loader. IPConfiguration is a separate Mach daemon, not a bundle loaded into configd's address space. The two daemons talk Mach RPC.
• No AF_UNIX / Distributed Objects. The sibling freebsd-launchd repo uses that pattern; this is the Mach-IPC track. ipconfig.defs MIG IDL is retained (this repo's slim 2-routine subset).
• No IOKit power-management integration. Apple's IORegisterForSystemPower + IOPMConnectionCreate + scheduled wake events have no FreeBSD equivalent. Live without sleep-coordinated lease renewal.
• No Apple80211. WLAN association state arrives as the State:/Network/Interface/<iface>/AirPort key published by wland — ipconfigd does not read wpa_supplicant's control socket itself. Current iters target Ethernet only; the DHCP gate that consumes AirPort{Authenticated} is specced in the WLAN plan §1.4.
• No SymptomReporter / IPv6AWDReport. Apple wireless diagnostics telemetry — deleted on import.
• No MobileGestalt. One call site in dhcp.c; stub returns "FreeBSD".
• No NetBoot / BSDP. Out of scope.
• No EAPOLController. 802.1X auth coordination skipped; if needed later, route through wpa_supplicant.
• No CLAT46 / L4S ioctls. Darwin-private; #ifdef'd out.
• No DHCPv6 stateful (iter 7b deferred indefinitely). SLAAC covers the common case; QEMU SLIRP doesn't run a DHCPv6 server so there's no CI validation path. Build when a real consumer needs it.

2. Apple source overview (reference)

For context: Apple's bootp repo total scope. This repo's port is much smaller — a fresh-written thin daemon at src/IPConfiguration/ that draws on Apple's protocol cores rather than re-shaping Apple's plugin tree wholesale.

Largest single Apple files (for orientation):

• IPConfiguration.bproj/ipconfigd.c — 10,312 LOC. Plugin shell + IFState + SCDynamicStore + power events + service lifecycle. Not ported wholesale; this repo's ipconfigd.c is fresh-written and much smaller.
• IPConfiguration.bproj/dhcp.c — 4,660 LOC. DHCPv4 state machine; protocol-core reference for our dhcp_discover.c.
• IPConfiguration.bproj/DHCPv6Client.c — 3,717 LOC. Not built — iter 7b deferred indefinitely.
• bootplib/RouterAdvertisement.c — 1,788 LOC. RA parser/builder; reference for our ra_listen.c.
• bootplib/dhcp_options.c — 1,716 LOC. 113 known DHCPv4 options; option-table reference.
• bootplib/DHCPv6Options.c — 1,637 LOC. DHCPv6 options — not built (iter 7b deferred).
• bootplib/interfaces.c — 1,589 LOC. Uses getifaddrs(3) + SIOCGIFMEDIA; FreeBSD-portable.

3. Architecture (shipped)

Standalone Mach daemon (NOT a configd plugin — this repo's configd has no plugin loader). The two daemons live in separate address spaces and communicate exclusively over Mach RPC. ipconfigd registers Mach service com.apple.IPConfiguration; it publishes to com.apple.SystemConfiguration via sc_publish.c. Subscribes to nothing yet — DHCP fires once at boot on the first non-loopback Ethernet. Hot-plug / multi-interface deferred.

4. Shipped files (file-by-file)

Source tree lives at src/IPConfiguration/ in the freebsd-launchd-mach repo. Translation units below are what's on disk through iter 8 (PRs #42–#51).

4.1 Deleted on import (Apple subtrees out of scope)

• Whole subtrees: bootpd.tproj, bootpdutil.tproj, bsdpc.tproj, BSDPClient/, dhcp6d.tproj/, DHCPServer/, netbootdisk/, rtadvd/ — all sibling daemons not in scope.
• IPConfiguration.bproj/IPv6AWDReport.{h,m} — Apple Wireless Diagnostics telemetry.
• IPConfiguration.bproj/report_symptoms.{c,h} — same.
• IPConfiguration.bproj/Embedded-Info.plist — iOS variant manifest.
• IPConfiguration.bproj/wireless-entitlements.plist — code-signing entitlements.
• bootplib/ioregpath.{c,h} — IORegistry walker, only used for NetBoot.
• bootplib/{nbimages,nbsp,bsdplib,macnc_options,netinfo,subnets}.{c,h} — NetBoot internals.
• SCTest-Swift/, tests/IPConfigurationTest/ Xcode test schemes — replace with our own.
• All Xcode project files (*.xcodeproj, xcconfigs/).

4.2 Fresh-written for this repo (Apple shapes, Mach-IPC track)

Rather than line-for-line reshape Apple's ipconfigd.c (10k LOC of plugin shell + power events + service lifecycle + Mach RPC server), iter 1–8 wrote a thin daemon from scratch that reuses Apple's protocol cores (DHCPv4 state machine, DHCP option tables, RA parser, ARP packet build) and replaces everything Darwin-specific with native FreeBSD code.

4.3 Apple protocol-core inventory (reference)

Files in Apple's tree that would be portable verbatim (or near) on a future expansion. Today this repo's fresh-written daemon uses these as reference oracles rather than importing them directly — the iter 1–8 codebase is much smaller. Listed here for orientation when growing the surface in future iters.

5. MIG IDL (Mach-IPC track)

Apple's bootplib/ipconfig.defs is 196 LOC, 21+ routines. This repo retains the same MIG-over-mach_msg shape but ships a slim 2-routine subset as src/IPConfiguration/ipconfig.defs. The MIG-generated stubs link into both the daemon (mach_service.c) and the CLI (ipconfig.c).

subsystem ipconfig 17000;

#include <mach/std_types.defs>
#include <mach/mach_types.defs>

/* Iter 5a — 2 routines. */
routine ipconfig_if_count(
        server          : mach_port_t;
    out  count           : int);

routine ipconfig_if_addr(
        server          : mach_port_t;
     in  ifname          : (string_t);
    out  ipv4            : (string_t);
    out  result          : int);

Future routines (Apple's full surface) grow the IDL as real consumers arrive — see §12 Future iters. Caller-identity gating on these MIG entry points is currently TODO; no BSM audit-token / Apple entitlement system exists in this repo. Production hardening would gate on the Mach audit-token PID + uid via set_security_token already used elsewhere in the launchd-mach kernel module (cf. fork_bsport).

6. Kernel events: publish-only today

Apple's ipconfigd subscribes to seven SCDynamicStore key suffixes (kSCEntNetLink, kSCEntNetAirPort, kSCEntNetRefreshConfiguration, kSCEntNetIPv6, kSCEntNetIPv4ARPCollision, kSCEntNetIPv6RouterExpired, kSCEntNetNAT64) translated from kernel events by the sibling KernelEventMonitor.bundle configd plugin. This repo's ipconfigd currently subscribes to none of them — it fires DHCPv4 once at boot on the first non-loopback Ethernet interface, runs the ARP probe, then publishes the resulting lease.

Concretely, today (iter 8):

• Publishes: State:/Network/Service/<UUID>/IPv4 + /IPv6 over Mach RPC to com.apple.SystemConfiguration via sc_publish.c.
• Subscribes: nothing. No link up/down handling, no ARP-collision handling, no router-lifetime-expiry handling, no NAT64 handling, no WLAN association events.
• Lease renewal: driven by the timer in lease_loop.c (RFC 2131 T1/T2), not by external events. IPCONFIGD_FAST_LEASE=1 collapses the wait for CI.

Hot-plug, multi-interface, link-flap handling, and ARP-collision recovery all wait on a KEM-equivalent. The future-iters plan calls for hwregd-driven subscription rather than a configd KEM plugin (this repo has no plugin loader). PF_ROUTE → publish mapping is the same on FreeBSD vs. Darwin:

7. Apple-specific dependencies

8. The hard parts (what bit in iter 1–8)

1. BPF rxbuf sizing for ARP probe (iter 6). arp_probe.c initially undersized the BPF rxbuf; BIOCGBLEN returns 4096 by default. Fixed in commit e790468 — match the kernel's reported buffer size, not a guessed-smaller value. The exact failure mode was probe responses getting truncated silently.
2. SCDynamicStore publish from a non-plugin daemon (iter 4). Apple's pattern is "publish from inside configd's address space." This repo's sc_publish.c instead bundles up the CF dictionary and ships it as a Mach RPC to configd's com.apple.SystemConfiguration port. CF lifetime + key-shape symmetry both had to be right or scutil would not see the value.
3. MIG worker thread coexistence with the main DHCP loop (iter 5a). The worker runs mach_msg_server blocking on the registered port while the main thread runs select() over BPF / PF_ROUTE / RA sockets. Shared lease state lives in bound_state.c behind locks. Bootstrap_check_in must happen before the MIG service can be reached.
4. RFC 2131 RENEWING/REBINDING timer accuracy under CI (iter 5b). Real T1/T2 timers are minutes-to-hours; CI must observe the renewal without sleeping for hours. Solution: IPCONFIGD_FAST_LEASE=1 env var collapses T1/T2 to seconds; the IPCFG-RENEW-OK boot marker gates CI on observing one full renew cycle.
5. SLAAC vs. FreeBSD's accept_rtadv flag (iter 7a). The kernel's net.inet6.ip6.accept_rtadv=0 default plus per-iface IFDISABLED meant SLAAC silently did nothing until apply_lease_v6.c explicitly cleared IFDISABLED and called SIOCAIFADDR_IN6 with the EUI-64 we derived ourselves. RTM_ADD for ::/0 goes through the standard route socket.
6. Apple-shape ipconfig(8) command-table dispatch (iter 8). The CLI is structurally identical to Apple's — a static table of {name, handler, min_args, help} rows that the main dispatcher matches against argv[1]. Built fresh against our MIG client stubs.
7. DHCPv6 not built (iter 7b deferred indefinitely). Apple's DHCPv6Client.c is 3717 LOC. QEMU SLIRP doesn't run a DHCPv6 server, so there's no CI validation path. SLAAC covers home / SOHO / most enterprise. Build when a real consumer needs it.
8. Caller-identity gating is currently TODO. MIG entry points are ungated. Production hardening should gate on the Mach audit-token PID + uid via the set_security_token path already in mach.ko (cf. fork_bsport).
9. Subscribes to nothing yet. Hot-plug / link-flap / multi-interface / ARP-collision-recovery handling all wait on a kernel-event-subscription path. Future iters plan a hwregd-driven subscription (see §12).

9. The DHCPv6-spam-on-broken-networks problem

Confirmed: IPConfiguration has the same problem as dhcpcd. Both implement RFC 8415 verbatim. RFC 8415 says DHCPv6 Solicit has no max retransmission count (SOL_MAX_RC = 0 = infinite). Both clients retry Solicit forever on networks where the router advertises the M-flag but the DHCPv6 server returns "No Addresses Available." Both cap at one Solicit per hour with random jitter (SOL_MAX_RT = 3600).

Source citations:

• IPConfiguration: bootplib/DHCPv6.h:79-94 defines constants. DHCPv6Client.c:2641-2691 sends Solicit with DHCPv6ClientNextRetransmit(client, DHCPv6_SOL_TIMEOUT, DHCPv6_SOL_MAX_RT). No max-retry check.
• dhcpcd: src/dhcp6.h:120-121 defines same constants. src/dhcp6.c:1723 sets state->MRC = SOL_MAX_RC (= 0).

The Apple-vs-FreeBSD difference is purely logging policy:

• Apple's os_log infrastructure suppresses LOG_INFO "Solicit Transmit (try=N)" messages from default user-visible streams. Packets still go out the wire; users don't see them.
• FreeBSD's syslog(3) shows everything at default priority. dhcpcd at LOG_NOTICE for "DHCPv6 REPLY: No Addresses Available" → spammy.

Knob to disable in IPConfiguration: DHCPv6Enabled boolean in Embedded-Info.plist (default true upstream). Per-service: set kSCNetworkProtocolTypeIPv6 ConfigMethod to Manual or LinkLocal.

Conclusion (iter 8 resolution): this repo's ipconfigd doesn't build the DHCPv6 stateful path at all (iter 7b deferred indefinitely). The spam problem is sidestepped entirely. SLAAC handles the IPv6 case. If someone later builds DHCPv6 here, they'll need to default it to off and require per-service opt-in.

10. Comparison with dhcpcd

What IPConfiguration gave us (iter 1–8): SCDynamicStore-keyed publication (cleaner integration with the rest of the Mach-IPC track), Apple-shape ipconfig(8) CLI with MIG-stub dispatch, RFC 5227 ARP probe + announce, IPv6 RA listener + SLAAC, RFC 2131 lease loop. CGA + Bonjour Sleep Proxy + IOKit power coordination remain Apple-only (no FreeBSD equivalents — out of scope by design).

What dhcpcd had that we gave up: RFC 3118 authentication (rare in real deployments), DHCPv6 Reconfigure handler (deferred — iter 7b), dynamic SOL_MAX_RT learning (DHCPv6 not built), hook-script ecosystem (replaced by SCDynamicStore publish), bridge/lagg/vlan layering recognition (deferred — multi-interface future iter), privilege separation (daemon runs as root under launchd), RFC 7217 stable IIDs (deferred), cross-platform maintenance burden shared with NetBSD/Linux/etc. (intentional — this is an Apple-track port).

11. Locked architectural decisions

12. Iter history (shipped)

13. Future iters

14. Open questions / deferred features

Deferred-by-design (per the iter plan):

• RDNSS (RFC 8106). Today we ignore RDNSS in RA options. resolv.conf integration deferred until a consumer needs it.
• Multiple IPv6 prefixes. Only the first PIO from the RA is used.
• RA lifetime expiry. No timer on the published ::/0 default route.
• RFC 7217 stable privacy addresses. EUI-64 only; no opaque interface identifier.
• IPv4LL (RFC 3927 fallback). DHCPv4 failure does not fall back to link-local.
• Manual / static config method. No ConfigMethod=Manual path yet.
• PvD / HTTPS provisioning (RFC 8801). Apple's IPConfigurationHelper XPC helper not ported.
• IO80211 / cellular. WLAN association coordination and cellular paths not built. The WLAN half is now specced — ipconfigd gates DHCP on wland's AirPort key rather than talking 802.11 itself.
• Hot-plug / multi-interface. Subscribes to nothing; only the first boot-time Ethernet.
• Lease persistence. No /var/db/dhcpclient/ equivalent — lease lives in bound_state.c RAM only.
• DHCPv6 stateful (iter 7b). Deferred indefinitely — SLAAC covers the common case.

15. References

• Apple source: github.com/apple-oss-distributions/bootp (latest tag bootp-534.100.6). The IPConfiguration.bproj/ directory is the upstream we reference.
• RFC 2131 — DHCPv4. rfc-editor.org/rfc/rfc2131
• RFC 5227 — IPv4 Address Conflict Detection (ARP probe + announce). rfc-editor.org/rfc/rfc5227
• RFC 8415 — DHCPv6 (deferred indefinitely, iter 7b). rfc-editor.org/rfc/rfc8415
• RFC 4861 — IPv6 Neighbor Discovery (RS/RA). rfc-editor.org/rfc/rfc4861
• RFC 8106 — RDNSS / DNSSL (deferred). rfc-editor.org/rfc/rfc8106
• RFC 3927 — IPv4LL (link-local; deferred). rfc-editor.org/rfc/rfc3927
• RFC 7217 — Stable privacy IPv6 IIDs (deferred). rfc-editor.org/rfc/rfc7217
• RFC 3972 — Cryptographically Generated Addresses. rfc-editor.org/rfc/rfc3972
• dhcpcd source (the alternative we replaced): github.com/NetworkConfiguration/dhcpcd
• Companion plans: freebsd-launchd, nextbsd-configd, freebsd-mDNSResponder, freebsd-kmodloader.
• Sibling track: freebsd-launchd (AF_UNIX + GNUstep DO). This plan targets the v2 Mach-IPC track.

Revision 2026-05-23. Refactored from a deferred netconfigd-plugin plan (sibling AF_UNIX/DO track) to a shipped freebsd-launchd-mach (v2) standalone Mach daemon. Iter 1–8 (PRs #42–#51) merged: daemon skeleton, DHCPv4 INIT→BOUND, SCDynamicStore publish, RFC 2131 RENEW/REBIND with IPCONFIGD_FAST_LEASE CI gate, MIG service worker (2-routine surface), RFC 5227 ARP probe + announce, IPv6 RA listener + EUI-64 SLAAC + ::/0 route + State:/.../IPv6 publish, Apple-shape ipconfig(8) CLI. iter 7b (DHCPv6 stateful) deferred indefinitely. Future iters grow the MIG surface, add multi-interface workers, swap select() for kqueue, and subscribe to hwregd for hot-plug.