User Tools

Site Tools


Starting with version 0.18 IWD is actively managing network interfaces, something that is not done on most current Linux distributions and operating systems based on the Linux kernel, like Android. This page explains how this works and how it differs from interface management before 0.18.


Current Linux kernels normally expose a single network interface, or netdev, for each physical wired network socket. Similarly the kernel by default creates one network interface for each WiFi radio that is found in the system. A network interface is a basic operating system object on Linux, visible both to the kernel and to the userspace, and unlike most other objects is not accessed like a file. The default WiFi interface will usually be named wlan0, wlan1 and so on, initially, and on systems running the systemd udev it will very quickly get renamed to something like wlp2s0, wlx00e02c312356 and similar. It can also be further manually renamed by the admin. The names are only mnemonics. Interfaces also have unique, immutable indexes (immutable until OS restart, interface removal, etc.).

The capabilities of a WiFi radio depend on the device's firmware and driver and to take full advantage of those capabilities multiple interfaces are allowed on each physical radio. Since those devices don't map 1:1 to interfaces, a different, higher level object type, the phy, represents a physical device. Phys are also exposed to userspace in recent kernels and they only exist for wireless devices, not for wired ethernet. Phys can be manually managed by the admin user with the iw command. Interfaces under each phy can be added and removed as needed, within the phy's advertised capabilities. Like interfaces, phys can be freely renamed but have immutable indexes.

On the DBus API, the net.connman.iwd.Adapter interface corresponds to a phy while the net.connman.iwd.Device corresponds to a network interface.

Legacy interface management

Assuming the driver has created a default interface for a phy, it's possible to execute all the basic station-mode (aka. Managed mode) operations, like scanning for WiFi networks and connecting to one, and never touch the interface setup. This is how current wpa-supplicant-based, wicd-based and pre-0.18 IWD -based systems work. On those systems the existence of the phys can be completely ignored as the userspace assumes a 1:1 mapping of physical devices to interfaces.

There are some exceptions. For Access-point mode (supported both by Android and desktop systems running e.g. Network Manager), in this setup it's necessary to change the interface type from station/managed to AP mode. Similarly for Ad-Hoc mode. This has the downside that due to the assumed 1:1 mapping of physical devices to interfaces, the device can only be used in one mode at a time. In reality some popular WiFi adapters support simultaneous station and AP operation and other combinations.

For P2P support it's necessary to actively create an interface for scanning and additionally one new interface for each P2P connection. wpa_supplicant supports that but at the time of writing this is only really used on Android. Desktop user environments have scarce P2P support.

Interface management in IWD

Starting with 0.18, IWD attempts to start with a clean phy with no interfaces when the new phy is detected (on startup or device hotplug). If IWD finds a default interface on a new phy, or any other interfaces, those will be removed during initalization and only the combination of interfaces needed by the user are going to be maintained from then on.

In practice this doesn't change a lot as during normal station-mode usage there's still going to be one interface on the phy, and optionally one p2p interface used for scanning when P2P is supported.

As a consequence IWD doesn't need to worry what state a given interface was in before IWD started using it as it only has to deal with freshly created interfaces. Another consequence is that if IWD is stopped by the admin or a power-user, there will be no wireless interfaces on the system. The kernel will have deleted the interfaces owned by IWD when the IWD process was killed. If the user wants to manually do anything with their wireless device they will need to first create a new interface using a command like

# iw phy phy0 interface add wlp2s0 type station

When IWD is running and the admin or another daemon creates new interfaces, those will be ignored by IWD. Those interfaces may however use up the driver's allowed number interfaces of each type and prevent IWD from offering the user some features.

Fallback to legacy mode

IWD will fall back to the legacy mechanism if it detects that a phy's driver does not support the needed interface management commands. It will also do this if the -i and/or -I options are used (there shouldn't normally be any need for that and in any case -p and -P are preferred). The legacy logic can also be forced (or inhibited) by using the use_default_interface main.conf setting as documented here.

udev interface renaming

On systems running the systemd udev at the time of writing there's a race condition affecting the interface renaming by udev. The race is a result of the kernel disallowing interface renames once the interface has been activated (UP) by IWD. IWD and udev may be detecting the new interface simultaneously and timing will decide whether udev will be able to perform the rename or not.

The change in how IWD manages interfaces doesn't really affect the race condition in any way. Optimally the kernel should allow those renames to go through independent of IWD.

Optimally also udev should not even need to rename the interfaces as those names have no meaning unless a user is manually configuring their networking, which usually means they will not want to run IWD as IWD assumes full authority over wireless configuration and the user will only configure it through the DBus interface.

The goal for the udev renaming is that a given interface is always referred to by the same name over system reboots and device re-plugs. For that purpose the DBus interface exposes the Model/Vendor properties on each Adapter object (phy) although those are not necessarily unique on the system.

With this new interface management logic it would actually make more sense for the phy names to be persistent as phys refer to specific devices. There will usually be only one managed-mode interface under that phy which uniquely identifies that interface.

interface_lifecycle.txt · Last modified: 2019/05/09 02:05 by Andrew Zaborowski