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.

iwd can work in standalone mode or in combination with comprehensive network managers like ConnMan, systemd-networkd and NetworkManager.

Note: Do not follow the instructions on this page when using iwd via a network manager unless it is explicitly stated otherwise in that network manager's article.

Installation

Install the iwd package.

Usage

The iwd package provides the client program iwctl, the daemon iwd and the Wi-Fi monitoring tool iwmon.

provides a GUI front-end for iwd and an indicator (tray) icon.

Start/enable so it can be controlled through the iwctl command or through .

iwctl

To get an interactive prompt do:

$ iwctl

The interactive prompt is then displayed with a prefix of [iwd]#.

To list all available commands:

[iwd]# help

Connect to a network

First, if you do not know your wireless device name, list all Wi-Fi devices:

[iwd]# device list

Then, to initiate a scan for networks (note that this command will not output anything):

[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 it as a command line argument:

$ iwctl --passphrase passphrase station device connect SSID

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 push the button on your router. 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 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 Wi-Fi 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

iwgtk

Alternatively, provides a GUI front-end through which iwd can be controlled.

Running without any arguments launches the application window, which can be used to toggle your adapters and devices on/off, change their operating modes, view available networks, connect to available networks, and manage known networks.

Indicator icon

To launch iwgtk's indicator (tray) icon daemon, run:

$ iwgtk -i

If the indicator icon does not appear, then your system tray most likely lacks support for the StatusNotifierItem API, in which case you need to run a compatibility layer such as .

The following system trays support StatusNotifierItem, and therefore work out of the box:

KDE Plasma
swaybar
xfce4-panel

The following trays only support XEmbed, and therefore require :

AwesomeWM
i3bar

Autostart

The most common use case for iwgtk is to start the indicator daemon every time you log into your desktop. If your desktop environment supports the XDG Autostart standard, this should happen automatically due to the file which is placed in by the AUR package.

Alternatively, a systemd unit file to start the indicator daemon is provided by the AUR package. If your desktop environment supports systemd's unit, then iwgtk can be autostarted via systemd by enabling the user unit.

Network configuration

By default, iwd stores the network configuration in the directory /var/lib/iwd. The configuration file is named as , where network is the network SSID and .type is the network type, either .open, .psk or .8021x. The file is used to store the encrypted and optionally the cleartext and can also be created by the user without invoking iwctl. The file can be used for other configuration pertaining to that network SSID as well. For more settings, see .

WPA-PSK

A minimal example file to connect to a WPA-PSK or WPA2-PSK secured network with SSID "spaceship" and passphrase "test1234":

To calculate the pre-shared key from the passphrase, one of these two methods can be used:

Enter the passphrase in cleartext in the configuration file:

/var/lib/iwd/spaceship.psk

[Security]
Passphrase=test1234

The pre-shared key will be appended to the file at the first connect:

Or the pre-shared key can be calculated from the SSID and the passphrase using wpa_passphrase (from ) or wpa-psk^AUR. See wpa_supplicant#Connecting with wpa_passphrase for more details.

EAP-PWD

For connecting to a EAP-PWD protected enterprise access point you need to create a file called: in the /var/lib/iwd directory with the following content:

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 file in the directory. 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:

MsCHAPv2 passwords can also be stored as a encrypted hash. The correct md4 hash can be calculated with:

$ iconv -t utf16le | openssl md4 -provider legacy

Insert an EOF after your password by pressing , do not hit . The resulting hash needs to be stored inside the key.

TTLS-PAP

Like EAP-PWD, you also need to create a file in the directory. 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

`EAP-Identity`

	one of
	`Config.eap_inner`
	username@

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 .

Disable auto-connect for a particular network

Create / edit file . Add the following section to it:

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:

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:

There is also ability to set route metric with RoutePriorityOffset:

IPv6 support

Since version 1.10, iwd supports IPv6, but it is disabled by default in versions below 2.0. Since version 2.0, it is enabled by default.

To disable it, add the following to the configuration file:

To enable it in version below 2.0 and higher than 1.10:

This setting is required to be enabled whether you want to use DHCPv6 or static IPv6 configuration. It can also be set on a per-network basis.

Setting static IP address in network configuration

Add the following section to file. For example:

/var/lib/iwd/spaceship.psk

[IPv4]
Address=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 :

For :

Allow any user to read status information

If you want to allow any user to read the status information, but not modify the settings, you can create the following D-Bus configuration file:

/etc/dbus-1/system.d/iwd-allow-read.conf

<!-- Allow any user to read iwd status information. Overrides some part
     of /usr/share/dbus-1/system.d/iwd-dbus.conf. -->

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>

  <policy context="default">
    <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 a drop-in snippet:

Check the iwd logs afterwards by running as root.

Restarting iwd.service after boot

On some machines, it is reported that has to be restarted to work after boot. See and thread 251432. This probably occurs because the Linux kernel and services start too early and iwd starts before wireless network card powers on. As a workaround, extend the unit to add a delay:

[Service]
ExecStartPre=/usr/bin/sleep 2

Then reload the systemd manager configuration.

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.

Wireless device is not renamed by udev

Since version 1.0, iwd disables predictable renaming of wireless device. It installs the following systemd network link configuration file which prevents udev from renaming the interface to :

As a result the wireless link name wlan# is kept after boot. This resolved a race condition between iwd and udev on interface renaming as explained in iwd udev interface renaming.

If this results in issues try masking it with:

# ln -s /dev/null /etc/systemd/network/80-iwd.link

No DHCP in AP mode

Clients may not receive an IP address via DHCP when connecting to iwd in AP mode. It is therefore necessary to enable network configuration by iwd on managed interfaces:

The mentioned file has to be created if it does not already exist.

Wifi keeps disconnecting due to iwd crash

Some users experience disconnections with WiFi, re-connecting continuously but stabilizing eventually and managing to connect.

Users report crashes () of in their journal.

The core issue is having multiple conflicting services for managing their network connections. Check that you do not have enabled them at the same time to fix this issue.

Error loading client private key

To load key files iwd requires the kernel module. While on boot it gets loaded by using /usr/lib/modules-load.d/pkcs8.conf, that will not be the case if iwd has just been installed.

If messages such as show up in the journal when trying to connect to WPA Enterprise networks, manually load the module:

# modprobe pkcs8_key_parser

gollark: No.

gollark: We had this with OIR™.

gollark: I think you just have a terrible connection to me somehow.

gollark: It's saying "write buffer space exhausted" a lot.

gollark: No idea. I couldn't be bothered to actually look at the logs so I wanted to just watch you do stuff as it happened to debug.

iwd