Provided by: iwd_3.9-2ubuntu1_amd64 
NAME
iwd.config - Configuration file for wireless daemon
SYNOPSIS
Configuration file main.conf
DESCRIPTION
The main.conf configuration file configures the system-wide settings for iwd. This file lives in the
configuration directory specified by the environment variable $CONFIGURATION_DIRECTORY, which is normally
provided by systemd. In the absence of such an environment variable it defaults to /etc/iwd. If no
main.conf is present, then default values are chosen. The presence of main.conf is not required.
FILE FORMAT
See iwd.network for details on the file format.
SETTINGS
The settings are split into several categories. Each category has a group associated with it and
described in separate tables below.
General Settings
The group [General] contains general settings.
┌───────────────────────────────────────┬───────────────────────────────────────┐
│ EnableNetworkConfiguration │ Values: true, false │
│ │ │
│ │ Enable network configuration. │
│ │ │
│ │ Setting this option to true enables │
│ │ iwd to configure the network │
│ │ interfaces with the IP addresses. │
│ │ There are two types IP addressing │
│ │ supported by iwd: static and dynamic. │
│ │ The static IP addresses are │
│ │ configured through the network │
│ │ configuration files. If no static IP │
│ │ configuration has been provided for a │
│ │ network, iwd will attempt to obtain │
│ │ the dynamic addresses from the │
│ │ network through the built-in DHCP │
│ │ client. │
│ │ │
│ │ This also enables network │
│ │ configuration and the DHCP server │
│ │ when in AP mode and the AP profile │
│ │ being activated does not override it. │
│ │ │
│ │ The network configuration feature is │
│ │ disabled by default. See [Network] │
│ │ settings for additional settings │
│ │ related to network configuration. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ UseDefaultInterface (deprecated) │ Values: true, false │
│ │ │
│ │ Do not allow iwd to destroy / │
│ │ recreate wireless interfaces at │
│ │ startup, including default │
│ │ interfaces. Enable this behavior if │
│ │ your wireless card driver is buggy or │
│ │ does not allow such an operation, or │
│ │ if you do not want iwd to manage │
│ │ netdevs for another reason. For most │
│ │ users with an upstream driver it │
│ │ should be safe to omit/disable this │
│ │ setting. │
│ │ │
│ │ This setting is deprecated, please │
│ │ use [DriverQuirks].DefaultInterface │
│ │ instead. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ AddressRandomization │ Values: disabled, once, network │
│ │ │
│ │ If AddressRandomization is set to │
│ │ disabled, the default kernel behavior │
│ │ is used. This means the kernel will │
│ │ assign a mac address from the │
│ │ permanent mac address range provided │
│ │ by the hardware / driver. Thus it is │
│ │ possible for networks to track the │
│ │ user by the mac address which is │
│ │ permanent. │
│ │ │
│ │ If AddressRandomization is set to │
│ │ once, MAC address is randomized a │
│ │ single time when iwd starts or when │
│ │ the hardware is detected for the │
│ │ first time (due to hotplug, etc.) │
│ │ │
│ │ If AddressRandomization is set to │
│ │ network, the MAC address is │
│ │ randomized on each connection to a │
│ │ network. The MAC is generated based │
│ │ on the SSID and permanent address of │
│ │ the adapter. This allows the same MAC │
│ │ to be generated each time connecting │
│ │ to a given SSID while still hiding │
│ │ the permanent address. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ AddressRandomizationRange │ Values: full, nic │
│ │ │
│ │ One can control which part of the │
│ │ address is randomized using this │
│ │ setting. │
│ │ │
│ │ When using AddressRandomizationRange │
│ │ set to nic, only the NIC specific │
│ │ octets (last 3 octets) are │
│ │ randomized. Note that the │
│ │ randomization range is limited to │
│ │ 00:00:01 to 00:00:FE. The permanent │
│ │ mac address of the card is used for │
│ │ the initial 3 octets. │
│ │ │
│ │ When using AddressRandomizationRange │
│ │ set to full, all 6 octets of the │
│ │ address are randomized. The │
│ │ locally-administered bit will be set. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ RoamThreshold │ Value: rssi dBm value, from -100 to │
│ │ 1, default: -70 │
│ │ │
│ │ This value can be used to control how │
│ │ aggressively iwd roams when connected │
│ │ to a 2.4GHz access point. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ RoamThreshold5G │ Value: rssi dBm value, from -100 to │
│ │ 1, default: -76 │
│ │ │
│ │ This value can be used to control how │
│ │ aggressively iwd roams when connected │
│ │ to a 5GHz access point. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ CriticalRoamThreshold │ Value: rssi dBm value, from -100 to │
│ │ -1, default: -80 │
│ │ │
│ │ The threshold (for 2.4GHz) at which │
│ │ IWD will roam regardless of the │
│ │ affinity set to the current BSS. If │
│ │ the connected BSS has affinity (set │
│ │ in Station's Affinities list) the │
│ │ roam threshold will be lowed to this │
│ │ value and IWD will not attempt to │
│ │ roam (or roam scan) until either the │
│ │ affinity is cleared, or the signal │
│ │ drops below this threshold. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ CriticalRoamThreshold5G │ Value: rssi dBm value, from -100 to │
│ │ -1, default: -82 │
│ │ │
│ │ This has the same effect as │
│ │ CriticalRoamThreshold, but for the │
│ │ 5GHz band. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ RoamRetryInterval │ Value: unsigned int value in seconds │
│ │ (default: 60) │
│ │ │
│ │ Specifies how long iwd will wait │
│ │ before attempting to roam again if │
│ │ the last roam attempt failed, or if │
│ │ the signal of the newly connected BSS │
│ │ is still considered weak. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ ManagementFrameProtection │ Values: 0, 1 or 2 │
│ │ │
│ │ When ManagementFrameProtection is 0, │
│ │ MFP is completely turned off, even if │
│ │ the hardware is capable. This │
│ │ setting is not recommended. │
│ │ │
│ │ When ManagementFrameProtection is 1, │
│ │ MFP is enabled if the local hardware │
│ │ and remote AP both support it. │
│ │ │
│ │ When ManagementFrameProtection is 2, │
│ │ MFP is always required. This can │
│ │ prevent successful connection │
│ │ establishment on some hardware or to │
│ │ some networks. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ ControlPortOverNL80211 │ Values: false, true │
│ │ │
│ │ Enable/Disable sending EAPoL packets │
│ │ over NL80211. Enabled by default if │
│ │ kernel support is available. Doing │
│ │ so sends all EAPoL traffic over │
│ │ directly to the supplicant process │
│ │ (iwd) instead of putting these on the │
│ │ Ethernet device. Since only the │
│ │ supplicant can usually make sense / │
│ │ decrypt these packets, enabling this │
│ │ option can save some CPU cycles on │
│ │ your system and avoids certain │
│ │ long-standing race conditions. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ DisableANQP │ Values: false, true │
│ │ │
│ │ Enable/disable ANQP queries. The way │
│ │ IWD does ANQP queries is dependent on │
│ │ a recent kernel patch (available in │
│ │ Kernel 5.3). If your kernel does not │
│ │ have this functionality this should │
│ │ be disabled (default). Some drivers │
│ │ also do a terrible job of sending │
│ │ public action frames (freezing or │
│ │ crashes) which is another reason why │
│ │ this has been turned off by default. │
│ │ If you want to easily utilize Hotspot │
│ │ 2.0 networks, then setting │
│ │ DisableANQP to false is recommended. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ DisableOCV │ Value: false, true │
│ │ │
│ │ Disable Operating Channel Validation. │
│ │ Support for this is not advertised by │
│ │ the kernel so if kernels/drivers │
│ │ exist which don't support OCV it can │
│ │ be disabled here. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ SystemdEncrypt │ Value: Systemd key ID │
│ │ │
│ Warning: This is a highly │ Enables network profile encryption │
│ experimental feature │ using a systemd provided secret key. │
│ │ Once enabled all PSK/8021x network │
│ │ profiles will be encrypted │
│ │ automatically. Once the profile is │
│ │ encrypted there is no way of going │
│ │ back using IWD alone. A tool, │
│ │ iwd-decrypt-profile, is provided │
│ │ assuming the secret is known which │
│ │ will decrypt a profile. This │
│ │ decrypted profile could manually be │
│ │ set to /var/lib/iwd to 'undo' any │
│ │ profile encryption, but its going to │
│ │ be a manual process. │
│ │ │
│ │ Setting up systemd to provide the │
│ │ secret is left up to the user as IWD │
│ │ has no way of performing this │
│ │ automatically. The systemd options │
│ │ required are LoadCredentialEncrypted │
│ │ or SetCredentialEncrypted, and the │
│ │ secret identifier should be named │
│ │ whatever SystemdEncrypt is set to. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ Country │ Value: Country Code (ISO Alpha-2) │
│ │ │
│ │ Requests the country be set for the │
│ │ system. Note that setting this is │
│ │ simply a request to set the country, │
│ │ and does not guarantee the country │
│ │ will be set. For a self-managed wiphy │
│ │ it is never possible to set the │
│ │ country from userspace. For other │
│ │ devices any regulatory domain request │
│ │ is just a 'hint' and ultimately left │
│ │ up to the kernel to set the country. │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ DisablePMKSA │ Value: false, true │
│ │ │
│ │ Disable PMKSA support in IWD │
└───────────────────────────────────────┴───────────────────────────────────────┘
Network
The group [Network] contains network configuration related settings.
┌──────────────────────┬───────────────────────────────────────┐
│ EnableIPv6 │ Values: true, false │
│ │ │
│ │ Sets the global default that tells │
│ │ iwd whether it should configure IPv6 │
│ │ addresses and routes (either provided │
│ │ via static settings, Router │
│ │ Advertisements or DHCPv6 protocol). │
│ │ This setting is enabled by default. │
│ │ This setting can also be overridden │
│ │ on a per-network basis. │
├──────────────────────┼───────────────────────────────────────┤
│ NameResolvingService │ Values: resolvconf, systemd, none │
│ │ │
│ │ Configures a DNS resolution method │
│ │ used by the system. │
│ │ │
│ │ This configuration option must be │
│ │ used in conjunction with │
│ │ EnableNetworkConfiguration and │
│ │ provides the choice of system │
│ │ resolver integration. │
│ │ │
│ │ If not specified, systemd is used as │
│ │ default. │
│ │ │
│ │ If none is specified, then DNS and │
│ │ domain name information is ignored. │
├──────────────────────┼───────────────────────────────────────┤
│ RoutePriorityOffset │ Values: uint32 value (default: 300) │
│ │ │
│ │ Configures a route priority offset │
│ │ used by the system to prioritize the │
│ │ default routes. The route with lower │
│ │ priority offset is preferred. │
│ │ │
│ │ If not specified, 300 is used as │
│ │ default. │
└──────────────────────┴───────────────────────────────────────┘
Blacklist
The group [Blacklist] contains settings related to blacklisting of BSSes. If iwd determines that a
connection to a BSS fails for a reason that indicates the BSS is currently misbehaving or misconfigured
(e.g. timeouts, unexpected status/reason codes, etc), then iwd will blacklist this BSS and avoid
connecting to it for a period of time. These options let the user control how long a misbehaved BSS
spends on the blacklist.
┌───────────────────────────────┬───────────────────────────────────────────┐
│ InitialTimeout │ Values: uint64 value in seconds │
│ │ (default: 60) │
│ │ │
│ │ The initial time that a BSS spends on │
│ │ the blacklist. Setting this to zero │
│ │ will disable blacklisting │
│ │ functionality in IWD. │
├───────────────────────────────┼───────────────────────────────────────────┤
│ InitialRoamRequestedTimeout │ Values: uint64 value in seconds │
│ (deprecated) │ (default: 30) │
│ │ │
│ │ This setting is deprecated, please │
│ │ use │
│ │ [Blacklist].InitialAccessPointBusyTimeout │
│ │ instead. │
├───────────────────────────────┼───────────────────────────────────────────┤
│ InitialAccessPointBusyTimeout │ Values: uint64 value in seconds (default: │
│ │ 30) │
│ │ │
│ │ The initial time that a BSS will be │
│ │ blacklisted after indicating it cannot │
│ │ handle more connections. This is │
│ │ triggered by either a BSS transition │
│ │ management request (telling IWD to roam │
│ │ elsewhere) or by a denied authentication │
│ │ or association with the NO_MORE_STAS │
│ │ status code. │
│ │ │
│ │ Once a BSS is blacklisted in this manor │
│ │ IWD will attempt to avoid it for the │
│ │ configured amount of time. │
├───────────────────────────────┼───────────────────────────────────────────┤
│ Multiplier │ Values: unsigned int value greater than │
│ │ zero, in seconds (default: 30) │
│ │ │
│ │ If the BSS was blacklisted previously and │
│ │ another connection attempt has failed │
│ │ after the initial timeout has expired, │
│ │ then the BSS blacklist time will be │
│ │ extended by a multiple of Multiplier for │
│ │ each unsuccessful attempt up to │
│ │ MaxiumTimeout time in seconds. │
├───────────────────────────────┼───────────────────────────────────────────┤
│ MaximumTimeout │ Values: uint64 value in seconds (default: │
│ │ 86400) │
│ │ │
│ │ Maximum time that a BSS is blacklisted. │
└───────────────────────────────┴───────────────────────────────────────────┘
Rank
The group [Rank] contains settings related to ranking of networks for autoconnect purposes.
┌───────────────────────────┬───────────────────────────────────────┐
│ BandModifier2_4GHz │ Values: floating point value │
│ │ (default: 1.0) │
│ │ │
│ │ Increase or decrease the preference │
│ │ for 2.4GHz access points by │
│ │ increasing or decreasing the value of │
│ │ this modifier. │
│ │ │
│ │ A value of 0.0 will disable the │
│ │ 2.4GHz band and prevent scanning or │
│ │ connecting on those frequencies. │
├───────────────────────────┼───────────────────────────────────────┤
│ BandModifier5GHz │ Values: floating point value │
│ │ (default: 1.0) │
│ │ │
│ │ Increase or decrease the preference │
│ │ for 5GHz access points by increasing │
│ │ or decreasing the value of this │
│ │ modifier. 5GHz networks are already │
│ │ preferred due to their increase │
│ │ throughput / data rate. However, │
│ │ 5GHz networks are highly RSSI │
│ │ sensitive, so it is still possible │
│ │ for IWD to prefer 2.4GHz APs in │
│ │ certain circumstances. │
│ │ │
│ │ A value of 0.0 will disable the 5GHz │
│ │ band and prevent scanning or │
│ │ connecting on those frequencies. │
├───────────────────────────┼───────────────────────────────────────┤
│ BandModifier6GHz │ Values: floating point value │
│ │ (default: 1.0) │
│ │ │
│ │ Increase or decrease the preference │
│ │ for 6GHz access points by increasing │
│ │ or decreasing the value of this │
│ │ modifier. Since 6GHz networks are │
│ │ highly RSSI sensitive, this gives an │
│ │ option to prefer 6GHz APs over 5GHz │
│ │ APs. │
│ │ │
│ │ A value of 0.0 will disable the 6GHz │
│ │ band and prevent scanning or │
│ │ connecting on those frequencies. │
├───────────────────────────┼───────────────────────────────────────┤
│ HighUtilizationThreshold │ Values: unsigned integer value 0 - │
│ │ 255 (default: 0, disabled) │
│ │ │
│ │ Warning: This is an experimental │
│ │ feature │
│ │ │
│ │ The BSS utilization threshold at │
│ │ which a negative rank factor begins │
│ │ to be applied to the BSS. As the load │
│ │ increases for a BSS the ranking │
│ │ factor decays exponentially, meaning │
│ │ the ranking factor will decrease │
│ │ exponentially. Setting this can have │
│ │ very drastic effects on the BSS rank │
│ │ if its utilization is high, use with │
│ │ care. │
├───────────────────────────┼───────────────────────────────────────┤
│ HighStationCountThreshold │ Values: unsigned integer value 0 - │
│ │ 255 (default: 0, disabled) │
│ │ │
│ │ Warning: This is an experimental │
│ │ feature │
│ │ │
│ │ The BSS station count threshold at │
│ │ which a negative rank factor begins │
│ │ to be applied to the BSS. As the │
│ │ station count increases for a BSS the │
│ │ ranking factor decays exponentially, │
│ │ meaning the ranking factor will │
│ │ decrease exponentially. Setting this │
│ │ can have very drastic effects on the │
│ │ BSS rank if its station count is │
│ │ high, use with care. │
└───────────────────────────┴───────────────────────────────────────┘
Scan
The group [Scan] contains settings related to scanning functionality. No modification from defaults is
normally required.
┌─────────────────────────────┬───────────────────────────────────────┐
│ DisablePeriodicScan │ Values: true, false │
│ │ │
│ │ Disable periodic scan. Setting this │
│ │ option to 'true' will prevent iwd │
│ │ from issuing the periodic scans for │
│ │ the available networks while │
│ │ disconnected. The behavior of the │
│ │ user-initiated scans isn't affected. │
│ │ The periodic scan is enabled by │
│ │ default. │
├─────────────────────────────┼───────────────────────────────────────┤
│ InitialPeriodicScanInterval │ Values: unsigned int value in seconds │
│ │ (default: 10) │
│ │ │
│ │ The initial periodic scan interval │
│ │ upon disconnect. │
├─────────────────────────────┼───────────────────────────────────────┤
│ MaximumPeriodicScanInterval │ Values: unsigned int value in seconds │
│ │ (default: 300) │
│ │ │
│ │ The maximum periodic scan interval. │
├─────────────────────────────┼───────────────────────────────────────┤
│ DisableRoamingScan │ Values: true, false │
│ │ │
│ │ Disable roaming scan. Setting this │
│ │ option to 'true' will prevent iwd │
│ │ from trying to scan when roaming │
│ │ decisions are activated. This can │
│ │ prevent iwd from roaming properly, │
│ │ but can be useful for networks │
│ │ operating under extremely low rssi │
│ │ levels where roaming isn't possible. │
└─────────────────────────────┴───────────────────────────────────────┘
IPv4
The group [IPv4] contains settings related to IPv4 network configuration.
┌───────────────┬───────────────────────────────────────┐
│ APAddressPool │ Values: comma-separated list of │
│ │ prefix-notation IP strings │
│ │ │
│ │ Defines the space of IPs used for the │
│ │ Access Point-mode subnet addresses │
│ │ and the DHCP server. Defaults to │
│ │ 192.168.0.0/16. The prefix length │
│ │ decides the size of the pool from │
│ │ which an address is selected but the │
│ │ actual subnet size (netmask) is based │
│ │ on the AP profile being activated and │
│ │ defaults to 28 bits. The AP │
│ │ profile's [IPv4].Address setting │
│ │ overrides the global value set here. │
│ │ Setting a too small address space │
│ │ will limit the number of access │
│ │ points that can be running │
│ │ simultaneously on different │
│ │ interfaces. │
└───────────────┴───────────────────────────────────────┘
DriverQuirks
The group [DriverQuirks] contains special flags associated with drivers that are buggy or just don't
behave similar enough to the majority of other drivers.
┌────────────────────┬───────────────────────────────────────┐
│ DefaultInterface │ Values: comma-separated list of │
│ │ drivers or glob matches │
│ │ │
│ │ If a driver in use matches one in │
│ │ this list IWD will not attempt to │
│ │ remove and re-create the default │
│ │ interface. │
├────────────────────┼───────────────────────────────────────┤
│ ForcePae │ Values: comma-separated list of │
│ │ drivers or glob matches │
│ │ │
│ │ If a driver in use matches one in │
│ │ this list ControlPortOverNL80211 will │
│ │ not be used, and PAE will be used │
│ │ instead. Some drivers do not properly │
│ │ support ControlPortOverNL80211 even │
│ │ though they advertise support for it. │
├────────────────────┼───────────────────────────────────────┤
│ PowerSaveDisable │ Values: comma-separated list of │
│ │ drivers or glob matches │
│ │ │
│ │ If a driver in user matches one in │
│ │ this list power save will be │
│ │ disabled. │
├────────────────────┼───────────────────────────────────────┤
│ MulticastRxDisable │ Values: comma-separated list of │
│ │ drivers or glob matches │
│ │ │
│ │ If a driver in use matches one in │
│ │ this list, multicast RX will be │
│ │ disabled. │
├────────────────────┼───────────────────────────────────────┤
│ SaeDisable │ Values: comma-separated list of │
│ │ drivers or glob matches │
│ │ │
│ │ If a driver in use matches one in │
│ │ this list, SAE/WPA3 will be disabled │
│ │ for connections. This will prevent │
│ │ connections to WPA3-only networks, │
│ │ but will allow for connections to │
│ │ WPA3/WPA2 hybrid networks by │
│ │ utilizing WPA2. │
└────────────────────┴───────────────────────────────────────┘
SEE ALSO
iwd(8), iwd.network(5)
AUTHOR
Marcel Holtmann <marcel@holtmann.org>, Denis Kenzior <denkenz@gmail.com>, Andrew Zaborowski
<andrew.zaborowski@intel.com>, Tim Kourt <tim.a.kourt@linux.intel.com>, James Prestwood
<prestwoj@gmail.com>
COPYRIGHT
2013-2019 Intel Corporation
iwd 22 September 2019 IWD.CONFIG(5)