The iNet Wireless Daemon (or iwd for short) is the new superior tool for managing wireless devices on Linux. For the reason why and other details of iwd shall be left to others.

This post shall give a brief introduction into a simple functional iwd-based setup. Make sure you have all alternative service disabled that could interfere with this setup.

Network setup

Requirements

  • Linux >= 4.20 (at least for things like eduroam or other EAP-wifis)
  • iwd
  • systemd-networkd
  • NetworkManager/Connman/other-GUI-Interface (optional, potentially alternatively to systemd-networkd)

iwd

Start iwd. On systemd-based systems this is most likely just a simple systemctl enable iwd && systemctl start iwd. One can verify that iwd runs by issuing iwctl. If it can connect to iwd, you’ll get a iwctl-shell.

Furthermore, starting with iwd 0.18, you have to create a file /etc/iwd/main.conf containing

[General]
use_default_interface=true

due to iwd’s interface lifecycle handling, otherwise your default interface will be removed by iwd and therefore networkd won’t be able to handle it correctly, at least not when you use the interface’s Name for matching. If you use a [Match] section compatible with iwd’s new interface lifecycle handling, this is not necessary, of course.

systemd-networkd

Create a file /etc/systemd/network/wifi.network containing

[Match]
Name=< name of your wifi interface or * for every interface >

[Network]
DHCP=yes
IPv6PrivacyExtensions=true

and enable systemd-networkd. Now you have iwd bringing your wifi up and systemd-networkd getting you an IP via DHCP on that interface quickly afterwards.

At some point iwd intends to implement DHCP as well, but as of writing this, this is not yet the case and needs to be done by e.g. systemd-networkd.

Remarks to GUIs

If you use NetworkManager, you have to enable the iwd-backend for NetworkManager to use it. In addition to that, double check if you have the right NetworkManager-Version for your iwd version. As iwd has still not reached version 1.0 as of time of writing, the API can still be subject to change if it turns out that things need to be changed to prevent headaches in the future.

Working with it

You can now connect to simple PSK-wifi-networks in the iwctl-shell:

[iwctl] station <devicename> get-networks
…
[iwctl] station <devicename> connect network-name

iwd will ask you for the password, memorize it for later connections and autoconnect the next time the network appears.

file-based config

If you have more complex wifi-setups, you can place a configuration file in /var/lib/iwd. The files must be named as networkname.protocol. You can find the protocol listed in the output of get-networks in the iwctl-shell. To fill the file, take a look to the network configuration settings in the iwd documentation.

Example: eduroam

To get eduroam running (at least for institutions using TTLS as the EAP-Method and MSCHAPv2 for the inner authentication), create the file `/var/lib/iwd/eduroam.8021x containing for example

[Security]
EAP-Method=TTLS
EAP-TTLS-Phase2-Method=MSCHAPV2
EAP-TTLS-CACert=<certificate.pem>
EAP-Identity=<anonymous-identity>
EAP-TTLS-Phase2-Identity=<username>
EAP-TTLS-Phase2-Password=<password>

While MSCHAPv2 has been broken by now, the available alternatives for EAP are based on MD5 or directly send cleartext over the wire (PAP) or similarly bad methods, which unfortunately makes MSCHAPv2 seem to be the best choice if available.

For the University Heidelberg for example, fill the template with

  • <certificate.pem>: /etc/ssl/certs/T-TeleSec_GlobalRoot_Class2.pem
  • <anonymous-identity>: eduroamHDaoc2019@uni-heidelberg.de
  • <username>: <uni-id>@uni-heidelberg.de
  • <password>: your University account password

Final remarks

You might want to take a look at the previous post to deal with race conditions that might be introduced due to iwd being significantly faster than other wifi-solutions on Linux.

Revision history

13th June 2019:

  • Example above changed from PAP, which is a cleartext protocol, to MSCHAPv2, which is slightly less bad, for inner authentication
  • Updated example configs to reflect changes in eduroam setup for Heidelberg University

20th June 2019:

  • add section about /etc/iwd/main.conf to keep interoperability with the systemd-networkd-config in this post.