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.
Installation
Optionally, third-party graphical and terminal user interface front-ends can be installed:
- impala — A TUI (Terminal User Interface) for iwd.
- iwdgui — A graphical front-end for iwd.
- iwgtk — A graphical front-end for iwd and an indicator (tray) icon.
- iwmenu — A menu-driven interface for iwd.
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 through the iwctl
command or through iwgtk
.
network
or the wheel
user group are allowed to interact with iwd. In order to use iwctl or iwgtk, you need to add your user to one of those groups.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
. - To exit the interactive prompt, send EOF by pressing
Ctrl+d
. - You can use all commands as command line arguments without entering an interactive prompt. For example:
iwctl device wlan0 show
.
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
If the device or its corresponding adapter is turned off, turn it on:
[iwd]# device name set-property Powered on
[iwd]# adapter adapter set-property Powered on
Then, to initiate a scan for networks (note that this command will not output anything):
[iwd]# station name scan
You can then list all available networks:
[iwd]# station name get-networks
Finally, to connect to a network:
[iwd]# station name connect SSID
station
and Tab
Tab
, the available devices are displayed, type the first letters of the device and Tab
to complete. The same way, type connect
and Tab
Tab
in order to have the list of available networks displayed. Then, type the first letters of the chosen network followed by Tab
in order to complete the command.If a passphrase is required (and it is not already stored in one of the profiles that iwd automatically checks), you will be prompted to enter it. Alternatively, you can supply it as a command line argument:
$ iwctl --passphrase passphrase station name connect SSID
iwd
automatically stores network passphrases in the/var/lib/iwd
directory and uses them to auto-connect in the future. See #Network 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 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 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 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, iwgtkAUR provides a GUI front-end through which iwd can be controlled.
Running iwgtk
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 snixembed-gitAUR.
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 snixembed-gitAUR:
- AwesomeWM
- i3bar
- stalonetray
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 iwgtk-indicator.desktop
file which is placed in /etc/xdg/autostart/
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 graphical-session.target
unit, then iwgtk can be autostarted via systemd by enabling the iwgtk.service
user unit.
Network configuration
By default, iwd stores the network configuration in the directory /var/lib/iwd
. The configuration file is named as network.type
, 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 PreSharedKey
and optionally the cleartext Passphrase
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 iwd.network(5).
WPA-PSK
A minimal example file to connect to a WPA-PSK or WPA2-PSK secured network with SSID "spaceship" and passphrase "test1234":
/var/lib/iwd/spaceship.psk
[Security] PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295
- _
. If it contains any other characters, the name will instead be an =
-character followed by the hex-encoded (with lower case letters for the hex-numbers) version of the SSID.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:
/var/lib/iwd/spaceship.psk
[Security] Passphrase=test1234 PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295
- Or the pre-shared key can be calculated from the SSID and the passphrase using wpa_passphrase (from wpa_supplicant) or wpa-pskAUR. See wpa_supplicant#Connecting with wpa_passphrase for more details.
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 /var/lib/iwd
directory 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.
AutoConnect=false
as a workaround.EAP-PEAP
Like EAP-PWD, you also need to create a essid.8021x
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:
/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
MsCHAPv2 passwords can also be stored as an 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 Ctrl+d
, do not hit Enter
. The resulting hash needs to be stored inside the EAP-PEAP-Phase2-Password-Hash
key.
TTLS-PAP
Like EAP-PWD, you also need to create a essid.8021x
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
EAP-TLS
EAP-TLS uses x509 client certificates to authenticate you. Like ssh keys, these use public-key cryptography, so the wifi authentication server never needs to be sent a secret, and you do not need to copy and reuse a password between devices. Usually each device will use a distinct cert, one that can, in theory at least, be revoked without forcing you to change a password or disrupt your other devices.
As with the other enterprise methods you need to know the CA cert your organization uses (cacert.pem
), which is used to prove to your device it is connecting to the right place. You also need to have the client certificate, which represents you and will be uploaded on each connection (client-cert.pem
), and the private key that goes with it (client-key.pem
), which is used to prove you own that client certificate.
You can either provide a path to the required certificate or you can embed them inside your configuration.
When you have collected the credentials, put this in your /var/lib/iwd/essid.8021x
file:
/var/lib/iwd/essid.8021x
[Security] EAP-Method=TLS EAP-TLS-CACert=/path/to/cacert.pem EAP-Identity=your_enterprise_email EAP-TLS-ClientCert=/path/to/client-cert.pem EAP-TLS-ClientKey=/path/to/client-key.pem #EAP-TLS-ClientKeyPassphrase=key-passphrase # if client-key.pem is encrypted, provide its passphrase [Settings] AutoConnect=true
eduroam
eduroam offers a configuration assistant tool (CAT), which supports iwd. If your organisation has a profile within the CAT, getting connected to eduroam can be done by downloading the Linux script and running it using python. If your organisation does not support CAT, you will have to create the configuration file manually using parameters provided to you by the administrators (the below table can be helpful in doing so).
If for whatever reason the script does not work, it is easy to extract the necessary configuration options manually, including the certificate and server domain mask. Additionally, some institutions are upgrading to EAP-TLS, and outsourcing the generation of client-cert.pem
to SecureW2, in which case you will need to use their tool as well to generate a client cert.
The following table contains a mapping of iwd configuration options to eduroam CAT install script variables.
Iwd Configuration Option | CAT Script Variable |
---|---|
essid | one of Config.ssids
|
EAP-Method |
Config.eap_outer
|
EAP-Identity |
Config.anonymous_identity
|
EAP-method-CACert |
the content of Config.CA , an absolute path to a .pem file containing Config.CA or an embedded certificate.
|
EAP-method-ServerDomainMask |
one of Config.servers
|
EAP-method-Phase2-Method |
Config.eap_inner unless it is equal to PAP , in that case use instead Tunneled-PAP
|
EAP-method-Phase2-Identity |
username@Config.user_realm
|
where method
is the content of EAP-Method
and should be either TLS
, TTLS
or PEAP
. Once you have extracted all necessary information and converted them to their iwd configuration equivalent you can put them in a configuration file called essid.8021x
as explained in the preceding methods.
EAP-Identity
may not be required by your eduroam provider, in which case you might have to useanonymous@Config.user_realm
in this field.- If your
EAP-method-ServerDomainMask
starts withDNS:
, use only the part afterDNS:
.
Other cases
More example tests can be found in the test cases of the upstream repository.
Embedded certificates
Instead of including an absolute path to a PEM file (for certificates and keys), the PEM itself can be included inside the network configuration file.
An embedded PEM can appear anywhere in the settings file using the following format:
[@pem@my_ca_cert] ----- BEGIN CERTIFICATE ----- PEM data ----- END CERTIFICATE -----
where my_ca_cert is any name you can use to identify the certificate inside the configuration file.
Then the embedded certificate can be used anywhere in the settings file a certificate path is required by prefixing the value with embed:
EAP-TTLS-CACert=embed:my_ca_cert
This is not limited to CA certificates either. Client certificates, client keys (encrypted or not), and certificate chains can be included.
Optional configuration
File /etc/iwd/main.conf
can be used for main configuration. See iwd.config(5).
Disable auto-connect for a particular network
Create or edit the 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 RoutePriorityOffset
:
/etc/iwd/main.conf
[Network] RoutePriorityOffset=300
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:
/etc/iwd/main.conf
[Network] EnableIPv6=false
To enable it in version below 2.0 and higher than 1.10:
/etc/iwd/main.conf
[Network] EnableIPv6=true
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 /var/lib/iwd/network.type
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 systemd-resolved
:
/etc/iwd/main.conf
[Network] NameResolvingService=systemd
For resolvconf
:
/etc/iwd/main.conf
[Network] NameResolvingService=resolvconf
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>
Encrypted network profiles
By default, iwd stores network credentials to the system unencrypted. Since iwd version 1.25, iwd provides experimental support for creating encrypted profiles for systems using systemd.
First, create an encrypted credential. The following example uses systemd-creds and creates an encrypted credential called iwd-secret that is bound to the system's Trusted Platform Module which will be used to create encrypted profiles:
# systemd-ask-password -n | systemd-creds --tpm2-device=auto --name=iwd-secret encrypt - /etc/credstore.encrypted/iwd-secret.cred
Next, add the LoadCredentialEncrypted
option by creating a drop-in file for the iwd service.
/etc/systemd/system/iwd.service.d/use-creds.conf
[Service] LoadCredentialEncrypted=iwd-secret:/etc/credstore.encrypted/iwd-secret.cred
Finally, add the SystemdEncrypt
option with the value being the named credential to the iwd configuration file, reload the systemd manager, and restart the iwd service.
/etc/iwd/main.conf
[General] ... SystemdEncrypt=iwd-secret
- Any profiles currently on the system will be encrypted automatically. At this point there is nothing else needed, and any future profiles will be encrypted automatically.
- In the above example, the encrypted credential is implicitly bound to TPM PCR 7. Therefore, if the secure boot state or firmware certificates change then connecting to networks will not be possible for that booted session.
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:
/etc/systemd/system/iwd.service.d/tls-debug.conf
[Service] Environment=IWD_TLS_DEBUG=TRUE
Check the iwd logs afterwards by running journalctl -u iwd.service
as root.
Restarting iwd.service after boot
On some machines, it is reported that iwd.service
has to be restarted to work after boot. See FS#63912 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.
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 wlp#s#
:
/usr/lib/systemd/network/80-iwd.link
[Match] Type=wlan [Link] NamePolicy=keep kernel
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:
/etc/iwd/main.conf
[General] EnableNetworkConfiguration=True
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 ([1]) of iwd.service
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 pkcs8_key_parser
kernel module. While on boot it gets loaded by systemd-modules-load.service(8) using /usr/lib/modules-load.d/pkcs8.conf
, that will not be the case if iwd has just been installed.
If messages such as Error loading client private key /path/to/key
show up in the journal when trying to connect to WPA Enterprise networks, manually load the module:
# modprobe pkcs8_key_parser
iwd keeps roaming
iwd will roam to other known APs if the connection is too bad.
This will show up in the system log as wlan0: deauthenticating from xx:xx:xx:xx:xx:xx by local choice (Reason: 3=DEAUTH_LEAVING)
You can see the connection signal strength with
iwctl station wlan0 show | grep RSSI
You can increase the threshold to allow a worse connection. RoamThreshold defaults to -70 and RoamThreshold5G to -76.
/etc/iwd/main.conf
[General] RoamThreshold=-75 RoamThreshold5G=-80
Hostname not sent in DHCP request
Set SendHostname
in the network's configuration file, not in /etc/iwd/main.conf
.
/var/lib/iwd/SomeNetwork.psk
... [IPv4] SendHostname=true
See also
- Getting Started with iwd
- Network Configuration Settings
- More Examples for WPA Enterprise
- The IWD thread on the Arch Linux Forums
- 2017 Update on new WiFi daemon for Linux by Marcel Holtmann - YouTube
- The New Wi-Fi Experience for Linux - Marcel Holtmann, Intel - YouTube
- How to set up a simple access point with iwd