iwd without dbus

This is a complete rewrite of the original eiwd with the new focus being to modify as little as possible from upstream.

All that has changed in the iwd code is the insertion of ifdefs to block away dbus code when desired.

CHANGES

ell is included in this repository as a submodule.
dbus has been made optional in the iwd daemon via --disable-dbus.
Fixed non-posix ln usage in Makefile.
Added a simple script to generate iwd configuration files called iwd_passphrase (similar to wpa_passphrase).

BUILDING WITHOUT DBUS

./configure \
    --prefix=/usr \
    --localstatedir=/var \
    --disable-dbus

make
make DESTDIR="BLA BLA" install

WHAT FUNCTIONALITY IS LOST?

The only working utlities are iwd and iwmon. iwd is fully functional via its configuration files.

A new client will be written at some stage to allow finer control over what is available via the iwd configuration files.

Think of eiwd's iwd daemon usage as wpa_supplicant without the use of wpa_cli. Just a daemon which is configured via config files (set and forget).

FUTURE

[ ] Add a non-dbus client.
[x] Pre-generate manual pages for dist tarballs.

ORIGINAL README STARTS HERE

Wireless daemon for Linux

Compilation and installation

In order to compile the source code you need following software packages:

GCC compiler
GNU C library
Embedded Linux library
readline (command line client)

To configure run: ./configure --prefix=/usr

Configure automatically searches for all required components and packages.

To compile and install run: make && make install

Embedded Linux library

In order to compile the daemon and control utility the development version of Embedded Linux library is required to be present. The development repositories can be found here:

git://git.kernel.org/pub/scm/libs/ell/ell.git
https://kernel.googlesource.com/pub/scm/libs/ell/ell.git

The build systems requires that the Embedded Linux library source code is available on the same top level directory as the Wireless daemon source code:

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

It is not required to build or install Embedded Linux library. The build will happen when building the Wireless daemon and it will then be linked internally.

When using --enable-external-ell build option, it is not required that the Embedded Linux library source code is available in the top level directory.

The tarballs include a copy of the Embedded Linux library source files. When building from the tarballs, then it is not required to have the library sources available in the top level directory.

Manual pages

The manual pages are generated from reStructuredText markup source files during the normal build process. The generation requires the rst2man utility from Python Docutils project. If rst2man is for some reason not available, using --disable-manual-pages will skip the manual pages generation and installation.

When building from the tarballs, a copy of the generated manual pages is included and the rst2man utility is actually not needed.

Configuration and options

The configuration system provides switches to disable certain build time configuration options which are generally useful and enabled by default:

--disable-daemon

    Disable installation of Wireless daemon

    By default the Wireless daemon binary iwd is enabled and
    placed into --libexecdir directory.

--disable-client

    Disable installation of Wireless client utility

    By default the Wireless client binary iwctl is enabled
    and place into --bindir directory.

--disable-monitor

    Disable installation of Wireless monitor utility

    By default the Wireless monitor binary iwmon is enabled
    and place into --bindir directory.

--disable-dbus-policy

    Disable installation of D-Bus system policy configuration

    By default the accompanying D-Bus policy file will be
    installed in the D-Bus data directory. The location of
    that directory will be automatically detected or can be
    manually configured via the --with-dbus-datadir option.

    The D-Bus policy is required for daemons to gain service
    name ownership and clients to access them. When disabling
    this option, manual installation of D-Bus polices is
    required.

    Note: This option affects all D-Bus policy configurations.

--disable-systemd-service

    Disable installation of systemd service configuration

    By default the accompanying systemd service unit with
    D-Bus autostart configuration will be installed. The
    locations will be automatically detected or can be
    manually configured via --with-dbus-busdir option
    and --with-systemd-unitdir option.

    Using systemd is optional, but highly recommended. When
    disabling this option, manual installation is required.

    Note: This option affects all systemd unit setups.

--disable-manual-pages

    Disable generation and installation of manual pages

    By default all available manual pages will be generated
    and installed. When disabling this options, no manual
    pages are installed.

    Note: This options affects all manual pages.

When building for a system that wants to use wireless technology, disabling any of the above options makes only limited sense. It may break the general setup and usability for wireless connections.

The configuration system provides switches for optional build time features that can be enabled if the functionality is required:

--enable-external-ell

    Enable usage of external Embedded Linux library

    This allows using an externally installed Embedded Linux
    library instead of using the internal copy of ELL.

    Since the public API of Embedded Linux library is not yet
    stable, the usage of the internal ELL copy is preferred.

--enable-wired

    Enable installation of Ethernet authentication daemon

    This allows enabling the Ethernet daemon binary ead which
    is then placed into --libexecdir directory.

    With this option the support for 802.1x for wired Ethernet
    connections can be enabled. It provides its own D-Bus
    policy and systemd configuration.

--enable-hwsim

    Enable installation of Wireless simulation utility

    This allows enabling the Simulation daemon binary hwsim
    which is then placed into --bindir directory.

    With this utility and mac80211_hwim kernel module the
    simulation of 802.11 networks can be tested. It provides
    its own D-Bus policy configuration.

    This utility is only useful for developers and should not
    be considered for general installation. For this reason
    no systemd configuration is provided.

--enable-tools

    Enable compilation of various testing utilities

    This enables building of all utilities that are however
    not installed and only useful during development.

--enable-ofono

    Enable support for oFono SIM authentication

    Note: With --disable-daemon this option is ignored

--enable-sim-hardcoded

    Enable support for hard coded SIM keys

    Note: With --disable-daemon this option is ignored

Netlink monitoring

The included iwmon utility can be used to monitor the 802.11 subsystem generic netlink commands and events. It uses the nlmon kernel driver from Linux 3.10 and later. On startup network monitor interface named named 'nlmon' is created unless another interface name is given on the command line. If the monitor interface was created by the iwmon utility, it will be removed on program exit.

Manually the monitor interface can be created using the following commands:

ip link add name nlmon type nlmon
ip link set dev nlmon allmulticast on
ip link set dev nlmon up

It is possible to create netlink traces in PCAP format using tcpdump and then read them via iwmon utility:

tcpdump -i nlmon -w trace-file.pcap

The resulting PCAP files will use Linux cooked packet format containing packets with ARPHRD_NETLINK type. They can be read using iwmon:

iwmon -r trace-file.pcap

At this time iwmon is not able to write PCAP files by itself. This might change in future versions.

When also the authentication protocol traffic on port 0x888e (ETH_P_PAE) is needed, then a second capture is required:

tcpdump -i any 'ether proto 0x888e' -w trace-pae.pcap

It is possible to combine these two PCAP files using the mergecap utility and create a combined trace file:

mergecap -F pcap -w trace.pcap trace-file.pcap trace-pae.pcap

This will create a trace.pcap file that includes the complete picture of nl80211 netlink traffic and authentication messages. All packets are merged in chronological order based on timestamps.

Unfortunately it is not possible to instruct tcpdump filtering to do this in a single capture. Post-processing of the PCAP files is required at the moment.

Simulating devices

The Linux driver mac80211_hwsim provides the functionality to simulate Wireless devices using fake virtual air. Just load the module.

modprobe mac80211_hwsim radios=0

Providing the radios=0 is important since otherwise it starts out with two new Wireless radios by default.

With the provided hwsim utility it is now possible to add and remove virtual radio devices.

hwsim --create --keep
hwsim --destroy=<radio-id>

The radio id assigned to each virtual device is its internal id used by the Wireless device.

Information

Mailing list: https://lists.01.org/postorius/lists/iwd.lists.01.org/

IRC: irc://irc.freenode.net/#iwd

Wiki: https://iwd.wiki.kernel.org/

dylanaraps / eiwd

readme