mac80211_hwsim/README

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