tests/hwsim/README

   1 Automated hostapd/wpa_supplicant testing with mac80211_hwsim
   2 ------------------------------------------------------------
   3
   4 This directory contains testing infrastructure and test cases to run
   5 automated tests of full hostapd and wpa_supplicant functionality. This
   6 testing is done with the help of mac80211_hwsim which is Linux kernel
   7 driver that simulates IEEE 802.11 radios without requiring any
   8 additional hardware. This setup most of the hostapd and wpa_supplicant
   9 functionality (and large parts of the Linux cfg80211 and mac80211
  10 functionality for that matter) to be tested.
  11
  12 mac80211_hwsim is loaded with five simulated radios to allow different
  13 device combinations to be tested. wlantest is used analyze raw packets
  14 captured through the hwsim0 monitor interface that capture all frames
  15 sent on all channels. wlantest is used to store the frames for
  16 analysis. Three wpa_supplicant processes are used to control three
  17 virtual radios and one hostapd process is used to dynamically control
  18 the other two virtual radios. hwsim_test is used to verify that data
  19 connection (both unicast and broadcast) works between two netdevs.
  20
  21 The python scripts and tools in this directory control test case
  22 execution. They interact wpa_supplicant and hostapd through control
  23 interfaces to perform the operations. In addition, wlantest_cli and
  24 hwsim_test are used to verify that operations have been performed
  25 correctly and that the network connection works in the expected way.
  26
  27 These test cases are run automatically against the hostap.git commits
  28 for regression testing and to help in keeping the hostap.git master
  29 branch in stable state. Results from these tests are available here:
  30 http://buildbot.w1.fi/hwsim/
  31
  32
  33 Building binaries for testing
  34 -----------------------------
  35
  36 You will need to build (or use already built) components to be
  37 tested. These are available in the hostap.git repository and can be
  38 built for example as follows:
  39
  40 cd ../../wpa_supplicant
  41 cp ../tests/hwsim/example-wpa_supplicant.config .config
  42 make clean
  43 make
  44 cd ../hostapd
  45 cp ../tests/hwsim/example-hostapd.config .config
  46 make clean
  47 make hostapd hlr_auc_gw
  48 cd ../wlantest
  49 make clean
  50 make
  51 cd ../mac80211_hwsim/tools
  52 make
  53
  54 Alternatively, the build.sh script here can be used to run these steps
  55 with conditional creation of .config files only if they do not exist.
  56
  57 The test scripts can find the binaries in the locations where they were
  58 built. It is also possible to install hwsim_test and wlantest_cli
  59 somewhat on the path to use pre-built tools.
  60
  61 Please note that some of the configuration parameters used to enable
  62 more testing coverage may require development packages that may not be
  63 installed by default in many distributions. For example, following
  64 Debian/Ubuntu packages are likely to be needed:
  65 - binutils-dev
  66 - libsqlite3-dev
  67 - libpcap-dev
  68
  69
  70 wpaspy
  71 ------
  72
  73 The python scripts use wpaspy.py to interact with the wpa_supplicant
  74 control interface, but the run-tests.py script adds the (relative)
  75 path into the environment so it doesn't need to be installed.
  76
  77
  78 mac80211_hwsim
  79 --------------
  80
  81 mac80211_hwsim kernel module is available from the upstream Linux
  82 kernel. Some Linux distributions enable it by default. If that's not the
  83 case, you can either enable it in the kernel configuration
  84 (CONFIG_MAC80211_HWSIM=m) and rebuild your kernel or use Backports with
  85 CPTCFG_MAC80211_HWSIM=m to replace the wireless LAN components in the
  86 base kernel.
  87
  88
  89 sudo
  90 ----
  91
  92 Some parts of the testing process requires root privileges. The test
  93 scripts are currently using sudo to achieve this. To be able to run the
  94 tests, you'll probably want to enable sudo with a timeout to not expire
  95 password entry very quickly. For example, use this in the sudoers file:
  96
  97 Defaults        env_reset,timestamp_timeout=180
  98
  99 Or on a dedicated test system, you could even disable password prompting
 100 with this in sudoers:
 101
 102 %sudo   ALL=NOPASSWD: ALL
 103
 104
 105 Other network interfaces
 106 ------------------------
 107
 108 Some of the test scripts are still using hardcoded interface names, so
 109 the easiest way of making things work is to avoid using other network
 110 devices that may use conflicting interface names. For example, unload
 111 any wireless LAN driver before running the tests and make sure that
 112 wlan0..4 gets assigned as the interface names for the mac80211_hwsim
 113 radios. It may also be possible to rename the interface expectations in
 114 run-tests.py to allow other names to be used.
 115
 116 Please also note that some commonly enabled tools, like NetworkManager,
 117 may end up trying to control new network interfaces automatically. This
 118 can result in conflicts with the test scripts and you may need to
 119 disable such network services or at least mark the mac80211_hwsim wlan#
 120 interfaces as umanaged. As an example, this can be done in
 121 /etc/NetworkManager/NetworkManager.conf with following addition:
 122
 123 [keyfile]
 124 unmanaged-devices=mac:02:00:00:00:00:00;mac:02:00:00:00:01:00;mac:02:00:00:00:02:00;mac:02:00:00:00:03:00;mac:02:00:00:00:04:00
 125
 126
 127 Running tests
 128 -------------
 129
 130 Simplest way to run a full set of the test cases is by running
 131 run-all.sh in tests/hwsim directory. This will use start.sh to load the
 132 mac80211_hwsim module and start wpa_supplicant, hostapd, and various
 133 test tools. run-tests.sh is then used to run through all the defined
 134 test cases and stop.sh to stop the programs and unload the kernel
 135 module.
 136
 137 run-all.sh can be used to run the same test cases under different
 138 conditions:
 139
 140 # run normal test cases
 141 ./run-all.sh
 142
 143 # run normal test cases under valgrind
 144 ./run-all.sh valgrind
 145
 146 # run normal test cases with Linux tracing
 147 ./run-all.sh trace
 148
 149 # run normal test cases with multi channel support (see details below)
 150 ./run-all.sh channels=<num of channels>
 151
 152 run-all.sh directs debug logs into the logs subdirectory (or $LOGDIR if
 153 present in the environment). Log file names include the current UNIX
 154 timestamp and a postfix to identify the specific log:
 155 - *.log0 = wpa_supplicant debug log for the first radio
 156 - *.log1 = wpa_supplicant debug log for the second radio
 157 - *.log2 = wpa_supplicant debug log for the third radio
 158 - *.hostapd = hostapd debug log
 159 - hwsim0 = wlantest debug log
 160 - hwsim0.pcapng = capture with all frames exchanged during the tests
 161 - *.log = debug prints from the test scripts
 162 - trace.dat = Linux tracing record (if enabled)
 163 - hlr_auc_gw - hlr_auc_gw (EAP-SIM/AKA/AKA' authentication) log
 164 - auth_serv - hostapd as RADIUS authentication server log
 165
 166
 167 For manual testing, ./start.sh can be used to initialize interfaces and
 168 programs and run-tests.py to execute one or more test
 169 cases. run-tests.py output verbosity can be controlled with -d (more
 170 verbose debug output) and -q (less verbose output) on the command
 171 line. "-f <module name>" (pointing to file test_<module name>.py) can be
 172 used to specify that all test cases from a single file are to be
 173 run. Test name as the last command line argument can be specified that a
 174 single test case is to be run (e.g., "./run-tests.py ap_pmf_required").
 175
 176 Notice that some tests require the driver to support concurrent
 177 operation on multi channels in order to run. These tests will be skipped
 178 in case the driver does not support multi channels. To enable support
 179 for multi channel, the number of supported channel is passed as an
 180 argument to run-all.sh or start.sh
 181
 182
 183 Adding/modifying test cases
 184 ---------------------------
 185
 186 All the test cases are defined in the test_*.py files. These are python
 187 scripts that can use the local helper classes to interact with the test
 188 components. While various python constructs can be used in the scripts,
 189 only a minimal level of python knowledge should really be needed to
 190 modify and add new test cases. The easiest starting point for this is
 191 likely to take a look at some of the example scripts. When working on a
 192 new test, run-tests.py with -d and the test case name on the command
 193 line is a convenient way of verifying functionality.
 194
 195 run-tests.py will automatically import all test cases from the test_*.py
 196 files in this directory. All functions starting with the "test_" prefix
 197 in these files are assumed to be test cases. Each test case is named by
 198 the function name following the "test_" prefix.
 199
 200
 201 Results database
 202 ----------------
 203
 204 run-tests.py can be requested to write results from the execution of
 205 each test case into an sqlite database. The "-S <path to database>" and
 206 "-b <build id>" command line arguments can be used to do that. The
 207 database must have been prepared before this, e.g., with following:
 208
 209 cat | sqlite3 /tmp/example.db <<EOF
 210 CREATE TABLE results (test,result,run,time,duration,build,commitid);
 211 CREATE INDEX results_idx ON results (test);
 212 CREATE INDEX results_idx2 ON results (run);
 213 CREATE TABLE tests (test,description);
 214 CREATE UNIQUE INDEX tests_idx ON tests (test);
 215 CREATE TABLE logs (test,run,type,contents);
 216 CREATE INDEX logs_idx ON logs (test);
 217 CREATE INDEX logs_idx2 ON logs (run);
 218 EOF