Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

Wireless configuration
The wireless UCI configuration is located in 802.11 "wireless" subsystem.

/etc/config/wireless. Learn about the entire IEEE

Note1: By default the wireless is OFF. You can turn it on in the /etc/config/wireless by changing disabled 1 to disabled 0
In UCI CLI you do this with: uci set wireless.@wifi-device[0].disabled=0; uci commit wireless; wifi

Note2: In case your image does not contain the driver for your wireless chipset, simply install them with opkg and proceed with Regenerate Configuration.

Sections
A typical wireless config file contains at least one wifi device specifying general radio properties like channel, driver type and txpower and one wifi interface defining a wireless network on top of the radio device.

Wifi Devices
The wifi-device refer to physical radio devices present on the system. The options present in this section describe properties common accross all wireless networks on this radio interface, such as channel or antenna selection. In most cases there is only one radio adapter present on the device, so only one such section is defined, however on multi-radio hardware there may be multiple wifi-device sections - each referring to a different adapter. A minimal wifi-device declaration may look like the example below. Note that identifiers and options may vary for different chipset types or drivers.
config 'wifi-device' 'wl0' option 'type' 'broadcom' option 'channel' '6'

wl0 is the internal identifier for the wireless adapter broadcom specifies the chipset/driver type 6 is the wireless channel the device operates on
The possible options for device sections are listed in the table below. Note that not all options are used for all chipset/driver types, refer to the comments for further details.

Common Options
Name Type Required Default Description The type is determined on firstboot during the initial radio device detection - it is usually not required to change it. Used values are broadcom on brcm-2.4, atheros for madwifi or mac80211 for b43, ath5k and ath9k

type

string

yes

(autodetected)

1 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

phy

string

no/yes

(autodetected)

Specifies the radio phy associated to this section, it is usally autodetected and should not be changed. By default openwrt uses macaddr to identify the radio (more precise) but you can use phy instead, to be more hardware independant. This option is only used for type mac80211 and madwifi (trunk) Specifies the radio adapter associated to this section, it is not used to change the device mac but to identify the underlying interface. The value is autodetected at first boot or when you use phy parameter. If you wan't an hardware independant config (to restore the config on many routers) you should use phy parameter instead of macaddr. This option is only used for type mac80211 and madwifi (trunk)

macaddr

MAC address

yes/no

(autodetected)

disabled channel

boolean integer or "auto"

no

1 auto

Disables the radio adapter if set to 1. Removing this option or setting it to 0 will enable the adapter Specifies the wireless channel to use. In station mode the value auto is allowed, in access point mode an actual channel number must be given Selects the wireless protocol to use, possible values are 11b, 11bg, 11g, 11gdt (G + dynamic turbo, madwifi only), 11gst (G turbo, broadcom only), 11a, 11adt (A + dynamic turbo, madwifi only), 11ast (A + static turbo, madwifi only), 11fh (frequency hopping), 11lrs (LRS mode, broadcom only), 11ng (11N+11G, 2.4GHz, mac80211 only), 11na (11N+11A, 5GHz, mac80211 only) or auto Specifies the channel width in 11ng and 11na mode, possible values are: HT20 (single 20MHz channel), HT40- (2x 20MHz channels, 2. channel below) or HT40+ (2x 20MHz channels, 2. channel above). Cf. why.can.t.i.use.ht40.with.channel.11. This option is only used for type mac80211

yes

hwmode

string

no

(driver default)

htmode

string

no

(driver default)

ht_capab txpower diversity rxantenna

string integer boolean

no no no

(driver default) (driver default)

Specifies the available capabilities of the radio. The values are autodetected. This option is only used for type mac80211 Specifies the transmission power in dBm Enables or disables the automatic antenna selection by the driver Specifies the antenna for receiving, the value may be driver specific, usually it is 1 for the first and 2 for the second antenna. Specifying 0 enables automatic selection by the driver if supported. This option has no effect if diversity is enabled Specifies the antenna for transmitting, values are identical to

1
(driver default)

integer

no

txantenna

integer

no

(driver default)

rxantenna
Selects the antenna, possible values are vertical for internal vertical polarization, horizontal for internal horizontal polarization or external to use the external antenna connector Only used on the Ubiquiti NanoStation device family instead of the rxantenna/txantenna settings. Specifies the mac filter policy, disable to disable the filter, allow to treat it as whitelist or deny to treat it as blacklist. Supported for the mac80211 since r25105
[https://dev.openwrt.org/changeset/25105/trunk]

antenna

string

no

(driver default)

macfilter

string

no

disable

maclist

list of MAC no addresses

List of MAC addresses to put into the mac filter. (none) Supported for the mac80211 since r25105
[https://dev.openwrt.org/changeset/25105/trunk]

2 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

country

varies

no

(driver default)

Specifies the country code, affects the available channels and transmission powers. For type broadcom a two letter country code is used (EN or DE). The madwifi driver expects a numeric code. Not supported for the mac80211 type yet (supported in trunk) Distance between the ap and the furthest client in meters .

distance

integer

no

(driver default)

Only supported by madwifi, and the mac80211 type (in trunk) Do not scan for overlapping BSSs in HT40+/- mode. Only supported by mac80211 Turning this on will violate regulatory requirements! Set the beacon interval. This is the time interval between beacon frames, measured in units of 1.024 ms. hostapd permits this to be set between 15 and 65535. This option only has an effect on ap and adhoc wifi-ifaces. Only supported by mac80211 (in trunk)

noscan

boolean

no

beacon_int integer

no

100 (hostapd default)

basic_rate list

no

(hostapd/driver default)

Set the supported basic rates. Each basic_rate is measured in kb/s. This option only has an effect on ap and adhoc wifi-ifaces. Only supported by mac80211 (in trunk)

Broadcom Options
The options below are only used by the proprietary Broadcom driver (type
Name Type Required Default Description Enables Broadcom frame bursting if supported

broadcom).

frameburst boolean no maxassoc slottime

integer integer no no

(driver default) Limits the maximum allowed number of associated clients (driver default) Slot time in milliseconds

Madwifi Options
The following options are only used by the Madwifi driver (type
Name Type Required Default Description Enables software based LED control in the driver Enables outdoor channels in the 5GHz band

atheros).

softled outdoor

boolean no boolean no

1 0

regdomain number no

(driver default) Overrides the regulatory domain setting

Wifi Networks
A complete wireless configuration contains at least one wifi-iface section per adapter to define a wireless network on top of the hardware. Some drivers support multiple wireless networks per device:

broadcom if the core revision is greater or equal 9 (see dmesg | grep corerev) madwifi always supports multiple networks mac80211 STA mode supported on trunk. STA and AP at the same time is not yet
supported(r22989). A minimal example for a
config 'wifi-iface' option 'device'

wifi-iface declaration is given below.

'wl0'

3 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

option option option option option 'network' 'mode' 'ssid' 'encryption' 'key' 'lan' 'ap' 'MyWifiAP' 'psk2' 'secret passphrase'

http://wiki.openwrt.org/doc/uci/wireless

wl0 is the identifier for the underlying radio hardware lan specifies the network interface the wifi is attached to ap is the opetion mode, Access Point in this example MyWifiAP is the broadcasted SSID psk2 specifies the wireless encryption method, WPA2 PSK here secret passphrase is the secret WPA passphrase Common Options
The most common configuration option for
Name Type string

wifi-iface sections are listed below.

Default (first device id) Description Specifies the used wireless adapter, must refer to one of the defined wifi-device sections Selects the operation mode of the wireless network, ap for Access Point, sta for managed (client) mode, adhoc for Ad-Hoc, wds for static WDS and monitor for monitor mode, mesh for 802.11s mesh mode

Required yes

device

mode

string

yes

ap

mesh mode only supported by mac80211 (in

trunk)

ssid bssid

string

yes

OpenWrt
(driver default)

The broadcasted SSID of the wireless network Override the BSSID of the network, only applicable in

BSSID no address

adhoc or sta mode. In wds mode specifies the

BSSID of another AP to create WDS with. The Mesh ID as defined in IEEE 802.11s. If set, the wireless interface will join this mesh network when brought up. If not, it is necessary to invoke iw <iface> mesh join <mesh_id> to join a mesh after the interface is brought up. Only supported by mac80211 (in trunk) Turns off SSID broadcasting if set to 1 Isolate wireless clients from each other, only applicable in ap mode. May not be supported in the original Backfire release for mac80211 Enables 802.11h support. Not supported for the mac80211 type yet Enables WMM (802.11e) support. Not supported for the mac80211 type for backfire(?) Supported in trunk, in fact default but configurable in trunk Specifies the network interface to attach the wireless to Wireless encryption method. none for an open network, wep for WEP, psk for WPA-PSK, or psk2 for WPA2-PSK. See the WPA modes table for additional possible values. For an access point in WEP mode, the default is "open system" authentication. Use wep+shared for "shared

mesh_id

Mesh ID no

none

hidden isolate doth

boolean no boolean no

0 0 0

boolean no

wmm

boolean no

network

string

yes

lan

encryption

string

no

none

4 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

key" authentication (less secure), wep+open to explicitly use "open system," or wep+mixed to allow either. wep+mixed is only supported by hostapd. In any WPA-PSK mode, this is a string that specifies the pre-shared passphrase from which the pre-shared key will be derived. If a 64-character hexadecimal string is supplied, it will be used directly as the pre-shared key instead. In WEP mode, this can be an integer specifying which key index to use (key1, key2, key3, or key4.) Alternatively, it can be a string specifying a passphrase or key directly, as in key1. In any WPA-Enterprise AP mode, this option has a different interpretation. WEP passphrase or key #1 (selected by the index in

key

integer or string

no

(none)

key1

key). This string is treated as a passphrase from

string no (none) which the WEP key will be derived. If a 10- or 26-character hexadecimal string is supplied, it will be used directly as the WEP key instead. WEP passphrase or key #2 (selected by the index in

key2 key3 key4 iapp_interface

string string string string

no no no no

(none) (none) (none) (none)

key), as in key1.
WEP passphrase or key #3 (selected by the index in

key), as in key1.
WEP passphrase or key #4 (selected by the index in

key), as in key1.
specify an interface which used for 802.11f (IAPP) only enabled when defined Enables IEEE 802.11d country IE (information element) advertisement in beacon and probe response frames. This IE contains the country code and channel/power map. Requires country. Enables MFP (802.11w) support (0 = disabled, 1 = optional, 2 = required). Only supported by the ath9k driver (in trunk)

ieee80211d

integer

no

ieee80211w

integer

no

ieee80211w_max_timeout

integer

no

(hostapd default)

Specifies the 802.11w Association SA Query maximum timeout. Only supported by the ath9k driver (in trunk) Specifies the 802.11w Association SA Query retry timeout . Only supported by the ath9k driver (in trunk)

ieee80211w_retry_timeout integer maxassoc macaddr

no

(hostapd default)

integer

no

(hostapd/driver Specifies the maximum number of clients to connect. default) (hostapd/driver Overrides the MAC address used for the wifi interface. default) Set the DTIM (delivery traffic information message) period. There will be one DTIM per this many beacon frames. This may be set between 1 and 255. This option only has an effect on ap wifi-ifaces. Only supported by mac80211 (in trunk) Set the maximum allowed STA (client) listen interval. Association will be refused if a STA attempts to 65535 (hostapd associate with a listen interval greater than this value. default) This option only has an effect on ap wifi-ifaces. Only supported by mac80211 (in trunk)

mac no address

dtim_period

integer

no

2 (hostapd default)

max_listen_int

integer

no

5 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

Sets the fixed multicast rate, measured in kb/s.

mcast_rate

integer

no

(driver default)

Only supported by madwifi, and mac80211 (for type adhoc in trunk)

See the WPA tables below for a full listing of WPA related options used for WPA2 Enterprise (802.1x)

Madwifi Options
The options in the table below only work with type
Name Type Required Default

atheros.
Description

ar bgscan bursting ff frag minrate maxrate nosbeacon sw_merge probereq rate rts turbo uapsd wds wdssep xr

boolean no boolean no boolean no

0 0 0 0 0
(none)

Enables AR support Enables background scanning Enables frame bursting Enables hardware compression Enables fast frames Fragmentation threshold

compression boolean no
boolean no integer integer integer no no no

(driver default) Limit the minimum rate used (driver default) Limit the maximum rate used

boolean no boolean no boolean no integer integer no no

0 0 1

Disables the hardware beacon timer, only applicable in Managed mode Disables the hardware beacon timer, only applicable in IBSS mode Enables probe responses (AP will not appear in wifi scans if disabled)

(driver default) Use a fixed rate (driver default) Override the RTS/CTS threshold

boolean no boolean no boolean no boolean no boolean no

0 0 0 0 0

Enables turbo mode Enables Unscheduled Automatic Power Save Delivery (UAPSD) Enables Lazy-WDS, only applicable in Access Point or Managed mode Separates WDS clients from each other Enables XR support, only applicable in Managed mode

WPA Modes
Besides the WPA mode, the encryption option also specifies the group and peer ciphers to use. To override the cipher, the value of encryption must be given in the form mode+cipher. See the listing below for possible combinations.
Value WPA Version WPA2 Personal (PSK) WPA2 Personal (PSK) WPA2 Personal (PSK) Ciphers TKIP, CCMP TKIP CCMP

psk2+tkip+ccmp psk2+tkip+aes psk2+tkip psk2+ccmp psk2+aes psk2 psk+tkip+ccmp psk+tkip+aes psk+tkip psk

WPA Personal (PSK) WPA Personal (PSK)

TKIP, CCMP TKIP

6 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

psk+ccmp psk+aes

WPA Personal (PSK)

CCMP

mixed-psk+tkip+ccmp mixed-psk+tkip+aes WPA/WPA2 Personal (PSK) mixed mode TKIP, CCMP mixed-psk mixed-psk+tkip mixed-psk+ccmp mixed-psk+aes wpa2+tkip+ccmp wpa2+tkip+aes wpa2+ccmp wpa2+aes wpa2 wpa2+tkip wpa+tkip+ccmp wpa+tkip+aes wpa+ccmp wpa+aes wpa+tkip wpa
WPA/WPA2 Personal (PSK) mixed mode TKIP WPA/WPA2 Personal (PSK) mixed mode CCMP WPA2 Enterprise TKIP, CCMP

WPA2 Enterprise WPA2 Enterprise WPA Enterprise WPA Enterprise WPA Enterprise

CCMP TKIP TKIP, CCMP CCMP TKIP

mixed-wpa+tkip+ccmp mixed-wpa+tkip+aes WPA/WPA2 Enterprise mixed mode mixed-wpa mixed-wpa+tkip mixed-wpa+ccmp mixed-wpa+aes
WPA/WPA2 Enterprise mixed mode WPA/WPA2 Enterprise mixed mode

TKIP, CCMP TKIP CCMP

WPA Enterprise (Access Point)

Listing of Access Point related options for WPA Enterprise.
Name Default (none) Description RADIUS server to handle client authentication RADIUS port Shared RADIUS secret WPA Group Cipher rekeying interval in seconds

server port key

1812
(none)

wpa_group_rekey 600

The options below are for hostapd (not the Broadcom nas authenticator)

auth_server auth_port auth_secret acct_server acct_port acct_secret nasid

(none)

RADIUS authentication server to handle client authentication RADIUS authentication port Shared authentication RADIUS secret RADIUS accounting server to handle client authentication RADIUS accounting port Shared accounting RADIUS secret NAS ID to use for RADIUS authentication requests

1812
(none) (none)

1813
(none) (none)

WPA Enterprise (Client)

Listing of Client related options for WPA Enterprise.

7 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

At the time of writing only the madwifi driver supports WPA Enterprise in client mode.
Name Default (none) Description Defines the EAP protocol to use, possible values are tls for EAP-TLS and peap or ttls for EAP-PEAP

eap_type auth identity password ca_cert client_cert priv_key

MSCHAPV2 Defines the phase 2 authentication method to use, only applicable if eap_type is peap or ttls
(none) (none) (none) (none) (none) EAP identity to send during authentication Password to send during EAP authentication Specifies the path the CA certificate used for authentication Specifies the client certificate used for the authentication Specifies the path to the private key file used for authentication, only applicable if eap_type is set to tls Password to unlock the private key file, only works in conjunction with priv_key

priv_key_pwd (none)

Configuring Encryption
OpenWrt supports WPA/WPA2 PSK ("WPA Personal"), 802.11i ("WPA Enterprise") and WEP encryption. The used encryption protocol is defined per network in the wifi-iface sections of the wireless configuration. All encryption settings can also be changed via the LuCI (Network > Wifi). Read more...

Start/Stop Wireless
Wireless interfaces are brought up and down with the wifi command. To (re)start the wireless after a configuration change, use wifi, to disable the wireless, run wifi down. In case your platform carries multiple wireless devices it is possible to start or run down each of them individually by making the wifi command be followed by the device name as a second parameter. Note: The wifi command has an optional first parameter that defaults to 'up' , i.e. start the device. To make the second parameter indeed a second parameter it is mandatory to give a first parameter which can be anything except down. E.g. to start the interface wlan2 issue: wifi up wlan2; to stop that interface: wifi down wlan2. If the platform has also e.g. wlan0 and wlan1 these will not be touched by stopping or starting wlan2 selectively.

Regenerate Configuration
To rebuild the configuration file, e.g. after installing a new wireless driver, remove the existing wireless configuration (if any) and use the wifi detect command with stdout redirected to the /etc/config/wireless file:
rm -f /etc/config/wireless wifi detect > /etc/config/wireless

Notes
Currently, the mac80211 family of wifi drivers does not support DFS. However, DFS is mandatory for

8 of 9

03/07/2012 05:07 AM

Wireless configuration - OpenWrt Wiki

http://wiki.openwrt.org/doc/uci/wireless

many channels in the 5GHz band. If you provide a channel in your wireless config that requires DFS according to your country regulations, the radio1 device won't start up. You can check that with
iw reg get

If you provided DE as your country code (Germany), you'll notice that all channels in the 5GHz band require DFS, so you won't be able to use the radio1 device. A workaround is to choose FR, instead. This enables channels 36, 40, 44 and 48 at least. However, it might be illegal to use a foreign country code. Note: The output of iw reg get gives you just the frequences. Matching them to channels may be done via
iwlist wlan1 chan

Adjust other wireless settings as appropriate. *AS OF 2010-01-11, THE 5 GHZ WIRELESS INTERFACE WILL NOT COME UP UNLESS YOU SET THE COUNTRY CODE AND CHANNELS AS DESCRIBED ABOVE.* After saving your wireless config, execute this command to force the system to reread the configs and bring up the radios:
wifi

Examples
guest-wlan Back to top doc/uci/wireless.txt Last modified: 2012/02/03 21:19 by orca

9 of 9

03/07/2012 05:07 AM