Difference between revisions of "Iwd"

From ArchWiki
Jump to navigation Jump to search
(added more links for documentation)
(fixed section fragments (interactive))
Tag: wiki-scripts
 
(167 intermediate revisions by 48 users not shown)
Line 1: Line 1:
 +
{{Lowercase title}}
 
[[Category:Wireless networking]]
 
[[Category:Wireless networking]]
 
[[Category:Network configuration]]
 
[[Category:Network configuration]]
 +
[[ja:Iwd]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|Network configuration}}
 
{{Related|Network configuration}}
 
{{Related|Wireless network configuration}}
 
{{Related|Wireless network configuration}}
{{Related|WPA2 Enterprise}}
+
{{Related|WPA supplicant}}
 
{{Related articles end}}
 
{{Related articles end}}
 +
[https://iwd.wiki.kernel.org/ 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. [https://www.youtube.com/watch?v=F2Q86cphKDo]
  
[https://git.kernel.org/pub/scm/network/wireless/iwd.git/ IWD] is an up-and-coming wireless daemon for Linux. It is written by Intel and aims to replace wpa_supplicant.
+
iwd can work in standalone mode or in combination with comprehensive network managers like [[ConnMan]], [[systemd-networkd]] and [[NetworkManager#Using_iwd_as_the_Wi-Fi_backend|NetworkManager]].
It comes with different enhancements like an own crypto-library, called ELL, which docks directly into the Linux Kernel cryptography. IWD follows a more simple, more secure and more modern approach.
 
  
 
== Installation ==
 
== Installation ==
  
[[Install]] the {{Pkg|iwd}} package, which includes the client programm {{ic|iwctl}}, the daemon {{ic|iwd}} and the wifi monitoring tool {{ic|iwmon}}. IWD works standalone or in combination with connman or networkmanager.
+
[[Install]] the {{Pkg|iwd}} package.
  
 +
== Usage ==
  
== Overview ==
+
The {{Pkg|iwd}} package provides the client program {{ic|iwctl}}, the daemon {{ic|iwd}} and the Wi-Fi monitoring tool {{ic|iwmon}}.
  
The first step is to have the {{ic|iwd}} daemon up and running:
+
[[Start/enable]] {{ic|iwd.service}} so it can be controlled using the {{ic|iwctl}} command.
  
# systemctl enable iwd.service --now
+
=== iwctl ===
  
Then you can control your wireless settings via the command {{ic|iwctl}}. This command will open an interactive shell in the context of IWD.
+
To get an interactive prompt do:
  
== Basic usage ==
+
$ iwctl
  
=== Displaying all physical wifi devices ===
+
The interactive prompt is then displayed with a prefix of {{ic|[iwd]#}}.
  
{{hc|# iwctl|<nowiki>
+
{{Tip|
[iwd]# device list
+
* In the {{ic|iwctl}} prompt you can auto-complete commands and device names by hitting {{ic|Tab}}.
                                    Devices                                  *
+
* You can use all commands as command line arguments without entering an interactive prompt. For example: {{ic|iwctl device wlp3s0 show}}.}}
--------------------------------------------------------------------------------
+
 
  Name                Address            State          Adapter 
+
To list all available commands:
--------------------------------------------------------------------------------
+
 
  wlp2s0b1            5c:ac:4c:ab:3f:7d  disconnected  phy0             
+
[iwd]# help
</nowiki>}}
+
 
 +
==== 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.
 +
 
 +
{{Note|
 +
* {{ic|iwd}} automatically stores network passphrases in the {{ic|/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"
 +
}}
 +
 
 +
==== 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:
  
=== Scanning for networks ===
+
[iwd]# known-networks ''SSID'' forget
{{hc|# iwctl|<nowiki>
 
[iwd]# device wlp2s0b1 scan
 
[iwd]# device wlp2s0b1 get-networks
 
                              Available networks                            *
 
--------------------------------------------------------------------------------
 
    Network name                    Security  Signal
 
--------------------------------------------------------------------------------
 
    TestWPA                        psk      ****
 
    TestWPA2                        psk      ****
 
</nowiki>}}
 
  
=== Connecting to a WPA2 protected access point ===
 
{{hc|# iwctl|<nowiki>
 
[iwd]# device wlp2s0b1 connect TestWPA2
 
Type the network passphrase for TestWPA2 psk.                                 
 
Passphrase: *********************                                             
 
[iwd]# device wlp2s0b1 get-networks
 
                              Available networks                             
 
--------------------------------------------------------------------------------
 
    Network name                    Security  Signal
 
--------------------------------------------------------------------------------
 
    TestWPA                        psk      ****
 
  > TestWPA2                        psk      ****
 
</nowiki>}}
 
 
== WPA Enterprise ==
 
== WPA Enterprise ==
  
 
=== EAP-PWD ===
 
=== EAP-PWD ===
For connecting to a EAP-PWD protected enterprice access point you need to create a file called: {{ic|<essid>.8021x}} in the folder {{ic|/var/lib/iwd/}} with the following content:
 
  
{{hc|/var/lib/iwd/<essid>.8021x|<nowiki>
+
For connecting to a EAP-PWD protected enterprice access point you need to create a file called: {{ic|''essid''.8021x}} in the folder {{ic|/var/lib/iwd}} with the following content:
 +
 
 +
{{hc|/var/lib/iwd/''essid''.8021x|2=
 
[Security]
 
[Security]
 
EAP-Method=PWD
 
EAP-Method=PWD
EAP-Identity=<your enterprise email>
+
EAP-Identity=''your_enterprise_email''
EAP-PWD-Password=<your password>
+
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 {{ic|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 {{ic|''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:
 +
 
 +
{{hc|/var/lib/iwd/''essid''.8021x|2=[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}}
 +
 
 +
{{Tip|If you are planning on using ''eduroam'' and you are affiliated with a US-based institution, your CA is likely {{ic|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.}}
 +
 
 +
=== TTLS-PAP ===
 +
 
 +
Like EAP-PWD, you also need to create a {{ic|''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:
 +
 
 +
{{hc|/var/lib/iwd/''essid''.8021x|2=[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}}
 +
 
 +
=== TLS Based EAP Methods on older kernels ===
 +
 
 +
Linux kernels older than v4.20 (e.g. {{Pkg|linux-lts}}) have to be patched to connect to EAP-TLS, EAP-TTLS, and EAP-PEAP.
 +
Edit the PKGBUILD for the kernel and add the following sources
 +
{{hc|PKGBUILD|2=
 +
"iwd1.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ab2a33c1c0b1b0a45c16746dd0101057c6d432ed"
 +
"iwd2.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3a478ace6154e33009f9b01acbd4eaf7615fef0e"
 +
"iwd3.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5faadff684460b7f4064f9f28db8915a56601147"
 +
"iwd4.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3c7f3a6c70b47858a065b7a86313f390b083ee40"
 +
"iwd5.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5362bbfdf2a8a5810d4237e4dbbf5da043e47fb6"
 +
"iwd6.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5c93ce3acc010425eab01dc8e0ffb5529f3f85c1"
 +
"iwd7.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ca4d545b92cf52ffe777cc7cfbaf64100dfa6e9c"
 +
"iwd8.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=f2ac228eaba9fe3f4fcf80b121eb92707afdd4de"
 +
}}
 +
And add the following line to the end of the kernel config:
 +
{{hc|config|2=
 +
CONFIG_PKCS8_PRIVATE_KEY_PARSER=y
 +
}}
 +
Then update the checksums of the PKGBUILD with {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}):
 +
 
 +
$ updpkgsums
 +
 
 +
and build the package.
 +
 
 +
=== Other cases ===
 +
 
 +
More example tests can be [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests found in the test cases] of the upstream repository.
 +
 
 +
== Optional configuration ==
 +
 
 +
File {{ic|/etc/iwd/main.conf}} can be used for main configuration. See {{man|5|iwd.config}}.
 +
 
 +
By default, {{ic|iwd}} stores the network configuration in {{ic|/var/lib/iwd}} directory. The configuration file is named as {{ic|''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 {{ic|PreSharedKey}} and optionally the cleartext {{ic|Passphrase}} and can be created by the user without invoking {{ic|iwctl}}. The file can also be used for other configuration pertaining to that network SSID. For more settings, see {{man|5|iwd.network}}.
 +
 
 +
A minimal example file to connect to a WPA2/PSK secured network with SSID "spaceship" and passphrase "test1234":
 +
 
 +
{{hc|/var/lib/iwd/spaceship.psk|2=
 +
[Security]
 +
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295
 +
}}
 +
 
 +
The PreSharedKey can be calculated from the SSID and the WiFi passphrase using ''wpa_passphrase'' (from {{Pkg|wpa_supplicant}}) or {{AUR|wpa-psk}}:
 +
 
 +
{{hc|$ wpa_passphrase "spaceship" "test1234"|2=
 +
network={
 +
        ssid="spaceship"
 +
        #psk="test1234"
 +
        psk=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295
 +
}
 +
}}
 +
 
 +
{{Note|The SSID of the network is used as a filename only when it contains only alphanumeric characters or one of {{ic|- _}}. If it contains any other characters, the name will instead be an {{ic|1==}}-character followed by the hex-encoded version of the SSID.}}
 +
 
 +
=== Disable auto-connect for a particular network ===
 +
 
 +
Create / edit file {{ic|/var/lib/iwd/''network''.''type''}}. Add the following section to it:
  
 +
{{hc|/var/lib/iwd/spaceship.psk (for example)|2=<nowiki>
 
[Settings]
 
[Settings]
Autoconnect=True
+
AutoConnect=false
 
</nowiki>}}
 
</nowiki>}}
  
If you don't want autoconnect to the AP you can set the option to False and connect manually to the access point via {{ic|iwctl}}. The same applies to the password, if you don't want to store it plaintext leave the option out of the file and just connect to the enterprise AP.
+
=== Disable periodic scan for available networks ===
 +
 
 +
By default when {{ic|iwd}} is in disconnected state, it periodically scans for available networks. To disable periodic scan (so as to always scan manually), create / edit file {{ic|/etc/iwd/main.conf}} and add the following section to it:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[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.
 +
 
 +
To activate iwd's network configuration feature, create/edit {{ic|/etc/iwd/main.conf}} and add the following section to it:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[General]
 +
EnableNetworkConfiguration=true
 +
}}
 +
 
 +
There is also ability to set route metric with {{ic|route_priority_offset}}:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[General]
 +
route_priority_offset=300
 +
}}
 +
 
 +
==== Setting static IP address in network configuration ====
 +
 
 +
Add the following section to {{ic|/var/lib/iwd/''network''.''type''}} file. For example:
 +
 
 +
{{hc|/var/lib/iwd/spaceship.psk|2=
 +
[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 {{ic|/etc/iwd/main.conf}} for {{ic|systemd-resolved}}:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[Network]
 +
NameResolvingService=systemd
 +
}}
 +
 
 +
For {{ic|resolvconf}}:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[Network]
 +
NameResolvingService=resolvconf
 +
}}
 +
 
 +
=== Deny console (local) user from modifying the settings ===
 +
 
 +
By default {{ic|iwd}} D-Bus interface allows ''any'' console user to connect to {{ic|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.
 +
 
 +
{{hc|/etc/dbus-1/system.d/iwd-strict.conf|2=<nowiki>
 +
<!-- 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>
 +
</nowiki>}}
 +
 
 +
{{Tip|Remove ''<allow>'' lines above to deny reading the status information as well.}}
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== 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 [https://bbs.archlinux.org/viewtopic.php?id=241803]. 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 [https://iwd.wiki.kernel.org/interface_lifecycle#udev_interface_renaming]. The issue can be fixed by forcing iwd to legacy mode and thus, not renaming newly detected devices, by adding an option to {{ic|/etc/iwd/main.conf}} as follows:
 +
 
 +
{{hc|/etc/iwd/main.conf|2=
 +
[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:
 +
 
 +
{{hc|1=/etc/systemd/system/iwd@.service|2=
 +
[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 {{ic|iwd.service}} and enable {{ic|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: [https://lists.01.org/pipermail/iwd/2019-March/005837.html]
 +
 
 +
{{Accuracy|1=Is "After=network-pre.target" needed? If so, is "After=systemd-udevd" even needed? This solution does not seem to work for all cases. See [https://lists.01.org/pipermail/iwd/2019-March/005839.html] and {{man|7|systemd.special}}.}}
 +
 
 +
{{hc|1=/etc/systemd/system/iwd.service.d/override.conf|2=
 +
[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:
 +
 
 +
{{hc|1=/etc/systemd/system/iwd.service.d/override.conf|2=
 +
[Unit]
 +
After=systemd-udevd.service systemd-networkd.service}}
 +
 
 +
See {{Bug|61367}}.
 +
 
 +
=== Wireless device is not renamed by udev ===
 +
 
 +
Upgrade to {{Pkg|iwd}} 1.0 introduces the systemd network link configuration file:
 +
 
 +
{{hc|1=/usr/lib/systemd/network/80-iwd.link|2=
 +
[Match]
 +
Type=wlan
 +
 
 +
[Link]
 +
NamePolicy=keep kernel}}
 +
 
 +
This prevents udev from renaming the interface to {{ic|wlp#s#}}. As a result the wireless link name {{ic|wlan#}} is kept after boot.
 +
 
 +
If this results to issues disabling this file helps:
 +
 
 +
# ln -s /dev/null /etc/systemd/network/80-iwd.link
 +
 
 +
=== WPA Enterprise connection with NetworkManager ===
 +
 
 +
{{Move|NetworkManager#Troubleshooting|This is not a problem of iwd.}}
 +
 
 +
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 {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[#WPA Enterprise]].
  
== Further Documentation ==
+
== See also ==
  
First steps with IWD: [https://iwd.wiki.kernel.org/gettingstarted https://iwd.wiki.kernel.org/gettingstarted ]<br>
+
* [https://iwd.wiki.kernel.org/gettingstarted Getting Started with iwd]
More Examples for Enterprise WPA: [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests]
+
* [https://iwd.wiki.kernel.org/networkconfigurationsettings Network Configuration Settings]
 +
* [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests More Examples for WPA Enterprise]

Latest revision as of 22:29, 8 December 2019

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.

Installation

Install the iwd package.

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]#.

Tip:
  • In the iwctl prompt you can auto-complete commands and device names by hitting Tab.
  • 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.

Note:
  • 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"

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 enterprice 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
Tip: If you are planning on using eduroam and you are affiliated with a US-based institution, your CA is likely 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.

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

TLS Based EAP Methods on older kernels

Linux kernels older than v4.20 (e.g. linux-lts) have to be patched to connect to EAP-TLS, EAP-TTLS, and EAP-PEAP. Edit the PKGBUILD for the kernel and add the following sources

PKGBUILD
"iwd1.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ab2a33c1c0b1b0a45c16746dd0101057c6d432ed"
"iwd2.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3a478ace6154e33009f9b01acbd4eaf7615fef0e"
"iwd3.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5faadff684460b7f4064f9f28db8915a56601147"
"iwd4.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3c7f3a6c70b47858a065b7a86313f390b083ee40" 
"iwd5.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5362bbfdf2a8a5810d4237e4dbbf5da043e47fb6"
"iwd6.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5c93ce3acc010425eab01dc8e0ffb5529f3f85c1"
"iwd7.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ca4d545b92cf52ffe777cc7cfbaf64100dfa6e9c"
"iwd8.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=f2ac228eaba9fe3f4fcf80b121eb92707afdd4de"

And add the following line to the end of the kernel config:

config
CONFIG_PKCS8_PRIVATE_KEY_PARSER=y

Then update the checksums of the PKGBUILD with updpkgsums (from pacman-contrib):

$ updpkgsums

and build the package.

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
}
Note: The SSID of the network is used as a filename only when it contains only alphanumeric characters or one of - _. 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.

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>
Tip: Remove <allow> lines above to deny reading the status information as well.

Troubleshooting

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]

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Is "After=network-pre.target" needed? If so, is "After=systemd-udevd" even needed? This solution does not seem to work for all cases. See [5] and systemd.special(7). (Discuss in Talk:Iwd#)
/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 to issues disabling this file helps:

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

WPA Enterprise connection with NetworkManager

Tango-go-next.pngThis article or section is a candidate for moving to NetworkManager#Troubleshooting.Tango-go-next.png

Notes: This is not a problem of iwd. (Discuss in Talk:Iwd#)

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.

See also