iwd
iwd (iNet wireless daemon) is a wireless daemon for Linux written by Intel. The core goal of the project is to optimize resource utilization by not depending on any external libraries and instead utilizing features provided by the Linux Kernel to the maximum extent possible. [1]
iwd can work in standalone mode or in combination with comprehensive network managers like ConnMan, systemd-networkd and NetworkManager.
Contents
Installation
Usage
The iwd package provides the client program iwctl
, the daemon iwd
and the Wi-Fi monitoring tool iwmon
.
Start/enable iwd.service
so it can be controlled using the iwctl
command.
iwctl
To get an interactive prompt do:
$ iwctl
The interactive prompt is then displayed with a prefix of [iwd]#
.
- In the
iwctl
prompt you can auto-complete commands and device names by hittingTab
. - You can use all commands as command line arguments without entering an interactive prompt. For example:
iwctl device wlp3s0 show
.
To list all available commands:
[iwd]# help
Connect to a network
First, if you do not know your wireless device name, list all wifi devices:
[iwd]# device list
Then, to scan for networks:
[iwd]# station device scan
You can then list all available networks:
[iwd]# station device get-networks
Finally, to connect to a network:
[iwd]# station device connect SSID
If a passphrase is required, you will be prompted to enter it. Alternatively, you can supply as a command line argument:
$ iwctl --passphrase passphrase station device connect SSID
-
iwd
automatically stores network passphrases in the/var/lib/iwd
directory and uses them to auto-connect in the future. See #Optional configuration. - To connect to a network with spaces in the SSID, the network name should be double quoted when connecting.
- iwd only supports PSK pass-phrases from 8 to 63 ASCII-encoded characters. The following error message will be given if the requirements are not met: "PMK generation failed. Ensure Crypto Engine is properly configured"
Connect to a network using WPS/WSC
If your network is configured such that you can connect to it by pressing a button (Wikipedia:Wi-Fi Protected Setup), check first that your network device is also capable of using this setup procedure.
[iwd]# wsc list
Then, provided that your device appeared in the above list,
[iwd]# wsc device push-button
and go push the button on your router. That's it. The procedure works also if the button was pushed beforehand, less than 2 minutes earlier.
If your network requires to validate a PIN number to connect that way, check the help
command output to see how to provide the right options to the wsc
command.
Disconnect from a network
To disconnect from a network:
[iwd]# station device disconnect
Show device and connection information
To display the details of a WiFi device, like MAC address:
[iwd]# device device show
To display the connection state, including the connected network of a WiFi device:
[iwd]# station device show
Manage known networks
To list networks you have connected to previously:
[iwd]# known-networks list
To forget a known network:
[iwd]# known-networks SSID forget
WPA Enterprise
EAP-PWD
For connecting to a EAP-PWD protected enterprise access point you need to create a file called: essid.8021x
in the folder /var/lib/iwd
with the following content:
/var/lib/iwd/essid.8021x
[Security] EAP-Method=PWD EAP-Identity=your_enterprise_email EAP-Password=your_password [Settings] AutoConnect=True
If you do not want autoconnect to the AP you can set the option to False and connect manually to the access point via iwctl
. The same applies to the password, if you do not want to store it plaintext leave the option out of the file and just connect to the enterprise AP.
EAP-PEAP
Like EAP-PWD, you also need to create a essid.8021x
in the folder. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses MSCHAPv2 password authentication:
/var/lib/iwd/essid.8021x
[Security] EAP-Method=PEAP EAP-Identity=anonymous@realm.edu EAP-PEAP-CACert=/path/to/root.crt EAP-PEAP-ServerDomainMask=radius.realm.edu EAP-PEAP-Phase2-Method=MSCHAPV2 EAP-PEAP-Phase2-Identity=johndoe@realm.edu EAP-PEAP-Phase2-Password=hunter2 [Settings] AutoConnect=true
Addtrust External CA Root
, as your institution probably issues certificates through Internet2's InCommon. However, you should always refer to your organization's help desk if in doubt. See also #Eduroam.TTLS-PAP
Like EAP-PWD, you also need to create a essid.8021x
in the folder. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses PAP password authentication:
/var/lib/iwd/essid.8021x
[Security] EAP-Method=TTLS EAP-Identity=anonymous@uni-test.de EAP-TTLS-CACert=cert.pem EAP-TTLS-ServerDomainMask=*.uni-test.de EAP-TTLS-Phase2-Method=Tunneled-PAP EAP-TTLS-Phase2-Identity=user EAP-TTLS-Phase2-Password=password [Settings] AutoConnect=true
Eduroam
Eduroam offers a configuration assistant tool (CAT), which unfortunately does not support iwd. However, the installer, which you can download by clicking on the download button then selecting your university, is just a Python script. It is easy to extract the necessary configuration options, including the certificate and server domain mask.
The following table contains a mapping of iwd configuration options to eduroam CAT install script variables.
Iwd Configuration Option | CAT Script Variable |
---|---|
file name | one of Config.ssids
|
EAP-Method |
Config.eap_outer
|
EAP-Identity |
Config.email
|
EAP-PEAP-CACert |
Config.CA
|
EAP-PEAP-ServerDomainMask |
one of Config.servers
|
EAP-PEAP-Phase2-Method |
Config.eap_inner
|
EAP-PEAP-Phase2-Identity |
username@Config.user_realm
|
EAP-Identity
may not be required by your Eduroam provider, in which case you can use anonymous
in this field.Other cases
More example tests can be found in the test cases of the upstream repository.
Optional configuration
File /etc/iwd/main.conf
can be used for main configuration. See iwd.config(5).
By default, iwd
stores the network configuration in /var/lib/iwd
directory. The configuration file is named as network.type
where network is network SSID and type is network type i.e. one of "open", "wep", "psk", "8021x". The file is used to store the encrypted PreSharedKey
and optionally the cleartext Passphrase
and can be created by the user without invoking iwctl
. The file can also be used for other configuration pertaining to that network SSID. For more settings, see iwd.network(5).
A minimal example file to connect to a WPA2/PSK secured network with SSID "spaceship" and passphrase "test1234":
/var/lib/iwd/spaceship.psk
[Security] PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295
The PreSharedKey can be calculated from the SSID and the WiFi passphrase using wpa_passphrase (from wpa_supplicant) or wpa-pskAUR:
$ wpa_passphrase "spaceship" "test1234"
network={ ssid="spaceship" #psk="test1234" psk=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295 }
- _
. If it contains any other characters, the name will instead be an =
-character followed by the hex-encoded version of the SSID.Disable auto-connect for a particular network
Create / edit file /var/lib/iwd/network.type
. Add the following section to it:
/var/lib/iwd/spaceship.psk (for example)
[Settings] AutoConnect=false
Disable periodic scan for available networks
By default when iwd
is in disconnected state, it periodically scans for available networks. To disable periodic scan (so as to always scan manually), create / edit file /etc/iwd/main.conf
and add the following section to it:
/etc/iwd/main.conf
[Scan] DisablePeriodicScan=true
Enable built-in network configuration
Since version 0.19, iwd can assign IP address(es) and set up routes using a built-in DHCP client or with static configuration. It is a good alternative to standalone DHCP clients.
To activate iwd's network configuration feature, create/edit /etc/iwd/main.conf
and add the following section to it:
/etc/iwd/main.conf
[General] EnableNetworkConfiguration=true
There is also ability to set route metric with route_priority_offset
:
/etc/iwd/main.conf
[General] route_priority_offset=300
Setting static IP address in network configuration
Add the following section to /var/lib/iwd/network.type
file. For example:
/var/lib/iwd/spaceship.psk
[IPv4] ip=192.168.1.10 netmask=255.255.255.0 gateway=192.168.1.1 broadcast=192.168.1.255 dns=192.168.1.1
Select DNS manager
At the moment, iwd supports two DNS managers—systemd-resolved and resolvconf.
Add the following section to /etc/iwd/main.conf
for systemd-resolved
:
/etc/iwd/main.conf
[Network] NameResolvingService=systemd
For resolvconf
:
/etc/iwd/main.conf
[Network] NameResolvingService=resolvconf
Deny console (local) user from modifying the settings
By default iwd
D-Bus interface allows any console user to connect to iwd
daemon and modify the settings, even if that user is not a root user.
If you do not want to allow console user to modify the settings but allow reading the status information, then create a D-Bus configuration file as follows.
/etc/dbus-1/system.d/iwd-strict.conf
<!-- prevent local users from changing iwd settings, but allow reading status information. overrides some part of /usr/share/dbus-1/system.d/iwd-dbus.conf. --> <!-- This configuration file specifies the required security policies for iNet Wireless Daemon to work. --> <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> <busconfig> <policy at_console="true"> <deny send_destination="net.connman.iwd"/> <allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="GetAll" /> <allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="Get" /> <allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.ObjectManager" send_member="GetManagedObjects" /> <allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="RegisterSignalLevelAgent" /> <allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="UnregisterSignalLevelAgent" /> </policy> </busconfig>
Troubleshooting
Verbose TLS debugging
This can be useful, if you have trouble setting up MSCHAPv2 or TTLS. You can set the following environment variable via systemctl edit iwd.service
:
/etc/systemd/system/iwd.conf.d/override.conf
[Service] Environment=IWD_TLS_DEBUG=TRUE
Check the iwd logs afterwards via journalctl -u iwd
Connect issues after reboot
A low entropy pool can cause connection problems in particular noticeable after reboot. See Random number generation for suggestions to increase the entropy pool.
Systemd unit fails on startup due to device not being available
Some users have reported that the provided systemd unit does not wait for the wireless device to become available [2]. Unfortunately, if iwd is started before udev renaming is done, the network device will be blocked and renaming will fail. Thus, the unit fails on startup [3]. The issue can be fixed by forcing iwd to legacy mode and thus, not renaming newly detected devices, by adding an option to /etc/iwd/main.conf
as follows:
/etc/iwd/main.conf
[General] use_default_interface=true
Optionally, bind iwd to a specific wireless device by creating a systemd unit with the following content. As of 0.21, it has been observed that this will not prevent iwd from renaming the wireless device later, thus the use of iwd's legacy mode is mandatory:
/etc/systemd/system/iwd@.service
[Unit] Description=Wireless service on %I BindsTo=sys-subsystem-net-devices-%i.device After=sys-subsystem-net-devices-%i.device [Service] Type=dbus BusName=net.connman.iwd ExecStart=/usr/lib/iwd/iwd --interface %i LimitNPROC=1 Restart=on-failure
Then, disable iwd.service
and enable iwd@device.service
unit for the specific wireless device.
Alternatively, set a proper dependency for iwd to run after systemd/udevd by creating a drop-in file as follows: [4]
/etc/systemd/system/iwd.service.d/override.conf
[Unit] After=systemd-udevd.service
If systemd-networkd is used, since both systemd-udevd/networkd play relatively well together, and both are involved, it is reasonable to start iwd after both of them:
/etc/systemd/system/iwd.service.d/override.conf
[Unit] After=systemd-udevd.service systemd-networkd.service
See FS#61367.
Wireless device is not renamed by udev
Upgrade to iwd 1.0 introduces the systemd network link configuration file:
/usr/lib/systemd/network/80-iwd.link
[Match] Type=wlan [Link] NamePolicy=keep kernel
This prevents udev from renaming the interface to wlp#s#
. As a result the wireless link name wlan#
is kept after boot.
If this results in issues try masking it with:
# ln -s /dev/null /etc/systemd/network/80-iwd.link
WPA Enterprise connection with NetworkManager
If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the iwd backend then you will get the following error from NetworkManager:
Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)
This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd config file /var/lib/iwd/essid.8021x
like described in #WPA Enterprise.