iwd.config - Configuration file for wireless daemon

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>

2013-2019 Intel Corporation iwd 22 September 2019 IWD.CONFIG(5)

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.

See iwd.network for details on the file format.

iwd.config - Configuration file for wireless daemon

iwd(8), iwd.network(5)

The settings are split into several categories. Each category has a group associated with it and described in separate tables below. GeneralSettings 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:Thisisahighly │ Enables network profile encryption │ │ experimentalfeature │ 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. │ ├────────────────┼───────────────────────────────────────┤ │ Multiplier │ Values: unsigned int value 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:Thisisanexperimental │ │ │ 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:Thisisanexperimental │ │ │ 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. │ └────────────────────┴───────────────────────────────────────┘

Configuration file main.conf