3
0
mirror of https://git.kernel.org/pub/scm/network/wireless/iwd.git synced 2024-12-24 23:42:42 +01:00
The iNet Wireless Daemon (iwd) project aims to provide a comprehensive Wi-Fi connectivity solution for Linux based devices. The core goal of the project is to optimize resource utilization: storage, runtime memory and link-time costs. https://iwd.wiki.kernel.org/
Go to file
James Prestwood 07115e56a1 test-runner: Allow native hardware passthrough
This patch allows the host machine to pass through its PCI/USB network
cards into the test-runner virtual machine. By doing this we can run
nearly all the same autotests using physical/real wireless hardware.

First off, utilizing this feature requires a properly configured host
machine. There are kernel boot parameters and config files that need to
be configured before any of this will work. Unfortunately there is no
way around this, and hence this feature is not particularly aimed for
"the masses", but rather for specially configured test machines.

A new configuration file was introduced (tools/hw.conf) which is just an
example, it should be edited to work with the host machine using it. This
file merely holds the PCI addresses/USB bus of the devices you wish to pass
through to qemu.

Passing in this hardware config file with --hw <file> tells test-runner
that you are attempting to use this new feature. The tests themselves
do not need to change, its the initial test setup that required some
changes.

Since we are no longer creating radios we must discover the radios that
are present (once in the VM). This is done using borrowed code from IWD
to dump wiphys and interfaces. As the wiphys/interfaces are dumped, we
build up the wiphy list. In the hwsim case we still build this list up
when we create the radios, which hasn't changed. This does lead us to
have some special cleaup, where in the native case we just 'reset' the
list into its state pre-test (removing any hostapd flags). And as before
with the hwsim case we fully destroy and free the wiphy list, since a
new list will be created on the next test (along with new radios).

There should not need to be any changes to the tests themselves, but
potentially to some hw.conf files. A new key was introduced, 'needs_hwsim'
which need to be set on any tests that require the hwsim dbus API. This
tells test-runner to skip this test, otherwise it would fail in native
mode.

One last minor detail; the wiphy->id was changed to an unsigned int. This
is to match the type the kernel uses when dumping wiphys. Because of
this '0' is now the error case for both hwsim and native mode rather than
-1. Error checks were updated accordingly.
2019-05-01 17:03:34 -05:00
autotests auto-t: update testFILS to do PTK rekeys 2019-04-26 12:40:13 -05:00
client client: Add 'set-property' cmd for known networks 2019-04-11 10:57:14 -05:00
doc doc: Change interface naming after migration 2019-04-08 14:46:48 -05:00
linux linux: update nl80211.h to 4.20 kernel release 2019-01-24 17:25:22 -06:00
monitor monitor: Fix length parameter of strncpy for kernel names 2019-04-30 16:59:28 +02:00
plugins build: Add missing HAVE_CONFIG_H guards and include config.h 2019-04-04 14:02:38 +02:00
src scan: Reset sp.timeout in destroy callback 2019-05-01 11:47:50 -05:00
test test: Update list-known-networks use of DBus API 2019-04-11 11:01:33 -05:00
tools test-runner: Allow native hardware passthrough 2019-05-01 17:03:34 -05:00
unit unit: update test-{crypto,eapol} with PTK changes 2019-04-26 12:31:04 -05:00
wired eap: export session ID as key materials 2019-04-10 16:55:29 -05:00
.gitignore .gitignore: Update for renamed unit test 2019-04-09 00:03:08 -05:00
acinclude.m4 build: Use -Wvariadic-macros warning 2019-03-28 09:13:26 +01:00
AUTHORS AUTHORS: Mention Jordan's contributions 2018-08-09 10:46:47 -05:00
bootstrap build: Add support for internal ELL compilation 2014-05-11 11:01:11 -07:00
bootstrap-configure tools: Add configure option and D-Bus policy file for hwsim utility 2018-09-14 15:24:15 +02:00
ChangeLog Release 0.17 2019-04-12 21:51:30 +02:00
configure.ac Release 0.17 2019-04-12 21:51:30 +02:00
COPYING build: Add COPYING and INSTALL template files 2014-05-22 10:09:24 -07:00
HACKING doc: update kernel guide links 2019-03-20 10:50:00 -05:00
INSTALL build: Add COPYING and INSTALL template files 2014-05-22 10:09:24 -07:00
Makefile.am fils: implementation for FILS 2019-04-22 14:55:02 -05:00
README README: Add description for --enable-external-ell option 2018-10-19 19:31:32 +02:00
TODO TODO: Remove DLS task 2019-01-08 21:55:54 -06:00

Wireless daemon for Linux
*************************

Copyright (C) 2013-2018  Intel Corporation. All rights reserved.


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.


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.

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-sim-hardcoded

		Enable support for hard coded SIM keys

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

	--enable-ofono

		Enable support for oFono SIM authentication

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

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

		Enable generation of documentation and manual pages

		Note: This option does not provide any value right now


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/mailman/listinfo/iwd

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

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