Wi-Fi /etc/config/wireless

The UCI wireless configuration is located in /etc/config/wireless. Note that if the device has Ethernet ports, wireless is turned off by default and using LuCI → Network → Wireless will also write to this file.

See also: How do I enable Wi-Fi?

A typical wireless config file contains at least a pair of:

• wifi-device - specifies general radio properties like channel, driver type, and txpower
• wifi-iface - defines a wireless network on top of the wifi-device

The wifi-device refer to physical radio devices present on the system. The options present in this section describe properties common across all wireless interfaces on this radio device, such as channel or antenna selection.

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.

The options below are only used by the proprietary Broadcom driver (type broadcom).

The options below are only used by the Ubiquiti Nanostation family of devices.

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)
• mac80211

A minimal example for a wifi-iface declaration is given below.

config	wifi-iface
	option	device		'wl0'
	option	network		'lan'
	option	mode		'ap'
	option	ssid		'MyWifiAP'
	option	encryption	'psk2'
	option	key		'secret passphrase'

• wl0 is the identifier for the underlying radio hardware
• lan specifies the network interface that the Wi-Fi 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, at least 8 characters long

The common configuration options for wifi-iface sections are listed below.

Besides the encryption 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.

To use the WPA3 modes as access point, it is required to install the hostapd-openssl package.

To use the WPA3 modes as station (client), it is required to install the wpa-supplicant-openssl package.

To support both access point and station modes with WPA3, install the wpad-openssl package.

Listing of Access Point options for WPA Enterprise.

Listing of Client related options for WPA Enterprise.

When using WPA Enterprise type PEAP with Active Directory Servers, the “auth” option must be set to “auth=MSCHAPV2” or “auth=PAP”.

option auth 'auth=MSCHAPV2'

or

option auth 'auth=PAP'

The wpa_psk_file option specifies an external file containing a list of MAC address and PSK/passphrase pairs, allowing for multiple PSK/passphrases.

Example for a wpa_psk file:

00:00:00:00:00:00 secret_passphrase
00:00:00:00:00:00 another_passphrase
00:11:22:33:44:55 passphrase_for_a_specific_mac_only
00:22:33:44:55:66 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
vlanid=3 00:00:00:00:00:00 passphrase_for_vlan_id_3

In the example above, the last line uses the “vlanid=<id>” parameter: Clients can be assigned to VLAN-tagged interfaces depending on the PSK/passphrase. Additional configuration is required, re-using several parameters originally intended for RADIUS-based VLAN mappings:

Note: The vlan-related options above will be ignored or rejected by the default stripped down wpad-basic/hostapd-basic binaries. Like a RADIUS-based setup, these require the fully featured wpad/hostapd.

Example for a vlan file:

# VLAN ID to network interface mapping
1	vlan1
2	vlan2
3	vlan3
100	guest
# Optional wildcard entry matching all VLAN IDs. The first "#" in the interface name will be replaced with the VLAN ID.
# The network interfaces are created and removed dynamically when necessary.
*	vlan#
# Optional third parameter to override the bridge name
101	vlan100	bridge_name

Complete description copied from upstream hostapd.conf example:

# Workaround for key reinstallation attacks
#
# This parameter can be used to disable retransmission of EAPOL-Key frames that
# are used to install keys (EAPOL-Key message 3/4 and group message 1/2). This
# is similar to setting wpa_group_update_count=1 and
# wpa_pairwise_update_count=1, but with no impact to message 1/4 and with
# extended timeout on the response to avoid causing issues with stations that
# may use aggressive power saving have very long time in replying to the
# EAPOL-Key messages.
#
# This option can be used to work around key reinstallation attacks on the
# station (supplicant) side in cases those station devices cannot be updated
# for some reason. By removing the retransmissions the attacker cannot cause
# key reinstallation with a delayed frame transmission. This is related to the
# station side vulnerabilities CVE-2017-13077, CVE-2017-13078, CVE-2017-13079,
# CVE-2017-13080, and CVE-2017-13081.
#
# This workaround might cause interoperability issues and reduced robustness of
# key negotiation especially in environments with heavy traffic load due to the
# number of attempts to perform the key exchange is reduced significantly. As
# such, this workaround is disabled by default (unless overridden in build
# configuration). To enable this, set the parameter to 1.
#wpa_disable_eapol_key_retries=1

Note that this workaround can't prevent attacks against Tunneled Direct-Link Setup (TDLS). You may also want to add the option tdls_prohibit=1 in order to make such an attack more complicated:

Listing of Wi-Fi Protected Setup related options.

Support for WPS is provided by packages wpad and hostapd-utils. Default package wpad-mini is not enough.

WPS is possible only when encryption PSK/PSK2 is selected.

Minimal steps needed to get WPS running:

• Add option wps_pushbutton '1 ' to a config wifi-iface section that is configured for WPA2-PSK in /etc/config/wireless
• opkg update
• opkg remove wpad-mini
• opkg install wpad hostapd-utils
• reboot

After rebooting, instead of pushing the WPS button, you can manually initiate the WPS process (which is safer than using the button if it doubles as a reset button):

hostapd_cli wps_pbc

When using WPS-PIN:

• Add option wps_label '1 ' to a config wifi-iface section that is configured for WPA2-PSK in /etc/config/wireless
• opkg update
• opkg remove wpad-mini
• opkg install wpad hostapd-utils
• reboot

After rebooting, the WPS PIN needs to be given to hostapd each time a station tries to connect. The PIN may not be used multiple times, as an active attacker can recover half of it during each try. The “any” keyword can be replaced by the specific stations EUUID, as printed in hostapd log.

hostapd_cli wps_pin any $PIN

Example:

# /etc/config/wireless
...
config wifi-iface
	option device 'radio0'
	option mode 'ap'
	option ssid 'My-WiFi-Home'
	option network 'lan'
	option encryption 'psk2'
	option key 'WiFipassword'
	option ieee80211w '0'
	option wps_pushbutton '1'

This function needs the full version of hostapd or wpad. See also Wifi Roaming.

This function needs the full version of hostapd or wpad. See also Wifi Roaming.

First note that 802.11r is not necessarily needed for roaming since most WiFi clients (e.g. phones, tablets, laptops) will roam regardless of access point features. The difference is that roaming without 802.11r will take longer. Without 802.11r roaming for PSK might take 150ms and with EAP 500ms+. With 802.11r roaming is reduced to 15-75ms, see the forum discussion. So you will likely only see a difference if you are roaming whilst time-sensitive network traffic is being exchanged (e.g. VoIP, video conference, online game, etc.).

To check if 802.11r is working properly, set log_level to 1 (cf. Common Options) and look for message “FT authentication already completed - do not start 4-way handshake” in your system log after roaming.

Name	Type	Required	Default	Description
ieee80211r	boolean	no	0	Enables fast BSS transition (802.11r) support.
nasid	string	no	(BSSID without colon)	PMK-R0 Key Holder identifier (dot11FTR0KeyHolderID). A 1 to 48 octet identifier.
mobility_domain	string	no	(first 4 bytes of md5sum of the SSID)	Mobility Domain identifier (dot11FTMobilityDomainID, MDID). MDID is used to indicate a group of APs (within an ESS, i.e., sharing the same SSID) between which a STA can use Fast BSS Transition. 2-octet identifier as a hex string.
r0_key_lifetime	integer	no	10000	Default lifetime of the PMK-RO in minutes [1-65535].
r1_key_holder	string	no	(BSSID) (hostapd default)	PMK-R1 Key Holder identifier (dot11FTR1KeyHolderID). A 6-octet identifier as a hex string.
reassociation_deadline	integer	no	1000	Reassociation deadline in time units (TUs / 1.024 ms, 1000-65535). Warning: Some devices do not function properly with the default value of 1000. Using 20000 which is the default used on Cisco gear appears to resolve these issues.
r0kh	string	no	ff:ff:ff:ff:ff:ff,*,$key	List of R0KHs in the same Mobility Domain. Valid format: <MAC address>,<NAS Identifier>,<256-bit key as hex string> This list is used to map R0KH-ID (NAS Identifier) to a destination MAC address when requesting PMK-R1 key from the R0KH that the STA used during the Initial Mobility Domain Association. Key is generated with thep of auth_secret, so this should be the same for all APs.
r1kh	string	no	00:00:00:00:00:00,00:00:00:00:00:00,$key	List of R1KHs in the same Mobility Domain. Valid format: <MAC address>,<R1KH-ID>,<256-bit key as hex string> This list is used to map R1KH-ID to a destination MAC address when sending PMK-R1 key from the R0KH. This is also the list of authorized R1KHs in the MD that can request PMK-R1 keys.
pmk_r1_push	boolean	no	0	Whether PMK-R1 push is enabled at R0KH. Warning: If WPA3 (SAE) is enabled, setting this will break fast BSS transition (802.11r).
ft_over_ds	boolean	no	1	Whether to enable FT-over-DS. Warning: the default value of 1 for “FT over the DS” is known to cause issues especially with Apple devices. Setting this to 0 which instead uses “FT over the Air” is known to fix these issues.
ft_psk_generate_local	boolean	no	1	Whether to generate FT response locally for PSK networks. This avoids use of PMK-R1 push/pull from other APs with FT-PSK networks as the required information (PSK and other session data) is already locally available. Warning: For WPA3-only (SAE), setting this will break fast BSS transition (802.11r). For WPA2/3 mixed mode, you also need to disable this. Note that Fast Transition should continue working as r0kh and r1kh are automatically generated by default or you may elect to set r0kh & r1kh manually.

The wifi-station section allows matching a client (station) based on it's PSK or MAC Address and tagging it with a VLAN ID. It can be used to replicate the behaviour of wpa_psk_file in native UCI.

WPA3 SAE is not supported yet.

Example:

config	wifi-station
	option	iface		'iface_radio0'
	option	vid		'10'
	option	mac		'12:34:56:78:90:00'
	option	key		'hunter12'

The wifi-vlan section allows you to map between VLAN tagging on hostapd interfaces and their corresponding networks.

If the underlying interface is a DSA interface (Hardware Switch) make sure to configure the VLANs appropiately to guarantee the packets flow further.

Example:

config	wifi-vlan
	option	iface		'iface_radio0'
	option	network		'dmz'
	option	vid		'10'
	option	name		'10'

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.

To rebuild the configuration file, e.g. after installing a new wireless driver, remove the existing wireless configuration (if any) and use the wifi config command:

rm -f /etc/config/wireless
wifi config

The Wi-Fi channel width is the range of frequencies i.e. how broad the signal is for transferring data. Generally speaking, the bigger the channel width, the more data can be transmitted over the signal. But as with everything there are drawbacks. With larger channel widths, interference with others Wi-Fi networks or Bluetooth becomes a much larger issue, and making solid connections becomes much harder as well. Think of it like a highway. The wider the road, the more traffic (data) can pass through. On the other hand, the more cars (routers) you have on the road, the more congested the traffic becomes.

Wi-Fi standard allows 10, 20, 22, 40, 80 and 160 MHz but 10MHz is not used anymore, the 80 and 160 can be used only with 5 GHz frequency, and certain devices not being able to connect to APs with channel widths more than 40Mhz.

By default, the 2.4 GHz frequency uses a 20 MHz channel width. A 20MHz channel width is wide enough to span one channel. A 40 MHz channel width bonds two neighbouring 20 MHz channels together, forming a 40 MHz channel width; therefore, it allows for greater speed and faster transfer rates. One “control” channel functions as the main channel, and the other “extension” as the auxiliary channel. The main channel sends Beacon packets and data packets, and the auxiliary channel sends other packets. The extension channel can either be “above” or “below” the control channel, as long as it doesn't go outside the band. For example, if your control channel is 1, your extension channel has to “above”, because anything below channel 1 would be below the lowest frequency allowed in the 2.4GHz ISM band. The extension channel has to be contiguous with the edge of the control channel, without overlapping.

HT40+ means that centre frequency of the main 20 MHz channel is higher than that of the auxiliary channel, and HT40- otherwise. For example, if the centre frequency 149 and the centre frequency 153 reside on two 20 MHz channels, 149plus indicates that the two 20 MHz channels are bundled to form a 40 MHz channel.

When the HT40 mode is used in the 2.4 GHz frequency band, there is only one non-overlapping channel. Therefore, you are not advised to use the HT40 mode in the 2.4 GHz frequency band.

• HT20 High Throughput 20MHz, 802.11n
• HT40 High Throughput 40MHz, 802.11n
• HT40- High Throughput 40MHz, 802.11n, control channel is below extension channel.
• HT40+ High Throughput 40MHz, 802.11n, control channel is above extension channel.
• VHT20 Very High Throughput 20MHz, Supported by 802.11ac
• VHT40 Very High Throughput 40MHz, Supported by 802.11ac
• VHT80 Very High Throughput 80MHz, Supported by 802.11ac
• VHT160 Very High Throughput 160MHz, Supported by 802.11ac
• NOHT disables 11n

The default max channel width VT20 i.e. 20MHz supports a max speed of 150Mbps. Increasing this to 40MHz will increase the maximum theoretical speed to 300Mbps. The catch is that in areas with a lot of Wi-Fi traffic (and Bluetooth etc. which share the same radio frequencies), 40MHz may decrease your overall speed. Devices should detect interference when using 40MHz, and drop back to 20MHz. Edit htmode options in the file /etc/config/wireless and restart the Wi-Fi AP to test various channel widths. Note that option htmode should be set to either HT40+ (for channels 1-7) or HT40- (for channels 5-11) or simply HT40.

When using the mac80211 device, you can choose to enable/disable a number of high-throughput capabilities by setting any of the following options in the wifi-device section. Most capabilities are detected and enabled by default (in Barrier Breaker or later).

The following capabilities relate to 802.11n operation, and are enabled when the htmode option is set to any of HT20 HT40 HT40- HT40+ VHT20 VHT40 VHT80 or VHT160. Capabilities supported by a device can be queried with the iw list command, and are listed in the “Capabilities” section, refer to https://w1.fi/cgit/hostap/tree/hostapd/hostapd.conf for a description of the options (search for ht_capab on that web page).

Name	Type	Default	Capability	Description
ldpc	boolean	1	LDPC	LDPC (Low-Density Parity-Check code) capability
greenfield	boolean	0	GF	Receive Greenfield - treats pre-80211n traffic as noise. Warning: this can cause significant packet collisions and reduction in performance if older pre-n (a/b/g) traffic is present in the local area (including other networks which you don't control); it is disabled by default for a reason.
short_gi_20	boolean	1	SHORT-GI-20	Short GI (guard interval) for 20 MHz
short_gi_40	boolean	1	SHORT-GI-40	Short GI for 40 MHz
tx_stbc	integer	1	TX-STBC	Transmit STBC (Space-Time Block Coding)
rx_stbc	integer	3	RX-STBC1 RX-STBC12 RX-STBC123	Receive STBC: 1 - one spatial stream, 2 - one or two spatial streams, 3 - one, two, or three spatial streams, 0 - disables capability
max_amsdu	boolean	1	MAX-AMSDU-7935	Maximum A-MSDU length of 7935 octets (3839 octets if option set to 0)
dsss_cck_40	boolean	1	DSSS_CCK-40	DSSS/CCK Mode in 40 MHz allowed in Beacon, Measurement Pilot and Probe Response frames

The following capabilities relate to 802.11ac operation, and are enabled when the htmode option is set to any of VHT20, VHT40, VHT80, or VHT160. Capabilities supported by the device can be queried with the iw list command and are listed in the “VHT Capabilities” section.

Name	Type	Default	Capability	Description
rxldpc	boolean	1	RXLDPC	Supports receiving LDPC coded pkts
short_gi_80	boolean	1	SHORT-GI-80	Supports reception of packets transmitted with TXVECTOR params format equal to VHT and CBW = 80Mhz
short_gi_160	boolean	1	SHORT-GI-160	Supports reception of packets transmitted with TXVECTOR params format equal to VHT and CBW = 160Mhz
tx_stbc_2by1	boolean	1	TX-STBC-2BY1	Supports transmission of at least 2×1 STBC currently ignored in trunk
su_beamformer	boolean	1	SU-BEAMFORMER	Single user beamformer
su_beamformee	boolean	1	SU-BEAMFORMEE	Single user beamformee
mu_beamformer	boolean	1	MU-BEAMFORMER	Supports operation as an MU beamformer
mu_beamformee	boolean	1	MU-BEAMFORMEE	Supports operation as an MU beamformee
vht_txop_ps	boolean	1	VHT-TXOP-PS	0 = VHT AP doesn't support VHT TXOP PS (Power Save) mode (OR) VHT STA not in VHT TXOP PS mode, 1 = VHT AP supports VHT TXOP PS mode (OR) VHT STA is in VHT TXOP power save mode
htc_vht	boolean	1	HTC-VHT	STA supports receiving a VHT variant HT Control field.
rx_antenna_pattern	boolean	1	RX-ANTENNA-PATTERN	Rx antenna pattern does not change during the lifetime of an association
tx_antenna_pattern	boolean	1	TX-ANTENNA-PATTERN	Tx antenna pattern does not change during the lifetime of an association
vht_max_a_mpdu_len_exp	integer	7	MAX-A-MPDU-LEN-EXP<0-7>	Indicates the maximum length of A-MPDU pre-EOF padding that the STA can recv
vht_max_mpdu	integer	11454	MAX-MPDU-7991 MAX-MPDU-11454	Maximum MPDU length
rx_stbc	integer	4	0 - not supported, 1 - RX-STBC-1, 2 - RX-STBC-12, 3 - RX-STBC-123, 4 - RX-STBC-1234	Supports reception of PPDUs using STBC: 1 - one spatial stream, 2 - one or two spatial streams, etc. currently used incorrectly in trunk
vht_link_adapt	integer	3	VHT-LINK-ADAPT<0-3>	TA supports link adaptation using VHT variant HT Control field
vht160	integer	2	VHT160 VHT160-80PLUS80	Supported channel widths: 0 - 160MHz and 80+80 MHz not supported, 1 - 160 MHz supported, 2 - 160MHz and 80+80 MHz supported

In many countries, operating Wi-Fi devices on some or all channels in the 5GHz band requires radar detection and DFS (explanation). If you define a channel in your wireless config that requires DFS according to your country regulations, the 5GHz radio device won’t start up unless the firmware image is able to provide DFS support (i.e. it is both included and enabled). More technical details of the Linux implementation can be found here. DFS works as follows in Linux: The driver detects radar pulses and reports this to nl80211 where the information is processed. If a series of pulses matches one of the defined radar patterns, this will be reported to the user space application (e.g. hostapd) which in turn reacts by switching to another channel.

The following configuration specifies channel 104 which needs DFS support as implicitly stated with country code DE:

config	wifi-device		'radio0'
	option	type		'mac80211'
	option	channel		'104'
	option	hwmode		'11a'
	option	path		'pci0000:00/0000:00:00.0'
	option	htmode		'HT20'
	option	country		'DE'
 
config	wifi-iface
	option	device		'radio0'
	option	network		'lan'
	option	mode		'ap'
	option	ssid		'OpenWrt'
	option	encryption	'none'

You can check the country (regulatory domain) your Wi-Fi card thinks it must conform to with

iw reg get

If in doubt, double check your hostapd-phy.conf to make sure it contains the following values, and that your country code is set:

country_code=DE
ieee80211n=1
ieee80211d=1
ieee80211h=1
hw_mode=a

If radar detection is working, DFS channels will show up like this (here for Belgium, iw phy1 info output trimmed):

Frequencies:
* 5220 MHz [44] (17.0 dBm)
* 5240 MHz [48] (17.0 dBm)
* 5260 MHz [52] (20.0 dBm) (radar detection)
DFS state: usable (for 2155257 sec)
DFS CAC time: 60000 ms
* 5280 MHz [56] (20.0 dBm) (radar detection)
DFS state: usable (for 2155257 sec)
DFS CAC time: 60000 ms

When DFS is on, there will be a delay before the interface is enabled (e.g. after reboot). During this time period (often 60 seconds, and determined by local reglations) luci will report the interface is disabled. This time period is used to detect the presence of other signals on the channel (Channel Availability Check Time). This process can be monitored with:

logread -f

If you select a channel that requires DFS in your country and enable HT40, this may result in the DFS start_dfs_cac() failed error (visible with logread):

Configuration file: /var/run/hostapd-phy1.conf
wlan1: interface state UNINITIALIZED->COUNTRY_UPDATE
wlan1: interface state COUNTRY_UPDATE->HT_SCAN
wlan1: interface state HT_SCAN->DFS
wlan1: DFS-CAC-START freq=5680 chan=136 sec_chan=-1, width=0, seg0=0, seg1=0, cac_time=60s
DFS start_dfs_cac() failed, -1
Interface initialization failed
wlan1: interface state DFS->DISABLED
wlan1: AP-DISABLED
hostapd_free_hapd_data: Interface wlan1 wasn't started

Changing your configuration to HT20 should resolve this.