NixOS 无线网络配置完全指南wpa_supplicant 的声明式、命令式与企业级接入实战【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs本指南以 NixOS 官方手册 wireless.section.md 为骨架围绕networking.wireless这一核心模块展开系统讲解如何在 NixOS 中管理 WiFi 网络从声明式定义网络、用wpa_passphrase预计算密钥、通过secretsFile安全托管密码到无重建即时连网的wpa_cli命令式配置以及面向校园网/企业网EAP-PEAP与 PKCS#11 智能卡/TPM 的高级接入方案。读完本文你将掌握 wpa_supplicant 在 NixOS 中的完整配置链路并能在 wpa_supplicant.nix 源码与 wpa_supplicant 测试 的印证下理解每个选项背后的生成逻辑与安全边界。两种无线管理方案的选择NixOS 桌面安装例如 GNOME、KDE通常会使用 NetworkManager。这种情况下只需将当前用户加入networkmanager组即可直接在系统设置Settings应用里完成无线网络的连接与切换无需任何 NixOS 配置{ users.users.alice.extraGroups [ networkmanager ]; }除此之外NetworkManager 还支持将部分无线网络直接写进 NixOS 配置声明式管理通过networking.networkmanager.ensureProfiles.profiles以 keyfile 风格定义连接配置connection.type wifi、wifi.ssid、wifi-security.psk等并可借助ensureProfiles.environmentFiles以环境变量方式注入密码避免明文落入 Nix store。相关选项定义见 networkmanager.nix。若不想引入 NetworkManager 这样的大块头依赖则可以退回到轻量方案——由wpa_supplicant直接管理无线接口。这是本文的主体只需一行配置即可启用{ networking.wireless.enable true; }启用后NixOS 会创建系统用户wpa_supplicant、系统组wpa_supplicant安装wpa_supplicant软件包并注册相应的 systemd 服务见 wpa_supplicant.nix。指定无线接口与多接口服务默认情况下wpa_supplicant 会自动管理第一个可用的无线接口。但从可靠性出发官方文档明确建议通过networking.wireless.interfaces显式指定接口名。源码中对应选项的说明指出若接口列表为空且autoDetectInterfaces默认true开启则 wpa_supplicant 会自动接管所有无线接口并在启动脚本中借助udevadm monitor等待无线网卡出现、动态拼装-i参数见 wpa_supplicant.nix。配置多个接口时NixOS 会为每个接口生成独立的 systemd 服务实例见 wpa_supplicant.nix{ networking.wireless.interfaces [ wlan0 wlan1 ]; }上述配置会分别生成wpa_supplicant-wlan0.service与wpa_supplicant-wlan1.service。同时需要注意多接口与 D-Bus 控制dbusControlled默认在接口数少于 2 时为true互斥配置层面对此设有断言见 wpa_supplicant.nix此外当接口列表为空时NixOS 还会写入 udev 规则在 wlan 设备热插拔时自动try-restart守护进程见 wpa_supplicant.nix。声明式配置无线网络NixOS 允许把需要自动连接的网络全部写死在配置中通过networking.wireless.networks属性集声明每个属性名默认为 SSID{ networking.wireless.networks { # SSID 不含空格或特殊字符可直接作为属性名 echelon { psk abcdefgh; }; # SSID 含空格和/或特殊字符必须用引号包裹属性名 echelons AP { psk ijklmnop; }; # 隐藏 SSID 的网络需要 hidden true echelon { hidden true; psk qrstuvwx; }; free.wifi { }; # 公共开放网络无需认证 }; }示例中同名 SSIDechelon在 Nix 属性集中重复定义时后一个会覆盖前一个实际配置请为每个网络使用唯一键名。free.wifi { };表示无认证的开放网络生成的 wpa_supplicant 网络块中key_mgmtNONE。每个网络块支持的选项源码中每个网络的子模块选项见 wpa_supplicant.nix还包括选项类型/默认值说明ssid字符串默认属性名覆盖网络块的 SSID可用于区分同名但密码不同的 APbssid字符串或null指定 BSSID 后仅连接该 AP可用于同 SSID 多接入点的精确选择psk8~63 个可打印字符明文预共享密钥WPA/WPA2/WPA3-PSK 口令与pskRaw、auth互斥pskRaw64 位十六进制或ext:名字预计算的原始 PSK或指向 secretsFile 中变量的外部引用auth字符串多行企业级认证的自由文本块例如 EAP 相关配置与psk、pskRaw互斥authProtocols枚举列表对应key_mgmt默认WPA-PSK、WPA-EAP、SAE及各自 802.11rFT-*变体hidden布尔默认false隐藏 SSID 时置true生成scan_ssid1priority整数或null优先级组值越大越先匹配扫描结果extraConfig字符串追加到该网络块的额外 wpa_supplicant 配置行需要说明的是psk、pskRaw、auth三者互斥由断言保证见 wpa_supplicant.nix同时psk有长度 8–63 字符的格式校验pskRaw必须是 64 位十六进制或ext:前缀形式。使用 pskRaw 与 wpa_passphrase 预计算密钥对于 WPA2 网络预共享密钥既可以用可读口令psk也可以用 64 位十六进制的原始 PSKpskRaw。使用pskRaw有两个好处一是口令不会以明文出现在配置与 Nix store 中起到一定混淆作用二是连接时无需每次都从口令派生密钥可略微加快连接速度。pskRaw的值可用wpa_passphrase工具计算得到$ wpa_passphrase ESSID PSK network{ ssidechelon #pskabcdefgh pskdca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435 }将输出中的psk值填入配置{ networking.wireless.networks.echelon { pskRaw dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435; }; }注意wpa_passphrase命令中的ESSID与PSK仅是命令行占位参数请替换为真实 SSID 与口令pskRaw中的十六进制串与具体 SSID 强绑定换网络需重新计算。全局与单网络 extraConfig除了结构化的选项wpa_supplicant 还允许注入任意原生配置行。networking.wireless.extraConfig作用于全局而每个网络块内的extraConfig只追加到该网络。官方文档给出的例子是 MAC 地址随机化{ networking.wireless.extraConfig # 默认启用 MAC 地址随机化 mac_addr1 ; networking.wireless.networks.home { psk abcdefgh; extraConfig # 在家使用真实 MAC 地址 mac_addr0 ; }; }从源码看全局extraConfig会原样追加到生成的/etc/wpa_supplicant/nixos.conf末尾见 wpa_supplicant.nix网络级extraConfig则会逐行缩进塞进对应network{ ... }块内见 wpa_supplicant.nix。更多可用选项请参考wpa_supplicant.conf(5)手册。提示NixOS 生成的完整 wpa_supplicant 配置会链接到/etc/wpa_supplicant/nixos.conf方便随时查看与排查。用 secretsFile 安全托管密钥前面所有例子中PSK 都会以明文写入 Nix store本机所有用户均可读取。因此官方文档强烈建议改用networking.wireless.secretsFileext:语法托管敏感信息{ networking.wireless.secretsFile /run/secrets/wireless.conf; networking.wireless.networks { home { pskRaw ext:psk_home; }; work.auth eapPEAP identitymy-userexample.com passwordext:pass_work ; }; }其中/run/secrets/wireless.conf的内容为变量名值格式psk_homemypassword pass_workmyworkpassword两个要点文件权限与归属secrets 文件应仅由wpa_supplicant用户可读建议chown wpa_supplicant:wpa_supplicant并设置 0600 权限。从源码看该文件会通过BindReadOnlyPaths以只读方式挂载进加固后的服务沙箱见 wpa_supplicant.nix并生成ext_password_backendfile:${cfg.secretsFile}配置行启用外部密码后端见 wpa_supplicant.nix。ext:适用范围有限只有部分字段支持该语法如psk、pskRaw、sae_password、passwordssid不支持。pskRaw中的外部引用既可以是明文口令也可以是预计算的原始 PSK。顺带一提旧选项networking.wireless.environmentFile已在新版中移除迁移路径即改为上述secretsFilepskRaw ext:...的写法见 wpa_supplicant.nix。命令式配置免重建即时连网有时尤其是尚未联网时希望不重建系统就临时加入一个新网络。将networking.wireless.userControlled设为true后wpa_supplicant组的用户即可通过wpa_cli/wpa_gui命令式地操作 wpa_supplicant{ networking.wireless.userControlled true; }从源码看该选项会向生成的配置写入ctrl_interface/run/wpa_supplicant/control、ctrl_interface_groupwpa_supplicant与update_config1见 wpa_supplicant.nix并在服务启动前创建带正确属主的客户端 socket 目录/run/wpa_supplicant/client见 wpa_supplicant.nix。历史遗留的userControlled.enable/userControlled.group写法仍被兼容但 group 已固定为wpa_supplicant。随后即可用wpa_cli交互式添加并连接网络# wpa_cli Selected interface wlan0 Interactive mode add_network 10 set_network 10 ssid echelon OK set_network 10 psk abcdefgh OK select_network 10 OK注意这些临时改动在 wpa_supplicant 重启后会全部丢失。若希望既保留声明式网络、又允许命令式网络的持久化需要开启networking.wireless.allowAuxiliaryImperativeNetworks从而允许使用wpa_cli的save命令或直接编辑/etc/wpa_supplicant/imperative.conf。从源码看该选项会让守护进程以-c /etc/wpa_supplicant/imperative.conf -I /etc/wpa_supplicant/nixos.conf方式启动——即以 imperative 文件为主配置、声明式文件作为辅助 include见 wpa_supplicant.nix并在 ExecStartPre 中预建带wpa_supplicant属主、664 权限的 imperative 配置文件见 wpa_supplicant.nix。测试用例 wpa_supplicant.nix 也验证了普通用户alice通过wpa_cli add_network/set_network/save_config后改动确实写入了/etc/wpa_supplicant/imperative.conf。重要手动编辑imperative.conf后需要重启守护进程才生效。若设置了interfaces请按对应实例重启# systemctl restart wpa_supplicant.service或# systemctl restart wpa_supplicant-interface.service企业级网络EAP-PEAP 与自由文本 auth对于 eduroam、企业 WiFi 等采用复杂认证协议的网络可借助网络块中的自由文本auth选项直接书写 wpa_supplicant 配置{ networking.wireless.networks { eduroam.auth key_mgmtWPA-EAP eapPEAP identityalice.smithexample.com passwordveryLongPassword$!3 ca_cert/etc/wpa_supplicant/eduroam.pem ; }; }源码中auth内容会按行拆分并原样插入网络块见 wpa_supplicant.nix同时自动生成key_mgmt行默认协议列表中包含WPA-EAP、FT-EAP等。可用的认证配置项与更多示例请参考wpa_supplicant.conf(5)手册页。密码等敏感字段同样建议改用ext:外部引用如passwordext:pass_work避免明文进入 Nix store。安全加固与 PKCS#11 令牌接入默认开启的沙箱加固默认情况下NixOS 会对 wpa_supplicant 守护进程应用严格的 systemd 安全加固限制其对文件、设备与网络能力的访问具体包括以wpa_supplicant非特权用户运行、仅保留CAP_NET_ADMIN/CAP_NET_RAW能力、RootDirectory/run/wpa_supplicant沙箱、ProtectSystemstrict、PrivateDevices、RestrictAddressFamilies收窄地址族、IPAddressDenyany、SystemCallFilter等一系列措施见 wpa_supplicant.nix。由此带来两个实操约束文中企业网络示例里的证书等文件必须能被wpa_supplicant用户读取建议统一存放在/etc/wpa_supplicant目录该目录通过BindPaths挂载进沙箱。若某些认证协议需要额外访问而无法显式授权只能关闭加固{ networking.wireless.enableHardening false; }该设置同样作用于由 NetworkManager 管理的无线网络——除非其 WiFi 后端不是 wpa_supplicant见networking.networkmanager.wifi.backend选项。PKCS#11智能卡与 TPM 上的 EAP-TLSnetworking.wireless.pkcs11.enable可以让 wpa_supplicant 通过 OpenSSL 的 pkcs11 引擎使用 PKCS#11 令牌如智能卡、TPM上的客户端密钥完成 EAP-TLS 认证。开启后服务环境会设置OPENSSL_ENGINES指向 libp11 的引擎目录见 wpa_supplicant.nix加固沙箱内默认提供/etc/tpm2_pkcs11数据库目录与 pcscd socket若数据库在其他位置必须显式挂载例如{ systemd.services.wpa_supplicant.serviceConfig.BindPaths [ /var/lib/tpm2_pkcs11 ]; }无图说明本文主题为纯配置类文档仓库内无与该主题强相关的架构图或截屏图片故不插入图片以文字与代码示例完整呈现全部要点。进阶选项速览除文档正文覆盖的选项外源码中还实现了若干值得了解的能力见 wpa_supplicant.nixfallbackToWPA2默认true当 WPA3 认证失败时自动回退到 WPA2。模块会为混合 WPA2/WPA3 网络额外生成一个去掉 SAE/FT-SAE 协议的降级网络块并适当提高原网络优先级见 wpa_supplicant.nix。若担心降级攻击可将此选项关闭。测试 basic 断言了混合网络会生成两个配置块。authProtocols精确控制key_mgmt协议列表WPA-PSK、WPA-EAP、SAE、OWE、DPP等 20 余种枚举值用于强制 WPA3-SAE 或兼容旧网卡。bssidpriority同一 SSID 下按 BSSID 精确锁定 AP 并按优先级选择测试 bssidGuard 验证了该行为。extraConfigFiles额外加载的 wpa_supplicant 配置文件通过-I参数引入见 wpa_supplicant.nix。scanOnLowSignal默认true信号变差时周期性扫描更优 AP生成bgscansimple:30:-70:3600见 wpa_supplicant.nix。driver默认nl80211,wext强制指定驱动。验证与参考模块完整实现nixos/modules/services/networking/wpa_supplicant.nix集成测试含 mac80211_hwsim hostapd 模拟 AP、SAE/WPA2 连接、命令式配置、BSSID 选择等nixos/tests/wpa_supplicant.nixNetworkManager 声明式 profile 选项nixos/modules/services/networking/networkmanager.nix官方手册原文nixos/doc/manual/configuration/wireless.section.md底层配置语法细节请查阅wpa_supplicant.conf(5)手册。至此从桌面场景的 NetworkManager 一行接入到 wpa_supplicant 的声明式、命令式与企业级EAP/PKCS#11配置再到密钥安全的secretsFile托管与默认沙箱加固的边界NixOS 无线网络的完整配置链路已经清晰可循。修改配置后执行sudo nixos-rebuild switch即可生效。【免费下载链接】nixpkgsNix Packages collection NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考