User Tools

Site Tools


This is an old revision of the document!

Getting Started with iwd

So you want to try out iwd but do not know where to start? You're in the right place. This document will cover building iwd from source and basic WPA-Personal (pre-shared key) type use cases. For WPA-Enterprise / 802.1X authentication setup, see the relevant topic pages.

Grabbing the source, building & installing

This assumes that you want to build iwd from source. If your distribution packages iwd already in some form, you can skip to the next section.

First we need ell, which is the only real library dependency that iwd has. ell provides D-Bus, Netlink, Main event loop, Timers, and various primitives for iwd.

denkenz@iwd-test ~ $
denkenz@iwd-test ~ $ git clone git://
Cloning into 'ell'...
remote: Counting objects: 7007, done.
remote: Compressing objects: 100% (1760/1760), done.
remote: Total 7007 (delta 5249), reused 6957 (delta 5226)
Receiving objects: 100% (7007/7007), 1.05 MiB | 0 bytes/s, done.
Resolving deltas: 100% (5249/5249), done.
denkenz@iwd-test ~ $ 

That's it for ell. We don't need to build it as iwd's build system will find the needed files from ell and build them as part of iwd. The only requirement is that iwd & ell top level directories are in the same root directory, and that ell source code is placed inside 'ell':

        |--- ell
        |    |--- ell
        |    `--- unit
        `--- iwd
             |--- src
             `--- client

Now on to iwd source:

denkenz@iwd-test ~ $ git clone git://
Cloning into 'iwd'...
remote: Counting objects: 10799, done.
remote: Compressing objects: 100% (2999/2999), done.
remote: Total 10799 (delta 7716), reused 10772 (delta 7708)
Receiving objects: 100% (10799/10799), 1.70 MiB | 0 bytes/s, done.
Resolving deltas: 100% (7716/7716), done.
denkenz@iwd-test ~ $

Now it is time to build iwd source itself. First we need to configure. If your system is not running systemd (like the test system in this example), then you should use '–disable-systemd-service' argument.

denkenz@iwd-test ~ $ cd iwd
denkenz@iwd-test ~/iwd $ ./bootstrap
denkenz@iwd-test ~/iwd $ ./configure --prefix=/usr --localstatedir=/var --sysconfdir=/etc --disable-systemd-service
denkenz@iwd-test ~/iwd $ make

At this point the code should be built and the binary produced:

denkenz@iwd-test ~/iwd $ ls src/iwd
denkenz@iwd-test ~/iwd $ 

At this point you can use make install to install the resulting binaries to your system:

denkenz@iwd-test ~/iwd $ sudo make install

If you want to avoid using make install above, you can run iwd successfully directly from the build directory. The only requirement is that we will need to punch a hole in the D-Bus Daemon configuration file to allow iwd to own the relevant DBus service. This can be done as follows:

denkenz@iwd-test ~/iwd $ sudo /usr/bin/install -c -m 644 src/iwd-dbus.conf `pkg-config --variable=datadir dbus-1`/dbus-1/system.d
Kernel Dependencies

iwd uses Linux Kernel's crypto subsystem for all cryptographic operations. iwd does not use OpenSSL or any other userspace cryptographic library. This does mean that your kernel must be configured properly. It is recommended that a very recent kernel is used, however for WPA-Personal usecases, a stock kernel version 4.11 should be sufficient.

For WPA-Personal the following kernel options must be enabled. You can use the scripts/config command from your Linux Kernel source tree to accomplish this:

scripts/config --enable CONFIG_CRYPTO_USER_API_SKCIPHER
scripts/config --enable CONFIG_CRYPTO_USER_API_HASH
scripts/config --enable CONFIG_CRYPTO_HMAC
scripts/config --enable CONFIG_CRYPTO_CMAC
scripts/config --enable CONFIG_CRYPTO_MD4
scripts/config --enable CONFIG_CRYPTO_MD5
scripts/config --enable CONFIG_CRYPTO_SHA256
scripts/config --enable CONFIG_CRYPTO_SHA512
scripts/config --enable CONFIG_CRYPTO_AES
scripts/config --enable CONFIG_CRYPTO_ECB
scripts/config --enable CONFIG_CRYPTO_ARC4
scripts/config --enable CONFIG_CRYPTO_DES
scripts/config --enable CONFIG_CRYPTO_CBC

If you want to play with WPS support, then you also need:

scripts/config --enable CONFIG_KEY_DH_OPERATIONS
Starting iwd

iwd must be started as root as it requires certain privileges to manage network interfaces, initiate wireless connections over NL80211 and run a service on the D-Bus system bus. If your distribution already packages iwd, please refer to your distribution's documentation on how the iwd service should be started. You can also skip to the next section. This HOWTO assumes that you have built iwd from source and want to use it from the build directory.

First a quick recap of iwd command line options:

denkenz@iwd-test ~/iwd $ src/iwd --help
iwd - Wireless daemon
	iwd [options]
	-B, --dbus-debug       Enable D-Bus debugging
	-i, --interfaces       Interfaces to manage
	-I, --nointerfaces     Interfaces to ignore
	-p, --phys             Phys to manage
	-P, --nophys           Phys to ignore
	-c, --config           Configuration directory to use
	-l, --plugin           Plugins to include
	-L, --noplugin         Plugins to exclude
	-h, --help             Show help options

You can use '–nointerfaces' or '–nophys' options to blacklist certain WiFi phys or interfaces from being managed by iwd. E.g. if they already might be managed by another process.

To start iwd, simply issue the following command:

denkenz@iwd-test ~/iwd $ sudo src/iwd

If your kernel is configured correctly, your iwd service should now be running. If iwd fails to start, pay attention to which kernel configuration are missing from your kernel and address those missing options first.

gettingstarted.1525982240.txt.gz · Last modified: 2018/05/10 19:57 by Denis Kenzior