NextBSD configd — porting plan Filed under: freebsd-launchd-mach (v2) effort PARTIALLY SHIPPED

A two-layer network and system-configuration stack for FreeBSD. The lower layer is the in-tree IPConfiguration daemon (DHCPv4/v6 + RA, RFC 5227 ARP, lease publish via Mach RPC). The upper layer is a port of Apple's configd — daemon name retained verbatim as configd, Mach-served as com.apple.SystemConfiguration, providing the SystemConfiguration dynamic store via MIG (configd.defs) for scutil, IPConfiguration, and GUI tooling. Companion to the freebsd-launchd-mach port.

1. Goal & non-goals

1.1 Goal

A FreeBSD live ISO that boots with launchd as PID 1, gets a working network in seconds without user intervention, and runs a SystemConfiguration-equivalent layer on top — the Apple-shape SCDynamicStore over Mach RPC for scutil, libIOKit consumers, and GUI tooling — while delegating the protocol-level work (DHCP, RA, ARP collision) to IPConfiguration, the standalone in-tree daemon that already does it. configd is the store; IPConfiguration is the protocol layer; they meet over Mach RPC.

1.2 Non-goals (this iteration)

• No DHCP client inside configd. IPConfiguration handles DHCPv4 + DHCPv6 in one daemon, including RDNSS, DNSSL, lease renewal, RFC 5227 ARP probe/announce, link-state recovery. configd is not the protocol layer.
• No RA processing inside configd. IPConfiguration parses RAs in userspace — supports prefix info, RDNSS (RFC 8106), DNSSL, route preferences.
• No AirPort / CoreWLAN logic. WLAN association is wland's job, not configd's — wland drives stock wpa_supplicant and publishes State:/Network/Interface/<iface>/AirPort into the store itself, over the ordinary SCDynamicStoreSetValue path. configd is the store, not the author. No configd change is required for WLAN. Apple's eapolclient is not ported. See the WLAN plan.
• No InterfaceNamer plugin. Apple's InterfaceNamer uses IOKit to assign persistent names; FreeBSD names interfaces in-kernel. Interface metadata (USB/PCI introspection) is available via libIOKit over hwregd for downstream consumers.
• No GNUstep / Distributed Objects. This is the Mach-IPC track. MIG over mach_msg is the IPC.
• No SimulatorSupport / QoSMarking. Apple-only frameworks; not portable.
• No captive-portal detection. Apple's URL-probe heuristic is out of scope; users handle this in the browser.
• No /etc/rc.conf compatibility layer. When SCPreferences arrives, preferences.plist will be the declarative config configd reads — matching Apple's surface.

2. Architecture: layered model

Two layers, separable in time and ownership:

2.1 Why two layers instead of one

Apple's configd has both layers fused — the IPConfiguration agent (DHCP/RA) is loaded as a plugin inside the configd process. We split it: configd is its own process, IPConfiguration is its own process. The interface between them is the same one Apple's IPConfiguration plugin would use internally — SCDynamicStoreSetValue on State:/Network/Service/<UUID>/IPv{4,6} — just now reached over Mach RPC rather than in-process. From the consumer's point of view (a GUI tool reading the dynamic store) the surface is identical.

The boundary between layers is clean: IPConfiguration owns protocol actions (acquire lease, run RFC 5227 ARP, configure address); configd owns store + IPC (key/value space, subscription, notification fan-out). They communicate via the canonical SCDynamicStore RPC surface; no custom protocol.

3. Layer 1 (shipped): IPConfiguration (in-tree) + wpa_supplicant (port)

3.1 IPConfiguration as the protocol layer

Apple ships IPConfiguration as a configd plugin loaded into the configd address space. In freebsd-launchd-mach it runs as its own daemon (src/IPConfiguration/) supervised by launchd. The split is a deliberate choice — the plugin loader is deferred, and the standalone shape made it easier to iterate on the DHCP state machine and RFC 5227 ARP without dragging the rest of configd along.

• Per-iface DHCPv4 state machine (DISCOVER / OFFER / REQUEST / ACK / RENEW / REBIND); IPv6 RA + DHCPv6.
• RFC 5227 ARP probe before declaring a lease bound (iter 6, shipped); ARP announce after.
• Lease loop with link-state hooks (re-DHCP on cable reconnect).
• On bound transition, calls sc_publish_ipv4() / sc_publish_ipv6() (in src/IPConfiguration/sc_publish.c) which talks to configd over Mach RPC via libSystemConfiguration. configd writes the published dictionary to State:/Network/Service/<UUID>/IPv4 (and v6) and fans the change out to any subscribed client ports.

3.2 wpa_supplicant from base (not ports)

Corrected. An earlier draft of this section had the security/wpa_supplicant port superseding base, arguing faster WPA3-SAE/OWE uptake and more aggressive CVE backports. The WLAN plan §3.3 rules that out: the port is the same 2.11 as base, but installs to /usr/local/sbin and shadows base for no benefit. We keep stock wpa_supplicant from FreeBSD base, untouched — not vendored into nextbsd-userland/src, not taught Mach, not added as a port. It speaks net80211 ioctls downward and a UNIX control socket upward; it never needs to know configd exists. All Mach knowledge lives in wland, which gets it for free by linking libSystemConfiguration. eapolclient (Apple's 802.1X supplicant) is not ported; WPA-Enterprise comes from wpa_supplicant's own EAP stack or not at all.

3.3 What configd IS doing today

configd is up and serving. Daemon binary at /usr/libexec/configd (TBD path; matches Apple), launchd plist publishes the com.apple.SystemConfiguration Mach service via MachServices; configd grabs the receive right via bootstrap_check_in, runs a MIG dispatch loop, and answers SCDynamicStoreCreate / SetValue / CopyValue / SetNotificationKeys / CopyKeyList over configd.defs. Notification keys cause the daemon to remember the client's notify port and send a wakeup mach_msg on key change; the client's SCDynamicStore rlsource fires.

The IPConfiguration → configd path is end-to-end: bind a lease, watch State:/Network/Service/<UUID>/IPv4 change in scutil-equivalent test tools. That's the level of "live" we're at.

4. Layer 2 (PARTIALLY SHIPPED): configd

End state: a launchd-supervised long-running daemon that publishes com.apple.SystemConfiguration, owns the SCDynamicStore, exposes the canonical configd.defs MIG surface, and (when SCPreferences arrives) reads declarative network preferences. Distinct from Apple's shape in that it does not host plugins in-process — the plugin loader is deferred. Things Apple shipped as plugins are either rolled in (IPMonitor's resolv.conf merge, future), run standalone (IPConfiguration), or unbuilt.

4.1 Dynamic store

configd publishes state to the SystemConfiguration "dynamic store" — a key-value space (keys like State:/Network/Interface/en0/IPv4) that processes subscribe to. Apple's key shape is retained verbatim. The backing store is an in-memory CF dictionary protected by a serial dispatch queue; subscribers register interest via SCDynamicStoreSetNotificationKeys (exact keys or regex patterns); the daemon sends mach_msg wake-ups to the subscriber's notify port when matching keys change.

Sources of state:

• IPConfiguration: on bind/release, calls sc_publish_ipv4() / sc_publish_ipv6(); that path lands as State:/Network/Service/<UUID>/IPv{4,6} writes via Mach RPC. Shipped.
• PF_ROUTE socket (planned): address adds/removes, link-state, route changes → populate State:/Network/Interface/<iface>/IPv{4,6}. Apple does this in the KernelEventMonitor plugin.
• wland (planned): publishes State:/Network/Interface/<iface>/AirPort — {Authenticated, SSID, BSSID, RSSI, Channel, Security}. configd does not read the wpa_supplicant control socket; wland owns it and writes the key like any other SCDynamicStore client. (An earlier draft of this plan had configd populating a …/WiFi key directly — that key name and that ownership are both wrong; see the WLAN plan.) Scan results deliberately do not go in the store: CONFIG_DATA_MAX rejects any value over 8 KiB.
• SCPreferences (deferred): populate Setup:-prefixed keys from preferences.plist — the user's declared service set / interface config.

4.2 MIG surface (configd.defs)

Apple's configd.defs is the IDL, retained. mig-generated server stubs link into configd; mig-generated client stubs link into libSystemConfiguration.so. Representative routines presently wired:

• configopen — allocate a session (a CFDictionary store handle); returns a server port the client uses as a session handle.
• configadd / configset — set value at key (SCDynamicStoreSetValue / SetMultiple).
• configget — copy value at key (SCDynamicStoreCopyValue).
• configlist — copy key list, optionally pattern-filtered (SCDynamicStoreCopyKeyList).
• configadd_notification / configremove_notification — subscribe / unsubscribe to keys or patterns.
• notifyset — deliver-port handoff: the client passes a Mach port the daemon should mach_msg on change.
• configclose — tear down session, drop subscriptions.

4.3 SCPreferences (deferred)

Apple's SCPreferences is the persistence + commit/apply surface over preferences.plist. Header surface present in src/libSystemConfiguration/SCPreferences.c; backing store and configd-side RPCs are not yet wired. When this lands, configd will:

1. Read preferences.plist (Apple-canonical path) via CFPropertyList.
2. Populate Setup: keys in the dynamic store from the parsed prefs.
3. Accept SCPreferencesCommit-shaped RPCs from clients; rewrite the plist atomically; reload Setup:; notify subscribers.

The shape is Apple-canonical — no FreeBSD-only Network.plist alternative; preferences.plist is the file.

4.4 Event sources

5. Repository

5.1 Layout under freebsd-launchd-mach/src/

freebsd-launchd-mach/src/
├── configd/                       The daemon. PARTIALLY SHIPPED.
│   ├── configd.c                  Service publish + MIG demux + dispatch_main
│   ├── config.defs                Apple configd.defs IDL (retained verbatim)
│   ├── config_session.{c,h}       Per-client session state, port tracking
│   ├── config_store.{c,h}         In-memory key/value store + pattern subs
│   ├── config_wire.{c,h}          MIG server stub helpers (CFData marshalling)
│   ├── config_types.h             Shared types between defs and impl
│   └── *test.c                    in-tree integration tests against the live
│                                  Mach service (configtest, listtest, patterntest,
│                                  notifytest, multitest)
│
├── libSystemConfiguration/        The client framework. PARTIALLY SHIPPED.
│   ├── SCDynamicStore.c           Public SCDynamicStoreCreate / SetValue /
│   │                              CopyValue / SetNotificationKeys; wraps mig
│   │                              client stubs into the CF API
│   ├── SCD.c, SCDMultiple.c       Bulk SCDynamicStore variants
│   ├── SCNotify.c                 Notify rlsource + callback dispatch
│   ├── SCNetworkInterface.c       Iface enumeration (planned full surface)
│   ├── SCNetworkService.c, Set.c  Network-service / set enumeration (planned)
│   ├── SCNetworkProtocol.c
│   ├── SCNetworkConfigurationInternal.{c,h}
│   ├── SCBridgeInterface.c, SCBondInterface.c, SCVLANInterface.c
│   ├── SCPreferences.c            (deferred — backing store + RPCs not wired)
│   ├── SCInternal.h
│   ├── SystemConfiguration/       public header umbrella
│   └── *test.c                    sctest, scnotifytest, scrltest, etc.
│
└── IPConfiguration/               Standalone DHCP/RA daemon. SHIPPED through iter 6.
    ├── ipconfigd.c, ipconfig.c    daemon + CLI
    ├── ipconfig.defs              IPConfiguration's own MIG IDL (separate from
    │                              configd's)
    ├── dhcp_discover.c, ra_listen.c, lease_loop.c
    ├── arp_probe.c                RFC 5227 probe + announce (iter 6)
    ├── apply_lease.c, apply_lease_v6.c
    ├── bound_state.c              fires sc_publish on BOUND
    ├── sc_publish.{c,h}           sc_publish_ipv4 / sc_publish_ipv6
    │                              -> libSystemConfiguration -> configd via Mach
    ├── mach_service.c
    └── ...

Top-level (freebsd-launchd-mach/) hosts the launchd plist for configd (com.apple.SystemConfiguration registered via MachServices in the plist; configd calls bootstrap_check_in on the published name to obtain the receive right).

5.2 Apple source provenance

The configd source is derived from Apple's configd (latest open tag configd-963.270.3). What's retained is the surface that's directly relevant to SCDynamicStore + the configd.defs IDL; the bulky plugin tree (IPMonitor, KernelEventMonitor, LinkConfiguration, PreferencesMonitor, SCNetworkReachability, InterfaceNamer, SimulatorSupport, QoSMarking) is not present. Files that are in-tree retain their Apache 2.0 headers per-file.

6. Locked architectural decisions

7. File-by-file plan (src/configd/ + src/libSystemConfiguration/)

Apple source baseline: configd-963.270.3 (~289 files, ~5.5 MB pre-pruning). What's not in-tree: the plugin tree (IPMonitor, KernelEventMonitor, LinkConfiguration, PreferencesMonitor, SCNetworkReachability), InterfaceNamer, SimulatorSupport, QoSMarking, AirPort, Apple-Wireless-Diagnostics, Swift test harnesses, Xcode build infra.

7.1 Not imported

• configd.xcodeproj/, xcconfigs/, xcscripts/ — Xcode build infra (replaced by gmake Makefiles)
• Plugins/QoSMarking/, Plugins/SimulatorSupport/, Plugins/InterfaceNamer/ — non-goals on FreeBSD
• Plugins/IPMonitor/IPMonitorAWDReport.{c,h} — Apple-Wireless-Diagnostics
• SCTest-Swift/ — Swift test harness
• libSystemConfiguration/SCDPlugin*.{c,h} — plugin loader (deferred)

7.2 Status by component

8. FreeBSD-only deltas (vs Apple's Darwin-tied configd)

9. Dependencies

Build-time: clang, lld (FreeBSD base); mig (in-tree, builds the server + client stubs from config.defs); pkgconf; system-domain headers/libraries at /System/Library/.

Runtime (on the ISO):

• libdispatch.so — mainloop + MIG receive source.
• libCoreFoundation.so — CF types (CFString, CFDictionary, CFData) used by SCDynamicStore values.
• libxpc.so — bootstrap APIs (bootstrap_check_in); not used for XPC framing in configd itself, but present in the libxpc-bootstrap path.
• libSystemConfiguration.so — this repo's client framework; consumed by IPConfiguration and any other SCDynamicStore client.
• (when WLAN lands) wpa_supplicant from FreeBSD base — already present, untouched. Not security/wpa_supplicant from ports.

10. launchd integration

10.1 IPConfiguration plist (in place)

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>             <string>com.apple.IPConfiguration</string>
    <key>ProgramArguments</key>  <array>
        <string>/usr/libexec/IPConfiguration</string>
    </array>
    <key>RunAtLoad</key>         <true/>
    <key>KeepAlive</key>         <true/>
</dict>
</plist>

IPConfiguration runs in foreground supervised by launchd; KeepAlive=true respawns it if it dies. Apple-canonical Label.

10.2 configd plist (Mach-service shape)

<plist version="1.0">
<dict>
    <key>Label</key>            <string>com.apple.configd</string>
    <key>ProgramArguments</key> <array><string>/usr/libexec/configd</string></array>
    <key>RunAtLoad</key>        <true/>
    <key>KeepAlive</key>        <true/>
    <key>MachServices</key>     <dict>
        <key>com.apple.SystemConfiguration</key>
        <true/>
    </dict>
</dict>
</plist>

launchd registers the com.apple.SystemConfiguration Mach service at boot. configd calls bootstrap_check_in("com.apple.SystemConfiguration", &recv_port) at startup to obtain the receive right. Until configd is up, RPCs from libSystemConfiguration clients block at bootstrap_look_up (or get a queued send right depending on launchd's OnDemand semantics — tracking this in iter wash). After check-in, configd runs dispatch_source(MACH_RECV) on the port and dispatches incoming MIG messages.

11. preferences.plist schema (DEFERRED — SCPreferences)

One canonical declarative configuration file at Apple's path. The GUI tooling reads/writes it via SCPreferences*; configd loads it into Setup: keys and re-evaluates on commit. The shape below is illustrative — final shape will follow Apple's preferences.plist schema (network-service-keyed, with NetworkServices, Sets, System dicts). Until SCPreferences lands, no plist is consulted; the auto-DHCP path through IPConfiguration runs unaided.

The example below is the original FreeBSD-only sketch from the sibling repo's plan, preserved for the data-model intent only:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Hostname</key>
    <string>my-host</string>

    <key>Interfaces</key>
    <dict>
        <key>em0</key>
        <dict>
            <key>Method</key> <string>DHCP</string>
        </dict>

        <key>em1</key>
        <dict>
            <key>Method</key> <string>Static</string>
            <key>IPv4</key>
            <dict>
                <key>Address</key> <string>192.168.1.10/24</string>
                <key>Router</key>  <string>192.168.1.1</string>
            </dict>
        </dict>

        <key>wlan0</key>
        <dict>
            <key>Method</key> <string>WPA</string>
            <key>WPA</key>
            <dict>
                <key>ConfigFile</key> <string>/etc/wpa_supplicant.conf</string>
            </dict>
            <key>IPv4</key>
            <dict>
                <key>Method</key> <string>DHCP</string>
            </dict>
        </dict>
    </dict>

    <key>DNS</key>
    <dict>
        <!-- Optional. If absent, DNS is taken from DHCP. -->
        <key>Servers</key>
        <array>
            <string>1.1.1.1</string>
            <string>1.0.0.1</string>
        </array>
        <key>Search</key>
        <array><string>example.com</string></array>
    </dict>
</dict>
</plist>

Empty / absent preferences.plist → IPConfiguration's defaults apply (auto-DHCP everything, RA on every iface). The no-config-needed default; today's live behavior.

Per-iface dict missing → IPConfiguration's defaults apply for that iface. A user who wants em0 to NOT auto-DHCP would express that through the SCPreferences API once it lands.

11.1 Schema versioning

The Apple preferences.plist ships an explicit version key in its top-level dict. The port follows.

12. scutil CLI tool (FUTURE)

Apple's scutil is the system-configuration shell. Ported as a libSystemConfiguration client (which means it talks to configd over the same Mach RPC surface as every other client). Initial command set when it lands:

• scutil --show — dump the entire dynamic store
• scutil --get Hostname / --set Hostname my-host — single-key edits
• scutil --interfaces — list managed interfaces with current state
• scutil --reload — force configd to re-read SCPreferences (once SCPreferences lands)
• scutil --watch <key> — long-running, prints on store changes (via the Mach notify-port path)

The Apple interactive store-shell mode is in scope — it builds on the same MIG surface configd already speaks, so it should be straightforward.

In the meantime, the in-tree test programs (configtest, listtest, patterntest, notifytest, multitest, sctest, scnotifytest) cover most of what an early scutil would expose.

13. Licensing

Top-level BSD-2-Clause; Apple configd source files retain their Apache 2.0 headers per-file (inbound=outbound). New code is BSD-2-Clause with SPDX headers.

14. Phased delivery

15. Open questions

16. References

• This repo: github.com/pkgdemon/freebsd-launchd-mach.
• Apple configd source: github.com/apple-oss-distributions/configd (latest tag configd-963.270.3).
• Apple IPConfiguration source: github.com/apple-oss-distributions/bootp (IPConfiguration lives under bootp/IPConfiguration.bproj/).
• Sibling repo (AF_UNIX/DO track): github.com/pkgdemon/freebsd-launchd — same upstream port effort, different architecture; daemon renamed netconfigd there.
• wpa_supplicant: w1.fi/wpa_supplicant/. FreeBSD port at security/wpa_supplicant.
• Companion plans: freebsd-launchd-mach (the parent repo), hwregd (the hardware-registry daemon backing libIOKit).
• FreeBSD route(4) / PF_ROUTE: man 4 route.
• MIG IDL: man 1 mig; the regenerator runs at build-time from src/configd/config.defs.

Revision history.
2026-05-23 — Architecture pivot: refactored from the sibling AF_UNIX/DO track to freebsd-launchd-mach (v2, the Mach-IPC track). Daemon name restored to Apple-canonical configd; configd.defs MIG IDL retained verbatim; Mach service com.apple.SystemConfiguration registered via bootstrap_check_in; libSystemConfiguration.so client framework hosts the mig-generated client stubs. PARTIALLY SHIPPED: the core SCDynamicStore RPC surface is live and consumed by IPConfiguration's sc_publish_ipv4 / sc_publish_ipv6. SCPreferences, PF_ROUTE source, scutil CLI, and SCNetworkReachability are planned in subsequent iterations. The plugin loader is deferred indefinitely; IPConfiguration runs as a standalone daemon and reaches configd over Mach RPC for State:/Network/Service/<UUID>/IPv{4,6} publishes.
(previous) — Original plan filed against the sibling freebsd-launchd (AF_UNIX/DO) track; daemon renamed netconfigd; service-to-service IPC via GNUstep Distributed Objects over AF_UNIX. Superseded for this repo.