This build's wifi documentation got rewritten once the desktop environment grew a GUI network applet — not because the original instructions were wrong, but because a second, complete way to do the same thing now existed alongside the first, and the two actively fight each other if both run at once.
The original method, built first
The first working path to wifi on this system was entirely command-line: wpa_supplicant, configured by hand with a config file naming the SSID and a hashed passphrase, enabled as a systemd service tied to the specific interface name, paired with a hand-written systemd-networkd .network file for DHCP and a manual symlink to get /etc/resolv.conf pointing at systemd-resolved's runtime stub. Every piece of it had to be documented explicitly, because none of it happens automatically — the interface name, the SSID, and the passphrase are all specific to wherever this system actually gets deployed, none of which a chroot build has any way to know in advance.
What changed once NetworkManager and plasma-nm existed
Once NetworkManager and Plasma's own network applet were built and wired in, a second, complete path to the same outcome existed: click the tray icon, pick a network, enter a passphrase, done — no config file to hand-write, no interface name to look up first. Both paths reach the same place. Neither one knows the other exists.
Why they conflict instead of coexisting
wpa_supplicant, run directly as its own systemd service against a named interface, and NetworkManager, which expects to manage that same interface itself, both want exclusive control of it. Whichever one claims the interface first blocks the other from doing anything useful with it — NetworkManager shows the interface as "unmanaged" if systemd-networkd or a standalone wpa_supplicant@ service already has it, and the reverse is just as true if NetworkManager claims it first. Nothing about either mechanism warns the other away automatically; they were each designed as a complete, self-sufficient way to manage a network interface, on the reasonable assumption that nothing else was doing the same job at the same time.
What the documentation had to say explicitly
The fix wasn't technical — both mechanisms work correctly on their own. It was about making the choice visible before someone hit the conflict by accident: the rewritten instructions name both methods up front, mark the GUI path as the recommended default for an actual desktop session, and say directly that picking one means not running the other. A troubleshooting section covers the specific symptom of picking wrong — an interface showing as "unmanaged" in the network applet — and traces it back to checking for a leftover systemd-networkd config file or a still-enabled wpa_supplicant@ service, either of which needs to be disabled before NetworkManager can take over. Switching from the CLI method to the GUI one afterward is itself a small documented procedure now, not something to work out by trial and error mid-troubleshooting.
The actual lesson in the rewrite
Adding a second way to do something that already worked doesn't automatically make the system more capable — it adds a real decision a previous version of the same documentation didn't need to mention, because there was nothing to choose between yet. The wifi setup doc's job changed the moment a second working path existed: from "here are the steps" to "here are two complete sets of steps, and you need to pick exactly one before doing anything, because doing both is worse than doing either."
Leave a comment
Comments are reviewed before they appear.