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