hostapd Linux documentation page
About hostapd
hostapd is an IEEE 802.11 AP and IEEE 802.1X/WPA/WPA2/EAP/RADIUS Authenticator.
This page is dedicated to the Linux documentation of it's
implementation and use. Please refer to the hostapd home page for
information for other Operating Systems.
As far a Linux is concerned, out of the old drivers you can only use these 3 drivers with hostapd:
All new mac80211 based drivers that implement AP functionality are supported with hostapd's nl80211 driver.
The
mac80211 subsystem moves all aspects of master mode into user space.
It depends on hostapd to handle authenticating clients, setting
encryption keys, establishing key rotation policy, and other aspects of
the wireless infrastructure. Due to this, the old method of issuing
'iwconfig mode master' no longer works.
Userspace programs like hostapd now use netlink (the nl80211 driver) to
create a master mode interface for your traffic and a monitor mode
interface for receiving and transmitting management frames.
Getting hostapd
Using your distributions hostapd
It is
advisable to try your distributions version of hostapd before taking the
time to compile and install your own copy. This will make future
maintenance easier as you'll be able to use the init scripts shipped by
the distro and hostapd will be updated by it as well. If your
distribution ships 0.6.8 or later, you can test with this bare minimum
config by creating the file hostapd-minimal.conf:
#change wlan0 to your wireless device
interface=wlan0
driver=nl80211
ssid=test
channel=1
If that config errors out with something like:
hostapd $ sudo hostapd ./hostapd-minimal.conf
Configuration file: ./hostapd-minimal.conf
Line 2: invalid/unknown driver 'nl80211'
1 errors found in configuration file './hostapd-minimal.conf'
that
means that your distro is not shipping hostapd with nl80211 driver
support and you'll need to follow the building instructions that follow.
If it works, you can skip down to the configuring hostapd section. If
not, continue on.
Download and compile hostapd
Using
hostapd with nl80211 requires you to have at least libnl-1.0 pre8 as
this release introduced genl, Generic Netlink, which nl80211 relies on.
Most distributions are shipping this or a later release by now. To compile on fedora or other distibutions that separate out the headers from the binaries, you need the libnl-devel package.
Throughout this section, versions will be referred to by: x.y.z
ex: hostapd-0.6.8.tar.gz would be referred to as hostapd-x.y.z.tar.gz
You can get the latest development version of hostapd from the git repository with:
git clone git://w1.fi/srv/git/hostap.git
cd hostap/hostapd
Or you can get a stable release (0.6.8 or later reccomended) by downloading the tarball from http://w1.fi/hostapd/.
wget http://w1.fi/releases/hostapd-x.y.z.tar.gz
tar xzvf hostapd-x.y.z.tar.gz
cd hostapd-x.y.z/hostapd
Next,
we need to configure the hostapd build to enable nl80211 driver
support. Copy defconfig to .config, and open it in your preferred text
editor. Also, there are other options that you may want to enable, like
802.11n support if your hardware can do it. Most of the other
encryption types and features aren't needed for most applications, so if
you're questioning if you need to enable it, you probably don't need
to.
cp defconfig .config
vi .config
Now find this line:
#CONFIG_DRIVER_NL80211=y
and
uncomment it by removing the '#' sign. Repeat for other settings that
you may be interested in. The basic configuration, with only this line
uncommented is enough to get hostapd up and running with WPA/WPA2
authentication and encryption.
Next, compile hostapd:
make
if this fails with errors like:
driver_nl80211.c:21:31: warning: netlink/genl/genl.h: No such file or directory
driver_nl80211.c:22:33: warning: netlink/genl/family.h: No such file or directory
driver_nl80211.c:23:31: warning: netlink/genl/ctrl.h: No such file or directory
driver_nl80211.c:24:25: warning: netlink/msg.h: No such file or directory
driver_nl80211.c:25:26: warning: netlink/attr.h: No such file or directory
you
need to install/update libnl-1.0pre8 (or later). If all goes well and
the compilation finishes, try the minimal hostapd again, see the section
Using your distributions hostapd above for that.
hostapd # ./hostapd ./hostapd-minimal.conf
Configuration file: ./hostapd-minimal.conf
Using interface wlan1 with hwaddr 00:0d:0b:cf:04:40 and ssid 'test'
If
that starts as the example here shows, you can move on to configuring
hostapd. If it fails to start with errors about the driver not being
found, review the steps listed above for compiling hostapd again. If it
gets the error messages:
Hardware does not support configured mode
wlan0: IEEE 802.11 Hardware does not support configured mode (2)
Could not select hw_mode and channel. (-2)
wlan0: Unable to setup interface.
rmdir[ctrl_interface]: No such file or directory
then it means the hw_mode (a, b or g) in the config file is set to a value not supported by the hardware.
Configuring hostapd
Establishing Baseline for Configuration
Before
configuring hostapd, you need to know the capabilities of the clients
that will be using it. Not all clients will support all of the methods
you may want to implement, so a baseline configuration needs to be
established. You will also want to do a survey of your area to find the
channel that has the fewest other APs on it. When choosing which
channel to use, it is important to remember that the channels overlap
with any channels that are within 20MHz.
Examples of the baseline you might establish:
Encryption: wpa-psk + tkip
Wireless Mode: g
Normal for an environment that has to support semi legacy devices, that don't support ccmp or wpa2
Encryption: wpa2-psk + ccmp
Wireless Mode: g+n
Normal for an environment that has only up to date hardware and software
Encryption: wep
Wireless Mode: b
This is the works case scenario, as wep is broken and can be trivially cracked. Don't consider this as anything more than keeping casual free loaders out.
Once you've found your baseline, it's time to edit hostapd.conf. The configuration options will be broken into 3 sections:
Common Options: options that you will probably want to set
Additional Options: options that are likely useful to at least know you have
Extra Options: options that you aren't likely to need for most setups
Common Options
The most
basic set of options for using hostapd with the nl80211 driver have
already been provided as the hostapd-minimal.conf. That is all you need
if you don't care about consistantly being on the same channel, don't
need/want encryption, and don't need a flashy name. However, that is
not a realistic idea in the real world.
First,
we'll setup the wireless interface settings, then the wireless
environment settings, and finally the authentication and encryption.
Wireless Interface
Setting Summary:
- interface: Tells hostapd what wireless interface to use
- bridge: Set to a bridge if the wireless interface in use is part of a network bridge interface
- driver: For our purposes, always nl80211
If you only have 1 wireless interface, and it's going to be bridged with a wired interface, a good example setup would be:
interface=wlan0
bridge=br0
driver=nl80211
Wireless Environment
Setting Summary:
The
ssid is just for ease of configuration. It is what shows up in scan
results, and can help in configuring your clients. Check the scan
results for your area and choose a name.
hw_mode
needs to be something that all of your hardware supports. Setting this
to 'g' is probably the most common setup, and also enables backwards
compatability with 802.11b devices. Note, this is not where you enable
802.11n support, as 802.11n operates on top of 802.11a or 802.11g's
functionality.
channel
should be chosen so that it has the minimum overlap with other APs or
other networks in your area. 802.11 channels are 20mhz (4 channels)
wide in total, or 10mhz (2 channels) wide on each side. This means that
an access point on channel 3 will interfere with an acces point on
channel 1 or channel 5. Use this to pick a channel. Most consumer APs
default to channel 6, so you can use channel 1 or channel 11 in most
cases for the best results. Also note that the channels available to
you depends heavily entirerly on the local regulatory rules.
An example of a good normal setup is:
ssid=MyNetwork
hw_mode=g
channel=1
802.11n Setting Summary
802.11n
builds on the settings above, and adds additional functionality. If
your hardware doesn't support 802.11n, or you don't plan on using it,
you can ignore these.
- ieee80211n: Set to 1 to enable 802.11n support, 0 to disable it
- ht_capab: A list of the 802.11n features supported by your device
The
explanation of these settings in the sample config file are quite
helpful, so I'll suggest reading those. You can use the command 'iw
list' to find a short list of the capabilities of your device.
Example settings:
wme_enabled=1
ieee80211n=1
ht_capab=[HT40+][SHORT-GI-40][DSSS_CCK-40]
Authentication and Encryption
There is a
lot to the authentication and encryption options in hostapd. This
section will cover the basics as far as wep/wpa/wpa2 goes, as well as
some of the other commonly used options.
Settings Summary:
- macaddr_acl:
This controls mac address filtering. Mac addresses are easily spoofed,
so only consider the use of this to be augmenting other security
measures you have in place.
- auth_algs:
This is a bit field where the first bit (1) is for open auth, the
second bit (2) is for Shared key auth (wep) and both (3) is both.
- ignore_broadcast_ssid: This enables/disables broadcasting the ssid.
- wpa:
This is a bitfield like auth_algs. The first bit enables wpa1 (1), the
second bit enables wpa2 (2), and bothe enables both (3)
- wpa_psk/wpa_passphrase: These establish what the pre-shared key will be for wpa authentication.
- wpa_key_mgmt: This controls what key management algorithms a client can authenticate with.
- wpa_pairwise: This controls wpa's data encryption
- rsn_pairwise: This controls wpa2's data encryption
First,
scratch macaddr_acl and ignore_broadcast_ssid from your priorities as
they only enhance security (and even then, only slightly). Also, WEP
has been effectively broken now, so unless you HAVE to support wep,
scratch that from your list. This just leaves wpa/wpa2. Per the draft
standard, wpa2 is required for 802.11n, and as there are known attacks
on wpa now, wpa2 is the recommended authentication and encryption suite
to use. Fortunately, you can have both enabled at once. If Windows
clients are going to be connecting, you should leave ccmp encryption out
of the wpa_pairwise option, as some windows drivers have problems with
systems that enable it.
A good starting point for a wpa & wpa2 enabled access point is:
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=3
wpa_passphrase=YourPassPhrase
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP
If, alternately, you just want to support wpa2, you could use something like:
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=YourPassPhrase
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP
That
should be all of the settings that you'll need to change for a basic,
secure, access point using hostapd with an AP enabled mac80211 driver.
Additional Options
Dynamic VLAN tagging
Tunnel-Type=VLAN (13)
Tunnel-Medium-Type=802
Tunnel-Private-Group-ID=VLANID
To enable dynamic VLAN tagging the following options in hostapd.conf need to be set:
dynamic_vlan=1
vlan_file=/etc/hostapd.vlan
A
value of 0 disables dynamic VLAN tagging, a value of 1 allows dynamic
VLAN tagging and a value of 2 will reject the authentication if the
RADIUS server does not provide the appropriate tunnel attributes.
Furthermore,
hostapd needs to know how the VLAN interfaces should be named, this is
done through an additional config file as specified in vlan_file.
Example /etc/hostapd.vlan:
1 wlan0.1
* wlan0.#
This
will create a wlan0.1 interface on top of wlan0 and move all STAs with
the RADIUS supplied vlantag 1 to that interface. The second entry is
used to dynamically create VLAN interfaces on top of wlan0, hostapd will
create an interface wlan0.vlantag for each different vlantag as
supplied by the RADIUS server. For example, if a STA associates and the
RADIUS server attributes contain the vlantag 100 hostapd will create a
wlan0.100 interface and map the STA to this new interface.
1 comments
