1:orphan:
2
3.. SPDX-License-Identifier: GPL-2.0
4.. include:: <isonum.txt>
5
6===================================================================
7mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
8===================================================================
9
10:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
11
12This program is free software; you can redistribute it and/or modify
13it under the terms of the GNU General Public License version 2 as
14published by the Free Software Foundation.
15
16
17Introduction
18============
19
20mac80211_hwsim is a Linux kernel module that can be used to simulate
21arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
22test most of the mac80211 functionality and user space tools (e.g.,
23hostapd and wpa_supplicant) in a way that matches very closely with
24the normal case of using real WLAN hardware. From the mac80211 view
25point, mac80211_hwsim is yet another hardware driver, i.e., no changes
26to mac80211 are needed to use this testing tool.
27
28The main goal for mac80211_hwsim is to make it easier for developers
29to test their code and work with new features to mac80211, hostapd,
30and wpa_supplicant. The simulated radios do not have the limitations
31of real hardware, so it is easy to generate an arbitrary test setup
32and always reproduce the same setup for future tests. In addition,
33since all radio operation is simulated, any channel can be used in
34tests regardless of regulatory rules.
35
36mac80211_hwsim kernel module has a parameter 'radios' that can be used
37to select how many radios are simulated (default 2). This allows
38configuration of both very simply setups (e.g., just a single access
39point and a station) or large scale tests (multiple access points with
40hundreds of stations).
41
42mac80211_hwsim works by tracking the current channel of each virtual
43radio and copying all transmitted frames to all other radios that are
44currently enabled and on the same channel as the transmitting
45radio. Software encryption in mac80211 is used so that the frames are
46actually encrypted over the virtual air interface to allow more
47complete testing of encryption.
48
49A global monitoring netdev, hwsim#, is created independent of
50mac80211. This interface can be used to monitor all transmitted frames
51regardless of channel.
52
53
54Simple example
55==============
56
57This example shows how to use mac80211_hwsim to simulate two radios:
58one to act as an access point and the other as a station that
59associates with the AP. hostapd and wpa_supplicant are used to take
60care of WPA2-PSK authentication. In addition, hostapd is also
61processing access point side of association.
62
63::
64
65
66    # Build mac80211_hwsim as part of kernel configuration
67
68    # Load the module
69    modprobe mac80211_hwsim
70
71    # Run hostapd (AP) for wlan0
72    hostapd hostapd.conf
73
74    # Run wpa_supplicant (station) for wlan1
75    wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
76
77
78More test cases are available in hostap.git:
79git://w1.fi/srv/git/hostap.git and mac80211_hwsim/tests subdirectory
80(http://w1.fi/gitweb/gitweb.cgi?p=hostap.git;a=tree;f=mac80211_hwsim/tests)
81