nixos/doc: improve networking.wireless chapter (#483534)

# Wireless Networks {#sec-wireless}

For a desktop installation using NetworkManager (e.g., GNOME), you just

have to make sure the user is in the `networkmanager` group and you can

skip the rest of this section on wireless networks.

For a desktop installation using NetworkManager (e.g., GNOME or KDE), you should

make sure the user is in the `networkmanager` group and you can just configure

wireless networks from the Settings app.

It is also possible to declare (some) wireless networks from the NixOS

configuration with [](#opt-networking.networkmanager.ensureProfiles.profiles).

NixOS will start wpa_supplicant for you if you enable this setting:

Alternatively, without NetworkManager, you can configure wireless networks

using wpa_supplicant by setting

```nix

{ networking.wireless.enable = true; }

```

NixOS lets you specify networks for wpa_supplicant declaratively:

By default, wpa_supplicant will manage the first wireless interface that becomes

available. It is however recommended to set the desired interface name with

[](#opt-networking.wireless.interfaces), as it is more reliable.

If multiple interfaces are set, NixOS will create a separate systemd service

for each one of them, for example:

```nix

{

  networking.wireless.interfaces = [

    "wlan0"

    "wlan1"

  ];

}

```

results in `wpa_supplicant-wlan0.service` and `wpa_supplicant-wlan1.service`.

## Declarative configuration {#sec-wireless-declarative}

NixOS lets you specify networks declaratively:

```nix

{

}

```

Be aware that keys will be written to the nix store in plaintext! When

no networks are set, it will default to using a configuration file at

`/etc/wpa_supplicant.conf`. You should edit this file yourself to define

wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).

If the network is using WPA2, the pre-shared key (PSK) can be also specified

with the `pskRaw` option as 64 hexadecimal digits.

This is useful to both obfuscate passwords and make the connection slightly

faster, as the key doesn't need to be derived every time.

If you are using WPA2 you can generate pskRaw key using

`wpa_passphrase`:

The `pskRaw` values can be calculated using the `wpa_passphrase` tool:

```ShellSession

```console

$ wpa_passphrase ESSID PSK

network={

        ssid="echelon"

```nix

{

  networking.wireless.networks = {

    echelon = {

  networking.wireless.networks.echelon = {

    pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";

  };

}

```

Other wpa_supplicant configuration can be set using the {option}`extraConfig`

option, either globally or per-network. For example:

```

{

  networking.wireless.extraConfig = ''

    # Enable MAC address randomization by default

    mac_addr=1

  '';

  networking.wireless.networks.home = {

    psk = "abcdefgh";

    extraConfig = ''

      # Use the real MAC address at home

      mac_addr=0

    '';

  };

}

```

::: {.note}

The generated wpa_supplicant configuration file is linked to

`/etc/wpa_supplicant/nixos.conf` for easier inspection.

:::

Be aware that in the previous examples the keys would be written to the Nix

store in plain text and readable to every local user.

It is recommended to specify secrets (PSKs, passwords, etc.) in a safe way using

[](#opt-networking.wireless.secretsFile) and the `ext:` syntax. For example:

```nix

{

  networking.wireless.secretsFile = "/run/secrets/wireless.conf";

  networking.wireless.networks = {

    home = {

      pskRaw = "ext:psk_home";

    };

    work.auth = ''

      eap=PEAP

      identity="my-user@example.com"

      password=ext:pass_work

    '';

  };

}

```

or you can use it to directly generate the `wpa_supplicant.conf`:

where `/run/secrets/wireless.conf` contains

```

psk_home=mypassword

pass_work=myworkpassword

```

::: {.note}

The secrets file should be owned and placed in a location accessible (only) by

the `wpa_supplicant` user. Only certain fields support the `ext:` syntax,

for example `psk`, `sae_password` and `password`, but not `ssid`.

:::

## Imperative configuration  {#sec-wireless-imperative}

```ShellSession

# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

It can be useful to add a new network without rebuilding the NixOS

configuration, particularly if you don't yet have Internet access.

Setting [](#opt-networking.wireless.userControlled) to `true` will allow users

of the `wpa_supplicant` group to configure wpa_supplicant imperatively.

For example, using `wpa_cli` you can add a new network and connect to it as:

```console

# 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

```

After you have edited the `wpa_supplicant.conf`, you need to restart the

wpa_supplicant service.

Note that these changes will be lost when wpa_supplicant is restarted.

To make them persistent, the option

[](#opt-networking.wireless.allowAuxiliaryImperativeNetworks) can be set, which

allows to use the `save` command in `wpa_cli`, or even directly editing the

file `/etc/wpa_supplicant/imperative.conf`.

```ShellSession

::: {.note}

Remember that after manually editing `imperative.conf` the wpa_supplicant daemon

needs to be restarted:

```console

# systemctl restart wpa_supplicant.service

```

or

```console

# systemctl restart wpa_supplicant-<interface>.service

```

if [](#opt-networking.wireless.interfaces) has been set.

:::

## Enterprise networks {#sec-wireless-enterprise}

Networks with more sophisticated authentication protocols can be configured

using the free-form `auth` option, for example:

```

{

  networking.wireless.networks = {

    eduroam.auth = ''

      key_mgmt=WPA-EAP

      eap=PEAP

      identity="alice.smith@example.com"

      password="veryLongPassword$!3"

      ca_cert="/etc/wpa_supplicant/eduroam.pem"

    '';

  };

}

```

For examples and a list of available options, see the

[wpa_supplicant.conf(5)](man:wpa_supplicant.conf(5)) man page.

::: {.warning}

By default, security hardening measures that limit access to files, devices and

network capabilities are applied to the wpa_supplicant daemon.

Certificates and other files supplied here need to be readable by the

`wpa_supplicant` user; it is therefore recommended to store them in the

`/etc/wpa_supplicant` directory.

If your network authentication protocol requires write access to files, smart

cards or TPM devices, you may have to disable security hardening with

```nix

{ networking.wireless.enableHardening = false; }

```

This setting also applies to networks configured from NetworkManager, unless

the WiFi [backend](#opt-networking.networkmanager.wifi.backend) in use is not

wpa_supplicant.

:::

  "sec-override-nixos-test": [

    "index.html#sec-override-nixos-test"

  ],

  "sec-wireless-declarative": [

    "index.html#sec-wireless-declarative"

  ],

  "sec-wireless-enterprise": [

    "index.html#sec-wireless-enterprise"

  ],

  "sec-wireless-imperative": [

    "index.html#sec-wireless-imperative"

  ],

  "test-opt-rawTestDerivationArg": [

    "index.html#test-opt-rawTestDerivationArg"

  ],

- support for `ecryptfs` in nixpkgs has been removed.

- The `networking.wireless` module has been security hardened: the `wpa_supplicant` daemon now runs under an unprivileged user with restricted access to the system.

- The `networking.wireless` module has been security hardened by default: the `wpa_supplicant` daemon now runs under an unprivileged user with restricted access to the system.

  As part of these changes, `/etc/wpa_supplicant.conf` has been deprecated: the NixOS-generated configuration file is now linked to `/etc/wpa_supplicant/nixos.conf` and `/etc/wpa_supplicant/imperative.conf` has been added for imperatively configuring `wpa_supplicant` or when using [allowAuxiliaryImperativeNetworks](#opt-networking.wireless.allowAuxiliaryImperativeNetworks).

  Also, the {option}`networking.wireless.userControlled.group` option has been removed since there is now a dedicated `wpa_supplicant` group to control the daemon, and {option}`networking.wireless.userControlled.enable` has been renamed to [](#opt-networking.wireless.userControlled).

  No functionality should have been impacted by these changes (including controlling via `wpa_cli`, integration with NetworkManager or connman), but if you find any problems, please open an issue on GitHub.

  If necessary, the security hardening can be reverted with [](#opt-networking.wireless.enableHardening).

  Note for NetworkManager users: before these changes NetworkManager used to spawn its own wpa_supplicant daemon, but now it relies on `networking.wireless`. So, if you had `networking.wireless.enable = false` in your configuration, you should remove that line.

- `kratos` has been updated from 1.3.1 to [25.4.0](https://github.com/ory/kratos/releases/tag/v25.4.0). Upstream switched to a new versioning scheme (year.major.minor). Notable breaking changes: