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.
- Linux >= 4.20 (at least for things like eduroam or other EAP-wifis)
- NetworkManager/Connman/other-GUI-Interface (optional, potentially alternatively to systemd-networkd)
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
If it can connect to iwd, you’ll get a iwctl-shell.
Furthermore, starting with iwd 0.18, you have to create a file
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.
Create a file
[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] 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.
If you have more complex wifi-setups, you can place a configuration file in
The files must be named as
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.
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
<password>: your University account password
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.
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.confto keep interoperability with the
systemd-networkd-config in this post.
12th September 2019:
- Corrected typo in certificate path