FreeBSD configd — porting plan

A two-layer network and system-configuration stack for FreeBSD. The lower layer (Phase 1, shipped) is dhcpcd in master mode + wpa_supplicant — both run directly by launchd, handling DHCPv4/v6/RA/SLAAC, link-state, hot-plug, and WiFi association. The upper layer (Phase 2+, planned) is a port of Apple's configd as netconfigd, providing a SystemConfiguration-like dynamic store, Distributed Objects IPC for scutil and GUI tooling, and a declarative Network.plist watcher that translates user intent into dhcpcd.conf overrides. Companion to the freebsd-launchd 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 (Phase 1 shipped), and grows over Phase 2+ a SystemConfiguration-equivalent layer on top — declarative config via Network.plist, a clean ObjC API for GUI tooling, and a scutil-equivalent CLI — while delegating the protocol-level work (DHCP, RA, WiFi association) to the well-maintained ports daemons that already handle it.

1.2 Non-goals (this iteration)

• No internal DHCP client. dhcpcd handles DHCPv4 + DHCPv6 in one daemon, including RDNSS, DNSSL, lease renewal, IPv4LL, link-state recovery. Re-implementing this inside netconfigd would burn months for no measurable gain.
• No internal RA processing. dhcpcd parses RAs in userspace — supports prefix info, RDNSS (RFC 8106), DNSSL, route preferences. The kernel's accept_rtadv path doesn't.
• No AirPort / CoreWLAN. WiFi authentication is delegated to wpa_supplicant. dhcpcd auto-coordinates with wpa_supplicant via its built-in hook for wifi-iface DHCP after association.
• No IOKit. Apple's InterfaceNamer uses IOKit to assign persistent names; FreeBSD names interfaces in-kernel.
• No Mach IPC. Same project rule: every mach/... include and every .defs file is amputated. NSConnection over AF_UNIX is the IPC.
• No XPC. Distributed Objects covers the same use cases.
• 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. Network.plist is the only declarative config netconfigd reads.

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 — IPConfiguration agent (DHCP/RA) lives inside the configd process. That's twenty years of Apple-internal work. FreeBSD's stack has a different shape: dhcpcd already does what IPConfiguration does, including features (DHCPv6, IPv4LL, RDNSS in userspace, master-mode hot-plug) that took Apple a long time to add. We get those for free by running dhcpcd directly, and free our netconfigd work for what's actually missing on FreeBSD: the SystemConfiguration layer (dynamic store + DO IPC + declarative config) on top.

The boundary between layers is clean: dhcpcd owns actions (acquire lease, configure address, follow link state); netconfigd owns policy (read Network.plist, decide what to ask dhcpcd to do, expose state to clients). They communicate via dhcpcd's existing config files + signals + lease-state files; netconfigd doesn't need to talk a custom protocol to dhcpcd.

3. Layer 1 (Phase 1, shipped): dhcpcd + wpa_supplicant

3.1 dhcpcd master mode

Run directly by launchd via /System/Library/LaunchDaemons/org.freebsd.dhcpcd.plist. ProgramArguments=["/usr/local/sbin/dhcpcd", "-B"] — the -B flag keeps dhcpcd in foreground so launchd's KeepAlive=true can supervise it. Master mode (no iface argument) means dhcpcd:

• Discovers every current network interface at startup.
• Watches RTM_NEWLINK/equivalent for new ifaces appearing (hot-plug USB ethernet, etc.).
• Runs DHCPv4 + DHCPv6 + RA processing on each iface as appropriate.
• Recognizes FreeBSD's bridge/lagg/vlan layering — DHCP runs at the bridge level (not on members), at the lagg level (not on members), and on each VLAN iface independently.
• Handles link-state changes: cable yanked → keeps lease state, stops sending packets; cable reconnected → re-acquires.
• Falls back to IPv4LL (169.254.x.x) when no DHCP server responds — covers Bonjour-only network segments.
• Clears IFDISABLED on the iface before sending IPv6 packets — we don't have to add -ifdisabled to ifconfig invocations.

3.2 wpa_supplicant from ports

Listed in pkglist.txt. Installs to /usr/local/sbin/wpa_supplicant, supersedes the base version. Reasons: faster WPA3-SAE / OWE feature uptake, current EAP method support, more aggressive CVE backports. dhcpcd has a built-in wpa_supplicant hook that detects the control socket and gates DHCP behind ASSOCIATED state — out-of-the-box pairing.

Phase 1 doesn't ship a launchd plist for wpa_supplicant. SSID configuration is still user-driven via /etc/wpa_supplicant.conf or wpa_cli. Phase 2+ will introduce a netconfigd-managed flow where Network.plist declares wpa_supplicant config that netconfigd materializes and starts wpa_supplicant per wifi iface.

3.3 What netconfigd is NOT doing in Phase 1

The Phase 1 NCDaemon is a stub:

- (void)start {
    NSLog(@"netconfigd: Phase 1 placeholder (pid=%d)", getpid());
    NSLog(@"netconfigd: network auto-config is dhcpcd's job; "
          @"this stub exits cleanly until Phase 2");
}

It doesn't get launched (no plist references it). It builds and installs to /usr/libexec/netconfigd just to keep the configd build pipeline live; the binary sits unused until Phase 2 swaps it for the real implementation. Apple's imported source under configd/src/ is intact and ready for Phase 2 work to begin against.

4. Layer 2 (Phase 2+, planned): netconfigd

The Apple configd port resumes in Phase 2. End state: a launchd-supervised long-running daemon that reads /Local/Library/Preferences/Network.plist, exposes DO IPC, and translates declarative config into dhcpcd / wpa_supplicant / kernel state. Distinct from the original plan in that it does not spawn DHCP/RA/WiFi children itself — it shapes what the lower layer does via files and signals.

4.1 Dynamic store, GNUstep-flavored

Apple's configd publishes state to the SystemConfiguration "dynamic store" — a key-value space (keys like State:/Network/Interface/en0/IPv4) that processes subscribe to. We keep the same key naming for compatibility-of-mental-model, back it with an NSMutableDictionary protected by a serial dispatch queue. Subscribers register interest via the DO connection; NSDistributedNotificationCenter-style fan-out notifies them when subscribed keys change.

Sources of state:

• PF_ROUTE socket: address adds/removes, link-state, route changes → populate State:/Network/Interface/<iface>/IPv{4,6}.
• dhcpcd's lease files in /var/db/ (or a ZeroMQ-style hook script dhcpcd runs on lease events): populate State:/Network/Service/<uuid>/DHCP.
• wpa_supplicant control socket: populate State:/Network/Interface/<iface>/WiFi with associated SSID + auth state.
• Network.plist: populate Setup:-prefixed keys with the user's declared config.

4.2 Translation: Network.plist → dhcpcd.conf

netconfigd's main outbound effect on the lower layer. When Network.plist changes:

1. Read the plist via NSPropertyListSerialization.
2. Compute desired dhcpcd config: per-iface static addresses (static ip_address=...), DNS overrides (static domain_name_servers=...), iface excludes (denyinterfaces ...), per-iface profiles.
3. Write to /etc/dhcpcd.conf.d/netconfigd.conf (drop-in path dhcpcd reads).
4. Send SIGHUP to dhcpcd's pid (in /var/run/dhcpcd.pid); dhcpcd re-reads config.

For DNS specifically: dhcpcd writes /etc/resolv.conf via resolvconf(8) by default. If Network.plist declares DNS.Servers, netconfigd merges those with DHCP-supplied servers and either uses dhcpcd's nooption domain_name_servers + static domain_name_servers=... shape, or takes resolv.conf ownership directly via nohook resolv.conf in dhcpcd.conf and writes resolv.conf itself.

4.3 Event sources

5. Repository

5.1 Layout under freebsd-launchd/configd/

freebsd-launchd/configd/
├── Makefile                       gmake build, installs to /usr/libexec/netconfigd
├── compat/                        FreeBSD shims for Apple-internal headers
├── scripts/import-source.sh       (Phase 0) clones apple-oss-distributions/configd
└── src/                           Apple configd-963.270.3 (post-amputation)
    ├── configd.tproj/
    │   ├── main.m                 (Phase 1) Foundation entry, calls NCDaemon
    │   ├── NCDaemon.{h,m}         (Phase 1) stub; Phase 2 grows it
    │   ├── _SC_dynamicStore_*.{c,h}  (Phase 2) ObjC rewrite
    │   └── ...                    Apple imports, Mach paths amputated
    ├── Plugins/
    │   ├── IPMonitor/             (Phase 2 port — repurposed for resolv.conf merge)
    │   ├── KernelEventMonitor/    (Phase 2 rewrite — PF_ROUTE source)
    │   ├── LinkConfiguration/     (Phase 2 port)
    │   ├── PreferencesMonitor/    (Phase 2 port — Network.plist watcher)
    │   └── SCNetworkReachability/ (Phase 2 port — DO API)
    ├── libSystemConfiguration/
    ├── nwi/
    ├── scutil.tproj/              (Phase 2 port — DO client)
    ├── SystemConfiguration.fproj/
    ├── common/
    └── logging/

Top-level (freebsd-launchd/) hosts:

• overlays/System/Library/LaunchDaemons/org.freebsd.dhcpcd.plist — Phase 1, in place.
• overlays/System/Library/LaunchDaemons/org.freebsd.netconfigd.plist — removed in Phase 1; will return in Phase 2.
• pkglist.txt — lists dhcpcd + wpa_supplicant.
• build.sh — chroot-side, runs make-configd.sh after launchd build to keep the configd build live; the resulting binary is unused in Phase 1.

5.2 How build.sh handles configd

Same chroot session that builds launchd + kmodloader. build.sh rsyncs configd/ into chroot:/tmp/configd/ and runs make-configd.sh against the just-installed Foundation/libdispatch. Installs to /usr/libexec/netconfigd.

6. Locked architectural decisions

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

Imported source: Apple configd-963.270.3. 289 source files; ~5.5 MB. Phase 0 amputation already done (drops the wholly-Mach files and explicit non-goals: AirPort, IOKit-based InterfaceNamer, SimulatorSupport, QoSMarking). What remains needs Phase 2 work.

7.1 Already deleted on import

• configd.xcodeproj/, xcconfigs/, xcscripts/ — Xcode build infra
• **/*.defs — MIG interface definitions (Mach-RPC IDL)
• configd.tproj/_SC_*.{c,h} Mach-IPC plumbing — entire IPC server replaced by DO
• Plugins/QoSMarking/, Plugins/SimulatorSupport/, Plugins/InterfaceNamer/
• Plugins/IPMonitor/IPMonitorAWDReport.{c,h} — Apple-Wireless-Diagnostics
• SCTest-Swift/ — Swift test harness
• libSystemConfiguration/SCDPlugin*.{c,h} — Mach-style plugin loader

7.2 Retained — Phase 2 fate

Total post-Phase-2: roughly 13-14k LOC vs Apple's ~37k pre-amputation. Slightly less than the original estimate because IPMonitor's role shrank with dhcpcd taking the IPConfiguration burden.

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

9. Dependencies

Build-time: clang, lld (FreeBSD base); the gnustep-make framework already installed by the launchd build; pkgconf; system-domain headers/libraries at /System/Library/.

Runtime (Phase 1, on the ISO):

• Ports: net/dhcpcd, security/wpa_supplicant (in pkglist.txt).
• Base: resolvconf(8) (used by dhcpcd to write /etc/resolv.conf via standard hooks).

Runtime (Phase 2+, when netconfigd ships):

• Above plus: libdispatch.so, libgnustep-base.so, libgnustep-corebase.so, libobjc.so, libBlocksRuntime.so (all from system domain — already present from launchd).

10. launchd integration

10.1 Phase 1: dhcpcd plist (in place)

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>             <string>org.freebsd.dhcpcd</string>
    <key>ProgramArguments</key>  <array>
        <string>/usr/local/sbin/dhcpcd</string>
        <string>-B</string>
    </array>
    <key>RunAtLoad</key>         <true/>
    <key>KeepAlive</key>         <true/>
</dict>
</plist>

-B keeps dhcpcd in foreground for launchd supervision; without it dhcpcd would daemonize on its own and launchd would think the job ended. KeepAlive=true respawns dhcpcd if it dies.

10.2 Phase 2+: netconfigd plist (planned)

<plist version="1.0">
<dict>
    <key>Label</key>            <string>org.freebsd.netconfigd</string>
    <key>ProgramArguments</key> <array><string>/usr/libexec/netconfigd</string></array>
    <key>RunAtLoad</key>        <true/>
    <key>KeepAlive</key>        <true/>
    <key>Sockets</key>          <dict>
        <key>Listeners</key>    <dict>
            <key>SockPathName</key> <string>/var/run/netconfigd.sock</string>
            <key>SockType</key>     <string>stream</string>
            <key>SockPathMode</key> <integer>438</integer> <!-- 0666 -->
        </dict>
    </dict>
</dict>
</plist>

launchd opens the AF_UNIX listener at boot, hands the fd to netconfigd via the launchd-port's launch_activate_socket-equivalent. Until netconfigd is up, queued connections from scutil / GUI tools sit in the kernel's socket queue.

11. Network.plist schema (Phase 2+)

One canonical declarative configuration file. The GUI tooling reads/writes it; netconfigd watches it and translates to dhcpcd config + resolv.conf.

<?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 Network.plist → dhcpcd's defaults apply (auto-DHCP everything, RA on every iface). This is the Phase 1 behavior; Phase 2+ keeps it as the no-config-needed default.

Per-iface dict missing → dhcpcd's defaults apply for that iface. A user who wants em0 to NOT auto-DHCP adds {"Method": "Disabled"}, which translates to denyinterfaces em0 in the generated dhcpcd.conf.

11.1 Schema versioning

Add a top-level "Version" key (integer) once we have post-v1 schema changes. v1 is implicit; v2+ ships the daemon's accepted version range.

12. scutil CLI tool (Phase 2+)

Apple's scutil is the system-configuration shell. Ported as a DO client of netconfigd. Initial command set:

• 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 netconfigd to re-read Network.plist
• scutil --watch <key> — long-running, prints on store changes

The interactive Mach-shell mode is dropped (depended on Mach store semantics).

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

• Apple source: github.com/apple-oss-distributions/configd (latest tag configd-963.270.3).
• dhcpcd: roy.marples.name/projects/dhcpcd/. Master-mode docs in man 8 dhcpcd; config reference in man 5 dhcpcd.conf.
• wpa_supplicant: w1.fi/wpa_supplicant/. FreeBSD port at security/wpa_supplicant.
• Companion plans: freebsd-launchd, freebsd-kmodloader.
• GNUstep base: github.com/gnustep/libs-base.
• FreeBSD route(4) / PF_ROUTE: man 4 route.