FreeBSD IPConfiguration — porting plan DEFERRED

A phased plan to eventually replace dhcpcd in this project with a port of Apple's IPConfiguration daemon-as-plugin. Sequenced after launchd, configd, and mDNSResponder are substantially complete. Recommendation: defer to Phase 7+ unless dhcpcd-with-netconfigd-shim shows real friction. This page exists to document the path so we don't relitigate the decision.

1. Goal & non-goals

1.1 Goal

Eventually replace dhcpcd in the freebsd-launchd project with a port of Apple's IPConfiguration. End state: netconfigd loads IPConfiguration.bundle at startup; the bundle owns DHCPv4/DHCPv6/IPv4LL/RA processing for every interface; state lands in netconfigd's dynamic store under the canonical Apple key namespace; client tools (scutil, ipconfig(8), GUI apps) reach the daemon via Distributed Objects over AF_UNIX.

1.2 Non-goals

• No Mach IPC. The 196-line MIG IDL bootplib/ipconfig.defs is replaced by an ObjC @protocol served over NSConnection.
• No IOKit power-management integration. Apple's IORegisterForSystemPower + IOPMConnectionCreate + scheduled wake events have no FreeBSD equivalent. Live without sleep-coordinated lease renewal in v1.
• No Apple80211. Wi-Fi association state comes from wpa_supplicant's control socket, not Apple's private 802.11 framework.
• No SymptomReporter / IPv6AWDReport. Apple wireless diagnostics telemetry — delete on import.
• No MobileGestalt. One call site in dhcp.c; stub returns "FreeBSD".
• No NetBoot / BSDP. The bootp repo contains bootpd, BSDPClient, netbootdisk, etc. — out of scope for this port.
• No EAPOLController. 802.1X auth coordination skipped in v1; if needed later, route through wpa_supplicant.
• No CLAT46 / L4S ioctls. Darwin-private; #ifdef'd out.

2. Source overview

Largest single files:

• IPConfiguration.bproj/ipconfigd.c — 10,312 LOC. Plugin shell + IFState + SCDynamicStore + power events + service lifecycle. The bulk of the port effort.
• IPConfiguration.bproj/dhcp.c — 4,660 LOC. DHCPv4 state machine. Port verbatim (one MobileGestalt call to amputate).
• IPConfiguration.bproj/DHCPv6Client.c — 3,717 LOC. DHCPv6 state machine. Port verbatim.
• bootplib/RouterAdvertisement.c — 1,788 LOC. RA parser/builder. Port verbatim.
• bootplib/dhcp_options.c — 1,716 LOC. 113 known DHCPv4 options. Port verbatim.
• bootplib/DHCPv6Options.c — 1,637 LOC. DHCPv6 options. Port verbatim.
• bootplib/interfaces.c — 1,589 LOC. Already uses getifaddrs(3) and SIOCGIFMEDIA. Minor BSD #ifdefs.

3. Architecture (target)

Same shape as Apple's: IPConfiguration is a plugin inside netconfigd's process, not a separate daemon. Shares the SCDynamicStore + DO IPC infrastructure netconfigd provides.

4. File-by-file plan

4.1 Delete on import

• 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 Rewrite (Mach → DO, Darwin → BSD)

4.3 Port verbatim (or near)

5. Mach IPC → Distributed Objects

The single MIG IDL bootplib/ipconfig.defs (196 LOC, 21 routines) becomes an ObjC @protocol over NSConnection on a known AF_UNIX path. Same shape as the configd plan.

@protocol NCIPConfiguration

// Counts and lookups
- (NSNumber *)interfaceCount;
- (NSArray *)interfaceList;

// DHCPv4 state queries
- (NSData *)optionForInterface:(NSString *)ifname code:(int)code
                        status:(out NCStatus *)status;
- (NSString *)addressForInterface:(NSString *)ifname
                           status:(out NCStatus *)status;
- (NSData *)lastDHCPPacketForInterface:(NSString *)ifname
                                status:(out NCStatus *)status;
- (NSDictionary *)summaryForInterface:(NSString *)ifname;

// Service lifecycle
- (NSString *)addServiceOnInterface:(NSString *)ifname
                         methodPlist:(NSDictionary *)plist
                              status:(out NCStatus *)status;
- (NCStatus)removeServiceOnInterface:(NSString *)ifname
                            serviceID:(NSString *)sid;
- (NCStatus)refreshServiceOnInterface:(NSString *)ifname
                             serviceID:(NSString *)sid;
- (NCStatus)setMethodForInterface:(NSString *)ifname
                       methodPlist:(NSDictionary *)plist;

// IPv6 / DHCPv6
- (NSData *)lastDHCPv6PacketForInterface:(NSString *)ifname
                                  status:(out NCStatus *)status;
- (NSData *)lastRAForInterface:(NSString *)ifname;
- (NSData *)dhcpDUID;
- (NSNumber *)iaidForInterface:(NSString *)ifname;

// Operational
- (NCStatus)setVerbose:(BOOL)verbose;
- (NCStatus)forgetNetworkForInterface:(NSString *)ifname;

@end

Per-call uid/gid check via getpeereid(2) on the AF_UNIX socket replaces Apple's BSM audit-token entitlement check (server.c:79-115). Same caller identity, much simpler than maintaining libbsm + an entitlement DB.

6. Kernel events: SCDynamicStore, not direct

Important finding: IPConfiguration does not subscribe to KEV_NETWORK_CLASS directly. grep -rln 'KEV_DL\|KEV_INET\|KEV_NETWORK_CLASS' IPConfiguration.bproj returns nothing. All kernel events arrive translated as SCDynamicStore key changes from the sibling KernelEventMonitor.bundle configd plugin. This is a clean win — our port can subscribe to the same key suffixes through netconfigd's KernelEventMonitor port (a Phase 2 item in the configd plan), and the PF_ROUTE knowledge stays in one place.

Keys IPConfiguration subscribes to (ipconfigd.c:9303-9333):

• kSCEntNetLink — link up/down → link_key_changed()
• kSCEntNetAirPort — Wi-Fi association change → ap_key_changed()
• kSCEntNetRefreshConfiguration — explicit RENEW request → link_refresh()
• kSCEntNetIPv6 — IPv6 address-list change → ipv6_interface_address_changed()
• kSCEntNetIPv4ARPCollision — ARP collision detected → arp_collision()
• kSCEntNetIPv6RouterExpired — router lifetime expired → ipv6_router_expired()
• kSCEntNetNAT64 — PLAT discovery complete → process_plat_discovery_complete()

The PF_ROUTE → SC-key translation table goes in netconfigd's KernelEventMonitor port:

7. Apple-specific dependencies

8. The hard parts

1. ipconfigd.c is 10,312 LOC of mixed concerns. Plugin shell + IFState + SCDynamicStore plumbing + power events + DHCP renew scheduling + wireless coordination + service-list ordering. Splitting into a portable core + Darwin-specific shell is the largest single sub-task. No clean cut at any function boundary above ~150 LOC.
2. Mach IPC is concentrated server-side, but framework client uses it too. server.c (654 LOC) is the only server. But IPConfigurationService.c (1,245 LOC), DHCPv6PDService.c (565 LOC), and ipconfig.tproj/client.c (1,630 LOC) are all pure Mach clients. Our DO rewrite lands in four places.
3. DUID UUID-mode requires deterministic kern.hostuuid. First-boot ISOs may have kern.hostuuid blank or all-zeros. Need a seed step (UUIDv4 from /dev/random, persisted) that runs before IPConfiguration first runs. Extend the launchd varrun one-shot to handle this.
4. SymptomReporter + IOPMCopyScheduledPowerEvents sprinkled across files. Simple amputation but ~30 call sites in ipconfigd.c, DHCPv6Client.c:2692, dhcp.c retry paths, report_symptoms.c.
5. os_log_t handle plumbing. Every translation unit takes os_log_t parameters in macros. Rewrite as opaque void * wrapping our logger, or replace the entire module with a syslog(3) wrapper.
6. ifutil.c Darwin-specific ioctls. About 12 with no FreeBSD equivalent. #ifdef out; CLAT46 + L4S features unavailable.
7. PvD HTTPS fetch helper is XPC. IPConfigurationHelper is a separate launchd-managed sandboxed helper that does NSURLSession TLS fetches. We don't have XPC. Either fold into main daemon (loses sandbox isolation) or implement DO-based helper. Defer until PvD support actually matters — RFC 8801 deployment is rare.
8. BSM audit-token entitlement gating. Replace with getpeereid uid checks; the "entitlement" concept (code-signed plist key on caller binary) doesn't translate to FreeBSD.
9. Two configd plugin dependencies (InterfaceNamer, KernelEventMonitor) must exist before IPConfiguration loads. netconfigd's responsibility — both are Phase 2 work in the configd plan. Sequencing constraint.
10. SCPreferences watcher for the tunables plist. netconfigd Phase 2+ SCPreferences-equivalent.

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). Per-service: set kSCNetworkProtocolTypeIPv6 ConfigMethod to Manual or LinkLocal. Our port should default to DHCPv6Enabled=false, requiring per-service opt-in via the ConfigMethod Setup-key. This matches the nodhcp6 default we're shipping in dhcpcd today.

Conclusion: porting IPConfiguration does NOT solve the spam problem; it merely renames it. The fix in either world is the same: don't enable DHCPv6 by default on networks where it doesn't function. Not a reason to port; not a reason not to either.

10. Comparison with dhcpcd

What IPConfiguration has that we'd gain: SCDynamicStore-keyed publication (cleaner integration with netconfigd), IPConfigurationServiceCreate framework API (Mac app symmetry), Bonjour Sleep Proxy + IOKit power coordination (irrelevant on FreeBSD without their kernel infra), CGA.

What dhcpcd has that we'd lose: RFC 3118 authentication (rare in real deployments), Reconfigure handler, dynamic SOL_MAX_RT learning, hook-script ecosystem, bridge/lagg/vlan layering recognition (the killer for our use case if we don't replace it), privilege separation, RFC 7217 stable IIDs, cross-platform maintenance burden shared with NetBSD/Linux/etc.

11. Locked architectural decisions

12. Phased delivery

13. Open questions

14. References

• Apple source: github.com/apple-oss-distributions/bootp (latest tag bootp-534.100.6). The IPConfiguration.bproj/ directory is what we port.
• RFC 2131 — DHCPv4. rfc-editor.org/rfc/rfc2131
• RFC 8415 — DHCPv6. rfc-editor.org/rfc/rfc8415
• RFC 4861 — IPv6 Neighbor Discovery (RS/RA). rfc-editor.org/rfc/rfc4861
• RFC 8106 — RDNSS / DNSSL. rfc-editor.org/rfc/rfc8106
• RFC 3927 — IPv4LL (link-local). rfc-editor.org/rfc/rfc3927
• RFC 3972 — Cryptographically Generated Addresses. rfc-editor.org/rfc/rfc3972
• dhcpcd source (the alternative we ship today): github.com/NetworkConfiguration/dhcpcd
• Companion plans: freebsd-launchd, freebsd-configd, freebsd-mDNSResponder, freebsd-kmodloader.