Karma is a set of patches to access point software to get it to respond to probe requests not just for itself but for any ESSID requested. This allows the AP to act as a lure to draw in any clients probing for known networks. The original Karma patches were released by Dino Dia Zovi for Madwifi, I then took over and ported the patches to Madwifi-ng and have now taken them to the new hostapd.
Contrary to some people belief the Karma patches do not get the AP to send out beacons beyond any that it has been configured to in its normal setup as an AP. This means that when you start it up you should not expect to see a flood of new networks advertised in your client. The way it works is that most clients have a list of perfered networks, usually most of them set to auto-connect. When a clients wireless is enabled it works through this list sending out probe requests for each one. As soon as Karma sees a probe request it says yes, regardless of what ESSID is requested, and the client then tries to associate. Some clients may continue to probe for other APs with higher preference in their list so may will drop off the first one they associate with in preference of the highest one that Karma responds to.
Most clients, when they try to associate, will check the encryption level offered by the AP, if this doesn't match what is expected then the client won't associate. This causes a flapping client, one that connects then disconnects quickly over a short period. I have however seen some clients just dropping to no encryption if that is what is offered.
If you are testing Karma and clients aren't connecting make sure they have networks in their preferred list and that they are set to auto-connect, just because Windows has a list of preferred APs it doesn't mean that it is set to auto-connect to them all. I get regular bug reports from people saying that Karma isn't doing its job but when they finally check the list they find that no networks are set to auto-connect.
After some prodding from Zero_Chaos I've finally patched hostapd allowing Atheros users to move away from Madwifi-ng and into ath5k and ath9k. It should also open the field to users of Prism54 and various other cards but these are yet to be tested.
Below you have a choice of download options, a patch for the version 1.0 source or a pre-patched copy, there is also a sample config file. To use the pre-patched source simply untar the tarball, change to the hostapd directory and run make. You can then start the AP with the -dd parameter to get the Karma output messages. The config file I provide has an ESSID of "FreeInternet" which it is beaconing, this is designed to attract those who aren't probing for any networks but can be drawn in by the offer of a free connection. The config file is commented up so it should be easy to modify to your own needs.
You can check you are running the patched version of hostapd by checking the version information:
# ./hostapd -v hostapd v1.0 User space daemon for IEEE 802.11 AP management, IEEE 802.1X/WPA/WPA2/EAP/RADIUS Authenticator Copyright (c) 2002-2012, Jouni Malinen <email@example.com> and contributors Karma patches by Robin Wood - firstname.lastname@example.org
And start it like this:
# ./hostapd -dd ~/hostapd-karma.conf
If you grep out just the KARMA references then you will see something like this after a successful association:
KARMA: Probe Request from 00:c0:ca:2f:96:50 for SSID 'test' KARMA: Checking SSID for start of association, pass through test KARMA: Successful association of 00:c0:ca:2f:96:50
If you want to send all the output directly to a file rather than either to screen or having to pipe it to a file or other app, as of version 1.0 you can now use the -f option to send the output to a file. The only problem with this is you have to enable the feature at build time. The patched source, and the patch, both enable this but if you want to check for it look for CONFIG_DEBUG_FILE and make sure it is set to 1.
One problem I know about with this release is that when the client finally associates only the MAC address is printed, not the ESSID it is associated with. This is because by this point it is assumed that the association is with the same ESSID as in the config file so the original probed ESSID doesn't appear to be stored in any of the available structures. I'm working on this and will hopefully find a way to pass it through to here.
With the madwifi-ng drivers you could interact with the running driver using the iwpriv command, with Hostapd you get hostapd_cli which I think is a much nicer tool. I've extended the default version to add a bunch of new commands to control the Karma additions.
When you start hostapd_cli it searches for an instance of hostapd and connects automatically if it is able:
# ./hostapd_cli hostapd_cli v1.0 Copyright (c) 2004-2012, Jouni Malinen <email@example.com> and contributors This program is free software. You can distribute it and/or modify it under the terms of the GNU General Public License version 2. Alternatively, this software may be distributed under the terms of the BSD license. See README and COPYING for more details. Selected interface 'wlan0' Interactive mode > ? Commands: mib get MIB variables (dot1x, dot11, radius) sta <addr> get MIB variables for one station all_sta get MIB variables for all stations new_sta <addr> add a new station deauthenticate <addr> deauthenticate a station disassociate <addr> disassociate a station get_config show current configuration help show this usage help interface [ifname] show interfaces/select interface level <debug level> change debug level license show full hostapd_cli license ping send a ping, get a pong karma_change_ssid change the default SSID for when Karma is off karma_get_ssid get the default SSID for when Karma is off karma_enable enable Karma karma_disable disable Karma karma_black blacklist Karma karma_white whitelist Karma karma_get_black_white get the black/whitelist state of Karma karma_add_ssid add an SSID to the black/white list karma_del_ssid delete an SSID from the black/white list karma_get_state get the state of Karma karma_add_black_mac add a MAC to the black list karma_add_white_mac add a MAC to the white list quit exit hostapd_cli
I'm not going to go into a full explanation of how the commands work, the standard ones are documented elsewhere and the Karma ones should be self explanatory. One thing I will point out is that I got frustraited typing help to get the above list so I alised ? to do the same thing - small change, big relief!
Seeing as I haven't created any patches for this for a while I've lost track of where the Madwifi project is. Last time I tried to patch it I couldn't get it to build with my kernel (2.6.23) without further patching the drivers so I gave up. I've collected all my previous patches together below and if you need specific help with them for some reason then get in touch, otherwise I recommend moving to the hostapd method.