iwd - ArchWiki

Jump to content

# iwd

From ArchWiki

Related articles

- Network configuration
- Wireless network configuration
- wpa_supplicant

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

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`.
- 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

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

Tip: The user interface supports autocomplete, by typing `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, you will be prompted to enter it. Alternatively, you can supply it as a command line argument:

    $ iwctl --passphrase passphrase station device connect SSID

Note:

- `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

## 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, .wep, .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).

Note: In string values, including identities and passwords, certain characters may be backslash-escaped. Leading spaces, \n, \r, and literal backslashes must be escaped. 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

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.

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.

#### 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 a encrypted hash. The correct md4 hash can be calculated with: (insert an EOF after your password, do not hit enter)

    $ iconv -t utf16le | openssl md4

The resulting hash needs to be stored inside the `EAP-PEAP-Phase2-Password-Hash` key.

Tip: If you are planning on using eduroam, see also #eduroam.

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

#### 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.anonymous_identity`
`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`

Note:

- `EAP-Identity` may not be required by your eduroam provider, in which case you might have to use `anonymous@Config.user_realm` in this field.
- If your `EAP-PEAP-ServerDomainMask` starts with `DNS:`, use only the part after `DNS:`.

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

### 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 `RoutePriorityOffset`:

    /etc/iwd/main.conf

    [Network]
    RoutePriorityOffset=300

#### IPv6 support

Since version 1.10, iwd supports IPv6, but it is disabled by default. To enable it, add the following to the configuration file:

    /etc/iwd/main.conf

    [Network]
    EnableIPv6=true

This setting is required 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

Note: If not specified, systemd-resolved is used as default.

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

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

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

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

Categories:

- Wireless networking
- Network configuration