madwifi-ifupdown/ConfigurationOptions
MadWifi ifupdown configuration options
This page is the reference documentation for all configuration options offered by madwifi-ifupdown. The meaning of the table rows is:
- Meaning
- a short description of the meaning of a parameter
- Context
- defines the context (STA VAP, AP VAP, both VAP types) and "dependencies" (other options that must/must not be set)
- Allowed value(s)
- details about the allowed range of values that might be assigned to the option
- Example
- an example value that demonstrates the usage of the option
- Mandatory
- whether or not the option is mandatory
- Default value
- the default value that is used for non-mandatory options if the option is not specified by the user
Please note: "--" means "not applicable" or "no default", but is never a valid value for any of the options.
General
ath_parent
| Meaning | name of the parent device |
| Context | AP, STA |
| Allowed value(s) | interface name |
| Example | ath_parent wifi0 |
| Mandatory | yes |
| Default value | -- |
Recent versions of MadWifi support so called "VAPs" (refer to ath_vaptype for more details). Each VAP has a parent device, which needs to be defined with this option.
ath_vaptype
| Meaning | type of the VAP |
| Context | -- |
| Allowed value(s) | <AP|STA> |
| Example | ath_vaptype STA |
| Mandatory | no |
| Default value | STA |
Recent versions of MadWifi support so called "VAPs". VAP is short for "Virtual Access Point" (which unfortunately is a misleading term) and is a virtual WLAN interface which is attached to exactly one physical WLAN interface (the "parent device" or just "parent"). More than one VAP may be attached to a single parent, and they may even be of different types. The MadWifi users guide has more details in its section Using wlanconfig.
madwifi-ifupdown currently supports STA (client mode) and AP (access point) VAPs only.
ath_vapopts
| Meaning | special options used for creating the VAP |
| Context | AP, STA |
| Allowed value(s) | [bssid|-bssid] [nosbeacon] |
| Example | ath_vapopts bssid |
| Mandatory | no |
| Default value | bssid (AP VAP) | -- (STA VAP) |
Quoting the MadWifi users guide, section Using wlanconfig:
When AP and station VAPs coexist, the nosbeacon flag must be used when creating the station. This flag disables the use of hardware beacon timers for station mode operation. This is necessary because concurrent AP and station operation implies the station should not modify the TSF clock for the APs.
Creating multiple VAPs typically implies that the MAC address of each VAP is different. However, if the -bssid flag is used, then the MAC address of the underlying wireless device is cloned for the VAP being created.
ath_wirelessmode
| Meaning | the IEEE 802.11 mode of operation for the VAP |
| Context | AP, STA |
| Allowed value(s) | [11a|11b|11bg|11g] |
| Example | ath_wirelessmode 11g |
| Mandatory | no |
| Default value | 11bg |
11a means up to 108 MBps on 5 GHz frequencies. 11b, 11bg and 11g are working on 2.4 GHz instead. 11b allows up to 11 MBps, 11bg and 11g up to 108 MBps. 11bg allows fallback to 11b transfer rates, where 11g allows no such fallback.
Keep in mind that even though multiple VAPs are allowed per parent, they all share their parent's (single) radio. Which means that you can't have VAPs working on different frequency bands and not even on different channels of the same band.
Note: the mode will not be set for a VAP if its parent device already has at least one other VAP attached.
ath_ssid
| Meaning | STA: the ESSID to associate to, AP: the ESSID of the created cell |
| Context | AP, STA |
| Allowed value(s) | ESSID string |
| Example | ath_ssid MadWifi |
| Mandatory | no |
| Default value | MadWifi |
Quoting iwconfig(8):
Set the ESSID (or Network Name - in some products it may also be called Domain ID). The ESSID is used to identify cells which are part of the same virtual network. As opposed to the AP Address or NWID which define a single cell, the ESSID defines a group of cells connected via repeaters or infrastructure, where the user may roam transparently.
ath_channel
| Meaning | the channel that the VAP will be working on |
| Context | AP, STA |
| Allowed value(s) | integer value representing a valid channel number |
| Example | ath_channel 10 |
| Mandatory | no |
| Default value | -- |
The following needs to be considered here:
- In a scenario with a single radio and multiple VAPs, all VAPs will share the same channel. It's not possible to use different channels or frequency bands on each VAP.
- In a scenario with one STA VAP and one or more AP VAPs, where the STA VAP has not been set to a fixed channel, it will start scanning all available channels for a matching Access Point. As a result, the AP VAPs will follow the STA VAP's channel hopping, eventually changing to a different channel when the STA associates to its AP.
- The available channels depend on ath_wirelessmode as well as the countrycode/regdomain settings of the WLAN card you use. Read more.
ath_txpower
| Meaning | setting the transmit power used for this VAP |
| Context | AP, STA |
| Allowed value(s) | integer, valid range differs (see below) |
| Example | ath_txpower 15 |
| Mandatory | no |
| Default value | -- |
The TX power is given in units of dBm. The valid range differs, depending on the countrycode/regdomain setting and eventually on the type of card that is used as parent device.
access control
ath_acl
| Meaning | define MAC access control list mode |
| Context | AP |
| Allowed value(s) | <off|black|white> |
| Example | ath_acl white |
| Mandatory | no |
| Default value | off |
The MAC access control to configure which clients are allowed to associate with the AP VAP, based on their MAC address. If either "blacklist" or "whitelist" is selected, ath_acl_file names the file that contains a list of MAC addresses. In "blacklist" mode, every client is allowed to associate unless its MAC address is contained in ath_acl_file. In "whitelist" mode, clients are allowed to associate only if their MAC address is contained in ath_acl_file.
ath_acl_file
| Meaning | specify the file that contains the MAC addresses used for MAC ACL |
| Context | AP, ath_acl <black|white> |
| Allowed value(s) | path and name of the MAC address file |
| Example | ath_acl_file /etc/hostapd/hostapd.acl |
| Mandatory | yes |
| Default value | -- |
The file is expected to contain one MAC address per line. Originally, the MAC ACL is a feature provided by hostapd. In case ath_security is not set to wpa, the MAC ACL functionality will be configured "manually" by the if-pre-up.d-script.
encryption, authentication
ath_security
| Meaning | the type of encryption to use for this VAP |
| Context | AP, STA |
| Allowed value(s) | <none|wep|wpa|wpa1|wpa2|wpa1and2> |
| Example | ath_security wpa |
| Mandatory | no |
| Default value | none |
WEP is supported for AP and STA, WPA is currently supported for AP only (using hostapd).
wpa1, wpa2 and wpa1and2 determine which WPA variants are offered by the AP. Please note that WPA2 (aka IEEE802.11i) is only working with hostapd 0.5.2 or later. Enabling WPA2 while using hostapd 0.4.9 will prevent association/authentication of clients, no matter which variant of WPA they are trying to use!
wpa is the same as wpa1 for backward compatibility.
ath_wep_key[1-4]
| Meaning | definition of the up to 4 keys used for WEP encryption |
| Context | AP, STA, ath_security wep |
| Allowed value(s) | 40bit WEP: up 5 ASCII characters or 10 HEX digits 104bit WEP: 6 to 10 ASCII characters or 12 to 20 HEX digits |
| Example | ath_wep_key1 s:mywepkey ath_wep_key2 AABBCCDDEE |
| Mandatory | yes for ath_security wep (see below) |
| Default value | -- |
When using WEP encryption, you must define at least one WEP key. The length of the key determines the WEP strength that is applied for that key (as mentioned above).
Quoting iwconfig(8) about valid key notations:
To set the current encryption key, just enter the key in hex digits as XXXX-XXXX-XXXX-XXXX or XXXXXXXX. ... You can also enter the key as an ASCII string by using the s: prefix. Passphrase is currently not supported.
ath_wep_txkey
| Meaning | index of the WEP key used to encrypt traffic that is sent by this VAP |
| Context | AP, STA, ath_security wep |
| Allowed value(s) | <1|2|3|4> |
| Example | ath_wep_txkey 1 |
| Mandatory | no |
| Default value | 1 |
ath_wep_mode
| Meaning | whether to use open or shared security mode |
| Context | AP, STA, ath_security wep |
| Allowed value(s) | <open|shared> |
| Example | ath_wep_mode open |
| Mandatory | no |
| Default value | open |
Loose translation of a german-language knowledge base article from Lancom Systems:
WEP defines two different methods, the "open-system" authentication (OSA) and the shared key authentication (SKA). OSA means that every station can associate with an AP and receive unencrypted data, thus the term "authentication" is misleading here.
With SKA the access point uses a challenge-response-mechanism to make sure the station has a valid key. Only properly authenticated stations are allowed to exchange encrypted data with the access point. ...The disadvantage of the SKA is that an unencrypted challenge packet is involved. The client then encrypts the challenge and sends the result as response back to the access point. This provides an attacker with an unencrypted packet and its encrypted "version", making it way easier to attack the key.
For this reason OSA should always be prefered.
ath_wpa_pskfile
| Meaning | name of a file containing per-client PSK definitions |
| Context | AP, ath_security wpa |
| Allowed value(s) | path and name of a valid PSK file for hostapd |
| Example | ath_wpa_pskfile /etc/hostapd/hostapd.wpa-psk |
| Mandatory | no |
| Default value | -- |
Quoting hostapd.conf:
Optionally, WPA PSKs can be read from a separate text file (containing list of (PSK,MAC address) pairs. This allows more than one PSK to be configured. Use absolute path name to make sure that the files can be read on SIGHUP configuration reloads.
See also: hostapd.wpa-psk example
ath_wpa_psk
| Meaning | Pre-shared key given as 256bit secret in hex format |
| Context | AP, ath_security wpa |
| Allowed value(s) | exactly 64 hex digits |
| Example | ath_wpa_psk 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef |
| Mandatory | only if ath_wpa_passphrase is not set |
| Default value | -- |
ath_wpa_passphrase
| Meaning | Pre-shared key given as ASCII passphrase |
| Context | AP, ath_security wpa |
| Allowed value(s) | 8 to 63 ASCII characters |
| Example | ath_wpa_passphrase my secret passphrase |
| Mandatory | only if ath_wpa_psk is not set |
| Default value | -- |
ath_wpa_cfgfile
| Meaning | use this configuration file rather than generating one |
| Context | AP, ath_security wpa |
| Allowed value(s) | path and name of a valid hostapd configuration file |
| Example | ath_wpa_cfgfile /etc/hostapd/hostapd.conf |
| Mandatory | no |
| Default value | -- |
madwifi-ifupdown creates a temporary hostapd configuration file based on the parameters specified by the user. However, complex setups are not possible this way, and to support such setups a configuration file can be specified here. If this parameter is set, all other WPA-related parameters will be ignored.
STA-only
ath_nickname
| Meaning | the nickname used for a STA VAP |
| Context | STA |
| Allowed value(s) | nickname string |
| Example | ath_nickname myhost-ath0 |
| Mandatory | no |
| Default value | $(hostname)-$IFACE |
Quoting iwconfig(8):
Set the nickname, or the station name. Some 802.11 products do define it, but this is not used as far as the protocols (MAC, IP, TCP) are concerned and completely useless as far as configuration goes. Only some diagnostic tools may use it.
ath_dhcp_delay
| Meaning | maximum time to wait for successful association before trying to get a DHCP lease |
| Context | STA, "dhcp" method used for this VAP |
| Allowed value(s) | integer value |
| Example | ath_dhcp_delay 15 |
| Mandatory | no |
| Default value | 15 |
In order to get a DHCP lease, the STA VAP needs to have a valid association. This option is used for a hack which delays execution of the DHCP client until the STA VAP is associated. However, the delay is limited to the amount of time specified in this option, to prevent deadlocks in case the STA can not find a suitable Access Point at all.
AP-only
ath_hidessid
| Meaning | whether the ESSID should be broadcasted or not (aka "closed network") |
| Context | AP |
| Allowed value(s) | <yes|no> |
| Example | ath_hidessid yes |
| Mandatory | no |
| Default value | no |
This setting allows to disable broadcasting of the ESSID in the beacons that an AP VAP sends out frequently. This is usually regarded as a security measure, since a STA needs to know the exact ESSID in order to associate to that AP. However, the security gained by this step is void, since the ESSID is transmitted unencrypted in association requests from legitimate clients and can easily intercepted by an attacker. Read more in this article on Wi-Fi Planet.
ath_relay
| Meaning | whether associated clients are allowed to communicate with each other |
| Context | AP |
| Allowed value(s) | <yes|no> |
| Example | ath_relay no |
| Mandatory | no |
| Default value | yes |
By default, clients associated to an AP VAP are allowed to communicate with other clients of the same AP. In this case the AP needs to relay traffic sent from one client to another, since clients can not communicate directly with each other as they can in Ad-hoc mode for example. However, this feature can be turned off, which is useful when setting up a Hotspot for example.
not yet implemented
ath_distance
| Meaning | |
| Context | |
| Allowed value(s) | |
| Example | . |
| Mandatory | |
| Default value |
Not implemented yet, see ticket #6.
ath_rate
| Meaning | |
| Context | |
| Allowed value(s) | |
| Example | . |
| Mandatory | |
| Default value |
Not implemented yet, see ticket #8.
