NextBSD WLAN plan PHASES 0–4 MERGED AWAITING HARDWARE

Grounded in a source-level review of nextbsd-redux/{nextbsd-userland, nextbsd-kernel, nextbsd-kernel-modules, nextbsd-freebsd-compat, nextbsd, nextbsd-overlays} and gershwin-components at 2026-07-13. Background: WLAN on NextBSD — the Apple stack, whose integration half this replaces. That half was written against the pre-Mach freebsd-* / pkgdemon era and assumed dhcpcd and Distributed Objects — neither of which NextBSD uses.

1. Three blockers between "Intel card" and "IP address"

Each is independent. All three must be fixed before WLAN works at all.

1.1 wlan_xauth is missing BLOCKER SHIP THIS NOW kernel#51

Symptom

Every WPA / WPA2 / WPA3 network fails to associate. Open networks work fine. There is no useful error surfaced to the user — wpa_supplicant simply never leaves SCANNING.

Root cause

Two independent facts combine to produce this, and neither is wrong on its own:

1. wlan_xauth is not in the kernel. NextBSD's config is include GENERIC plus additions (nextbsd-kernel/config/NEXTBSD:1) — nothing wireless is excluded, and device wlan + wlan_ccmp/wlan_tkip/wlan_wep/wlan_gcmp/wlan_amrr all arrive from GENERIC. But wlan_xauth is not in GENERIC either — upstream FreeBSD deliberately leaves it out, because net80211 autoloads it as a .ko on demand. On stock FreeBSD this is invisible and self-healing.
2. NextBSD has no .ko tree to autoload from. nextbsd-kernel/ci/assemble-image.sh:168 does rm -f "$ROOTFS"/boot/kernel/*.ko — the entire module tree is deleted at image-assembly time; only .kext bundles survive. This is intentional and correct for the kext model.

Fix

# nextbsd-kernel/config/NEXTBSD
device      wlan_xauth   # 802.11 802.1x/WPA authenticator.
                         # net80211 autoloads this as a .ko on stock FreeBSD;
                         # NextBSD ships no .ko tree (assemble-image.sh:168),
                         # so it must be compiled in.

Risk: none. It is a purely additive kernel-config line that statically links a small, in-tree net80211 module that upstream ships and every other FreeBSD system loads on demand. It cannot regress the wired path, it changes no userland, and it touches no other subsystem. If WLAN is not present on a machine, the code is simply never entered.

Verification (standalone — no other phase required)

# Before: expect this to fail with "Invalid argument"
ifconfig wlan0 create wlandev iwlwifi0
wpa_supplicant -i wlan0 -c /tmp/wpa.conf -d      # never leaves SCANNING

# After: expect association to complete
wpa_cli -i wlan0 status                          # wpa_state=COMPLETED

# Sanity-check the authenticator actually registered:
sysctl net.wlan.devices                          # radio is visible
ifconfig wlan0 list caps                         # WPA/RSN advertised

wlan_acl and wlan_rssadapt are the same latent class of failure and would be reasonable to add in the same commit, but neither is needed for a station — they only matter for hostap mode and alternate rate control, so leaving them out is defensible.

1.2 Nothing creates the wlan0 VAP BLOCKER new work — wland

On FreeBSD, wlans_iwlwifi0="wlan0" in rc.conf clones the 802.11 VAP from the physical device. NextBSD has neither: nextbsd-freebsd-compat/.github/workflows/build.yml:127 hard-strips /stage/etc, installworld (not make distribution) is used deliberately so /etc content is never generated, and /sbin/init is in the superseded list because launchd is PID 1. There is no rc.d and never will be.

So ifconfig wlan0 create wlandev iwlwifi0 has no owner. This is a responsibility Apple's wifid never had — IO80211 presents en0 directly — and it means the phy→VAP lifecycle must belong to something on NextBSD. That something is wland.

1.3 ipconfigd DHCPs too early, then gives up forever BLOCKER userland#37

The trigger path has no interface-type check at all. The only filter anywhere is strncmp(ifname, "lo", 2).

Two aggravations. net80211 VAPs go through ether_ifattach, so they report IFT_ETHER — meaning even dhcp_pick_interface()'s sdl_type != 6 filter (dhcp_discover.c:111) will happily select wlan0. And the {4,8,16}s retransmit ladder means the user watches a 28-second hang before nothing happens.

1.4 The fix: gate DHCP on an AirPort key

Make ipconfigd's contract honest. Today it assumes Link{Active} means "L2 is usable for IP"; net80211's RUN state breaks that assumption for WPA. The repair is to require a second predicate — but only where a WLAN daemon has declared itself the authority.

Single file, src/IPConfiguration/sc_link_watch.c, ~70 LOC:

And the re-trigger falls out for free. wland publishes AirPort {Authenticated: false} on association and {Authenticated: true} on CTRL-EVENT-CONNECTED. That second configset is itself a change on the new pattern, so configd wakes the existing linkwatch session, evaluate_interface("wlan0") re-runs, /Link is already Active, the gate is now open → DHCP. Event-driven, no polling, no debounce, no new IPC. It also incidentally fixes the "one failed attempt then silence" hole: a re-association generates a fresh trigger even though /Link never moved.

No configd change. No ipconfig.defs change. No MIG regeneration.

2. What already exists (so we don't rebuild it)

3. Approaches ruled out (do not relitigate)

3.1 iwd DEAD

Two independent fatal blockers. It is welded to nl80211/cfg80211 — there is no net80211 backend, and iwd deliberately leans on cfg80211 semantics rather than abstracting over them, so a FreeBSD port is a rewrite of the layer the daemon is built on, not a driver shim. And it is LGPL-2.1 (can't go in base), on top of dragging in ell and D-Bus.

What survives: iwd's object model — Station / Network / KnownNetwork / Agent — maps almost one-to-one onto CoreWLAN's CWInterface / CWNetwork / credential-prompt flow, and it already contains the autojoin brain wpa_supplicant lacks. iwd contributes ideas; wpa_supplicant contributes code.

3.2 A custom supplicant seeded from Apple's sources DEAD

There is no seed. eapolclient (eap8021x) does the EAP exchange only — it derives a PMK for Enterprise networks and hands it back. It does not scan, does not associate, and does not do the 4-way handshake. All of that lives in closed wifid and IO80211 firmware offload. And eap8021x is not in the NextBSD tree at all.

So "custom wland based on Apple's supplicant" means implementing SAE/Dragonfly, the 4-way handshake and key hierarchy, PMKSA caching, PMF/802.11w, and FT from scratch — the exact code that produced KRACK and Dragonblood — in a codebase where we are the only auditor. No.

3.3 Vendoring wpa_supplicant into nextbsd-userland/src and teaching it Mach REJECTED

Four reasons, any one sufficient:

• It violates the repo's own scope. nextbsd-userland's README defines it as "Tiers 0–2 — the system layer that has no FreeBSD equivalent." wpa_supplicant is definitionally the FreeBSD thing; it already speaks net80211 through driver_bsd.c.
• CVE cadence. wpa_supplicant is the one component in the network stack where "three months behind upstream" is an exploit. Stock, a fix is a base rebuild. Vendored-and-patched, every upstream security release becomes a merge against our Mach patches, forever.
• The patch buys nothing. We need the policy brain regardless — wpa_supplicant has no autojoin, no known-networks model, no credential store, no scan list for a UI. Once wland exists, wland holds the Mach port and calls SCDynamicStoreSetValue(). A Mach-aware supplicant would duplicate a component we still have to write.
• Blast radius. It couples the most security-sensitive, most-frequently-updated daemon to the most bespoke, least-settled component (the mach.ko syscall-slot shim). A bug there should not be able to take down the supplicant.

Also don't add the port. security/wpa_supplicant is the same 2.11, but installs to /usr/local/sbin and shadows base for no benefit. (FreeBSD's official pkg repo is configured and enabled — nextbsd/build.sh:169-187 writes pkg+https://pkg.FreeBSD.org/FreeBSD:15:${ABIARCH}/latest and rebrands ABI precisely so FreeBSD:15 packages install cleanly — so ports remain available if we ever need them. We don't, here.)

4. The architecture

4.1 Why the CLI bridge, and not linking SC into the prefPane

No Gershwin process has ever spoken Mach — zero mach/, bootstrap_look_up, xpc_connection, or SystemConfiguration references anywhere in gershwin-components. And this is deliberate, not accidental: gershwin-developer/Library/Scripts/Install-System-Domain.sh:74-95 force-disables HAVE_MACH when building Gershwin's libdispatch on NextBSD, so the desktop's dispatch is isolated from the base stack's Mach one. Gershwin apps link gnustep-base's Foundation, not libCoreFoundation.so.6. PORTING.md:838-846 states the policy: "three CF lanes, one CF per binary."

Linking libSystemConfiguration + libmach into a GNUstep bundle collides head-on with that split. The cheap path is the one already in the tree: ipconfigd is a Mach daemon and ipconfig is a pure-C CLI Mach client (bootstrap_look_up at ipconfig.c:150-154). Do the same. BSDBackend.m:262-268 already invokes a privileged helper via NSTask, so a /usr/sbin/wlan binary drops straight into the existing invocation path with no ObjC↔Mach linkage problem at all.

The CoreWLAN-shaped ObjC API stays above the Mach line, where ObjC actually exists. That is also where it belongs architecturally.

5. The path DECIDED: BUILD IT PROPERLY

The two options were never competing architectures — the shortcut is a strict subset of the real thing's first phases. The only question was where to stop, and the answer is: we don't.

Why the shortcut was rejected

It doesn't actually work. That is the decisive argument, and it isn't an aesthetic one. Without wland, nothing publishes an AirPort key — so the DHCP gate in §1.4 has nothing to gate on, and every alternative is worse: hold the interface admin-down until wpa_supplicant reports CONNECTED (ugly, and racy against ipconfigd's own iface_bring_up), or let the 28-second DISCOVER ladder fail and hope for a manual retry (which the sticky-failure bug means never comes). The minimum honest shim — something that watches wpa_ctrl and publishes AirPort{Authenticated} — is wland v0. There is no cheaper thing that is also correct.

And the shortcut's end state is one we'd have to demolish. It leaves PSKs in /etc/wpa_supplicant.conf, autojoin as an integer, nothing in the dynamic store, and System Preferences shelling out through sudo -A to tools that don't exist on this system. Every one of those is later thrown away. The work isn't saved, it's deferred and then discarded.

6. Phases

Phase 0 — unblock the kernel 1 LINE · SHIP NOW

device wlan_xauth in nextbsd-kernel/config/NEXTBSD. This is not really a phase — it is a bug fix that happens to be a prerequisite. It has no dependency on Q1 (ship vs right), on wland, or on anything else in this document, and it should go in as its own PR rather than waiting for a WLAN decision. Full write-up, risk assessment, and standalone verification steps: §1.1. Ticket: nextbsd-kernel#51 (and the systemic audit, #52).

Phase 1 — prove the chain by hand

ifconfig wlan0 create wlandev iwlwifi0
ifconfig wlan0 up
wpa_supplicant -i wlan0 -c /tmp/wpa.conf -B
wpa_cli -i wlan0 status          # expect wpa_state=COMPLETED

Expect DHCP to fail here — that is the §1.3 race, and observing it is the point. Confirms driver, firmware, net80211, wlan_xauth, and the supplicant all work before any new code is written.

Phase 2 — ipconfigd: the gate + the latent bugs

The ~70-LOC sc_link_watch.c gate from §1.4, plus the pre-existing bugs in §8 — the gate does not work without them. Tickets: #37 (dead re-arm) and #38 (global single-flight) are hard blockers for the gate; #39, #40, #41 are the rest of the multi-interface debt.

Phase 3 — wland v1 (C + CoreFoundation)

/usr/sbin/wland, launchd job org.nextbsd.wland serving Mach service org.nextbsd.wlan. Responsibilities:

• VAP lifecycle — enumerate 802.11 phys, ifconfig wlanN create wlandev <phy>, destroy on removal.
• Its own PF_ROUTE listener for RTM_IFANNOUNCE — unless userland#42 lands first, in which case configd does this and wland just subscribes. Today configd's link monitor handles RTM_IFINFO only, so a VAP cloned at runtime is invisible to it until the first link-state transition, and a destroyed one leaves a stale Link key forever. Since wland is the thing doing the cloning, it must track arrivals and departures itself.
• Drive wpa_supplicant over wpa_ctrl — SCAN, SCAN_RESULTS, ADD_NETWORK, SET_NETWORK, SELECT_NETWORK; consume the async event stream (CTRL-EVENT-CONNECTED, -DISCONNECTED, -SSID-TEMP-DISABLED) off a dispatch_source on the control-socket fd. wpa_ctrl.c is BSD-licensed and small enough to compile in directly.
• Be the sole author of wpa_supplicant's network blocks. Run it with an empty config and inject everything at runtime. If wpa_supplicant.conf also carries SSIDs, two autojoin brains fight — the classic NetworkManager failure mode.
• Known networks in SCPreferences.
• Publish State:/Network/Interface/<wlan>/AirPort.

Phase 4 — the wlan CLI

/usr/sbin/wlan, a pure-C MIG client modeled on src/IPConfiguration/ipconfig.c. This is both the debugging tool (there is no scutil — see §7) and the desktop's bridge across the Mach line.

Phase 5 — System Preferences backend

A third NetworkBackend implementation (SCWLANBackend) in Network.prefPane, alongside NMBackend and BSDBackend, driving the wlan CLI from Phase 4.

This is needed rather than optional: the existing BSDBackend shells out to wpa_cli, dhclient and sysrc, none of which exist on NextBSD. So the NextBSD backend cannot be BSDBackend with tweaks — it needs something to talk to, and Phase 4 is what gives it one. The protocol itself doesn't change: scanForWLANs, connectToWLAN:withPassword:, setWLANEnabled:, savedConnections are already declared and already drive the WLAN tab.

7. Constraints that shape the code

Three more, less severe:

• No kSCEntNetAirPort. The 802.11 entity and all its property keys must be added to SCSchemaDefinitions.h. We are inventing this schema; nothing consumes it today.
• No scutil. The only mention in the tree is an .Xr scutil 8 cross-reference in configd's man page pointing at a binary that does not exist. There is no way to inspect the dynamic store ad hoc. The wlan CLI partly fills this; a general store dumper (CopyKeyList(".*") + CopyMultiple) is worth ~50 LOC on its own.
• No launchd service ordering. No StartAfter/Requires; the plist directory scan isn't even sorted. "Start after configd" is expressed as KeepAlive=true + open the SCDynamicStore lazily and tolerate NULL (sc_publish.c:136-143 is the model). Never assume configd is up in main().

7.1 The daemon recipe, concretely

Binary to /usr/sbin/wland — /System/Library holds data only (plists, kexts), never executables. A bsd.prog.mk Makefile, not CMake (CMake is used by exactly two components and the cross-toolchain file says so explicitly). Plist in overlay/System/Library/LaunchDaemons/, which ships verbatim via cp -aR overlay/. /stage/. Build block in build-userland.sh after IPConfiguration, generating MIG stubs externally and passing them in via MIGOUT=.

The link line matters and is easy to get wrong after the #378 rename:

LDADD+=  -llaunch -lsystem_kernel
LDADD+=  -lSystemConfiguration -lCoreFoundation
LDADD+=  -lsystem_dispatch -l:libsystem_blocks.so
CFLAGS+= -fblocks
WARNS=   0                       # CF public headers are not -Werror clean
BINDIR=  /usr/sbin

8. ipconfigd debt that WLAN forces us to pay

Both bugs are pre-existing and independent of WLAN. Both will defeat the §1.4 gate if left alone. Neither has been noticed because NextBSD has only ever been tested on a single wired NIC.

Related, and the next thing to break: State:/Network/Global/IPv4 is last-binder-wins. sc_publish.c:230-235 has ipconfigd declare whichever service just bound to be primary — the comment admits it. There is no IPMonitor, no service-order arbitration anywhere. mDNSResponder and hostnamed both read that key. Wired-only, nobody noticed. Add WLAN and "primary interface" is a race.

The honest read: ipconfigd is currently a single-interface wired-desktop daemon, and WLAN is what forces it to grow up. Also unhandled and worth knowing: no teardown on link-down (address and default route stay installed), no SIOCDIFADDR/RTM_DELETE/DHCPRELEASE anywhere, and /etc/resolv.conf is rewritten on bind but not on renew — so a renewal that changes DNS servers updates the store and not the resolver.

9. Hardware scope

10. Tickets

Filed 2026-07-13. Every one of these is a real bug independent of WLAN — they are all currently masked by the fact that NextBSD has only ever been exercised on a single wired NIC. WLAN is simply what makes them reachable. They are the foundation, and they go in before wland.

Foundation — must land first

Multi-interface debt — same root cause, do them together

Systemic / scope

11. Open questions

12. Provenance

Written 2026-07-13 against these trees at these commits:

What this supersedes

The companion research doc — now WLAN on NextBSD — the Apple stack, and why we use wpa_supplicant, renamed from freebsd-wifi-management.html → nextbsd-wifi-research.html → its current name — remains correct on Apple's stack, what's open source, the wpa_supplicant/iwd comparison, and the glossary. Its integration sections (old §4 "What this project ships today", §5 "Hypothetical wifid-fbsd", §7 "Open questions") have been deleted, not just flagged, because they asserted the following — all false on NextBSD:

• "wpa_supplicant from ports… already in pkglist.txt alongside dhcpcd" — NextBSD does not use dhcpcd. nextbsd/README.md:33 explicitly lists dhcpcd among the DHCP clients replaced by ipconfigd. And wpa_supplicant comes from base, not ports.
• "dhcpcd's built-in wpa_supplicant hook gates DHCP behind ASSOCIATED — out-of-the-box pairing, no extra glue" — that hook does not exist here. This was the doc's entire argument for not building a wland, and it rested on a component NextBSD doesn't ship.
• "Exposes a CoreWLAN-equivalent API over DO IPC (consistent with the project's Mach-IPC-replacement choice)" — the project went Mach. configd is a MIG server on com.apple.SystemConfiguration.configd. Distributed Objects was the abandoned sibling track.
• The ObjC @protocol NCWLANClient sketch — there is no ObjC runtime in nextbsd-userland.
• "wland is a cosmetic / API-symmetry investment, not a functional one" — false. Without something publishing an association-complete signal, DHCP on WLAN does not work at all.

Companion plans: configd (note: its repo pointer at pkgdemon/freebsd-launchd-mach is stale — the code now lives at nextbsd-redux/nextbsd-userland) · IPConfiguration · launchd (Mach) · Keychain