=== 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://git.kernel.org/pub/scm/libs/ell/ell.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://git.kernel.org/pub/scm/network/wireless/iwd.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. There are some dependencies required to configure. They are libtool, readline development headers and glib development headers. For building the manual pages rst2man is also required (python-docutils package on some distros).
For debian based systems, run the following command
$ sudo apt install libtool libreadline-dev libdbus-glib-1-dev python-docutils
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
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_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
Usage:
iwd [options]
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
-l, --plugin Plugins to include
-L, --noplugin Plugins to exclude
-d, --debug Enable debug output
-v, --version Show version
-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.
== Connecting to a Network ==
For this HOWTO we will be using iwd's command line client, iwctl, starting it from the iwd build directory. The default DBus configuration requires users to be part of the netdev group. If you are not, add yourself:
usermod -a -G netdev
iwctl should be shipped by default with most distributions, so if you are using iwd from a distribution package, you can simply invoke 'iwctl'.
denkenz@iwd-test ~/iwd $ client/iwctl
[iwd]# device list
Devices *
--------------------------------------------------------------------------------
Name Address Powered Adapter Mode
--------------------------------------------------------------------------------
wlp2s0b1 f6:1c:7f:ee:56:24 on phy2 station
Here we can see that this system has a single wireless device in 'station' mode, 'wlp2s0b1'. Lets try to find a network to connect to:
[iwd]# station wlp2s0b1 scan
[iwd]# station wlp2s0b1 get-networks
Available networks *
--------------------------------------------------------------------------------
Network name Security Signal
--------------------------------------------------------------------------------
TestWPA psk ****
TestWPA2 psk ****
As you can see there are two networks available. Lets connect to 'TestWPA2'. This network is a 'psk' network and requires a passphrase. When connecting to the network for the first time, iwd will ask you for the passphrase first. Type it in when prompted. For subsequent connections the passphrase entry will not be needed.
[iwd]# station wlp2s0b1 connect TestWPA2
Type the network passphrase for TestWPA2 psk.
Passphrase: *********************
[iwd]# station wlp2s0b1 get-networks
Available networks
--------------------------------------------------------------------------------
Network name Security Signal
--------------------------------------------------------------------------------
TestWPA psk ****
> TestWPA2 psk ****
As you can see, we should now be connected!