iwd.config(5)

📦
version 3.12 · 9 versions
, in alpine 3.24, fedora 44, nixos 26.05, ubuntu resolute, ubuntu stonking

💖 iwd.config — the manual page for iwd.config(5) bestie ✨

okay so like, welcome to iwd.config(5) from the Linux Connectivity girlies 💅 this is the whole scoop on the config file for the wireless daemon, and I'm gonna walk you through it like we're texting at 2am 🫶

✨ NAME ✨

iwd.config — the configuration file for the wireless daemon, aka the glow-up instructions for your Wi-Fi situation 💖

🌸 SYNOPSIS 🌸

Configuration file main.conf

literally one file, one vibe, no cap 🎀

🦋 DESCRIPTION 🦋

okay so the main.conf configuration file is the one that sets up all the system-wide settings for iwd — like, the main character of your wireless setup 👑

this file lives in the configuration directory that's specified by the environment variable $CONFIGURATION_DIRECTORY, which is normally handed to you by systemd. no thoughts, it just shows up 🌈

but bestie, if that environment variable isn't there? it defaults to /etc/iwd — that's the fallback, and it's serving as always 💅

and if there's no main.conf present at all, then default values get chosen instead. so the presence of main.conf is not required — it's optional, it's lowkey chill, it's giving "come as you are" 🧚✨

🎀 FILE FORMAT 🎀

for the deets on the file format, go check out iwd.network — that's where the format lore lives 📖💫

💜 SETTINGS 💜

the settings are split into several categories 👏 each category has a group associated with it, and each one gets described in its own separate tables below 📊✨ so like, stay tuned, there's more coming 🌸

✨ General Settings ✨

Okay so the [General] group is where the global-ish vibes live — the stuff that applies to iwd as a whole, not to one specific network. Let's get into it 💅

  • EnableNetworkConfiguration — Values: true, false. Turns on network configuration, bestie.

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 (so like, off unless you say otherwise, no cap). See [Network] settings for additional settings related to network configuration.

  • UseDefaultInterface — Values: true, false. Deprecated, babes — more on that in a sec 🙈

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. Like, it still works, but it's giving legacy energy — migrate when you can 💀
  • AddressRandomization — Values: disabled, once, network. This one's the MAC-address-privacy queen 👑

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. (Not slay of them, honestly 😭)

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. Iconic behavior, truly ✨

  • AddressRandomizationRange — Values: full, nic. Controls which part of the address gets the randomization treatment.

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. (Yes it's a separate dial from the 2.4GHz one, they're different girlies 💖)
  • CriticalRoamThreshold — Value: rssi dBm value, from -100 to -1, default: -80.

Like, picking right back up on the threshold saga 🔥 — so the threshold for 2.4GHz is the point at which IWD will roam no matter what affinity is set to the current BSS. And if the BSS you're connected to actually has affinity (the kind you set in Station's Affinities list), that roam threshold gets lowered down to this value, and IWD won't even attempt to roam (or do a roam scan) until either the affinity is cleared, or the signal drops below this threshold. Bestie, that's the whole bit 💅

  • CriticalRoamThreshold5G — Value: rssi dBm value, from -100 to -1, default: -82

This has the same effect as CriticalRoamThreshold, but for the 5GHz band. Same energy, different frequency 🦋

  • 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. Basically the "okay give it a minute and try again" timer ⏳

  • 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. Heads up: 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. Lowkey a glow-up for your CPU ✨

  • 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. Go off 👑

  • 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 experimental feature. No cap, be careful.

Enables network profile encryption using a systemd provided secret key. Once enabled, all PSK/8021x network profiles will be encrypted automatically. And 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 it's going to be a manual process, fr fr.

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. Matchy-matchy, you got this 🫶

  • 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…

…and the tail end of that last setting from before, finishing up the country talk 🎀 — for some devices this means iwd sets 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 — Values: false, true. This one just disables PMKSA support in IWD. That's it, that's the whole vibe 💅

🌸 Network 🌸

The group [Network] is where all your network configuration related settings live, bestie.

  • 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, and heads up — it 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 the lower priority offset is preferred.

If not specified, 300 is used as default.

💀 Blacklist 💀

The group [Blacklist] contains settings related to blacklisting of BSSes. So here's the tea: 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 you control how long a misbehaved BSS spends on the blacklist. It's giving timeout corner, fr fr ✨

  • 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 entirely 🫶
  • InitialRoamRequestedTimeout (deprecated) — Values: uint64 value in seconds (default: 30).
⚠️ This setting is deprecated, please use [Blacklist].InitialAccessPointBusyTimeout instead. Don't be that girl still using the deprecated one 😭
  • 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 manner, IWD will attempt to avoid it for the configured amount of time. Iconic avoidance behavior honestly 🌈

  • 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. It escalates. She escalates. 💅
  • MaximumTimeout — Values: uint64 value in seconds (default: 86400). Maximum time that a BSS is blacklisted. The ceiling. The limit. The final boss 🧚

👑 Rank

okay so the [Rank] group is where you go when you wanna have Opinions™ about which network iwd should autoconnect to 💅 it's literally the group that holds all the settings related to ranking of networks for autoconnect purposes. let's get into it 🎀

  • BandModifier2_4GHz — values: floating point value (default: 1.0). bump this up or down to increase or decrease the preference for 2.4GHz access points. it's giving "volume knob for a whole band" 🎚️ and yes, a value of 0.0 will disable the 2.4GHz band and prevent scanning or connecting on those frequencies — so like, actually gone, not just "less liked" 💀
  • BandModifier5GHz — values: floating point value (default: 1.0). same deal, but for 5GHz access points: increase or decrease the value of this modifier to increase or decrease the preference. heads up tho, 5GHz networks are already preferred due to their increase throughput / data rate 👑 but 5GHz networks are highly RSSI sensitive, so it's still possible for IWD to prefer 2.4GHz APs in certain circumstances 🙈 and again, 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). raise or lower this one to increase or decrease the preference for 6GHz access points ✨ since 6GHz networks are highly RSSI sensitive, this gives an option to prefer 6GHz APs over 5GHz APs — like, main character energy for the new band 🌈 and yep, a value of 0.0 will disable the 6GHz band and prevent scanning or connecting on those frequencies 🦋
⚠️ okay bestie, listen — 0.0 on any of these bands isn't a soft preference, it kills scanning and connecting on those frequencies. no cap, be sure before you commit 💀
  • 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, fr fr 🙏

  • 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 👥 same energy as the one above: 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 💜

lowkey the vibe check here: these are all knobs on the ranking math, not on whether a network is saved or trusted 💅 default 1.0 on the band modifiers means "no opinion added", and default 0 on the two thresholds means disabled — so if you never touch this group, nothing changes 🎀

✨ Scan ✨

Okay bestie, the [Scan] group contains settings related to scanning functionality. No modification from defaults is normally required — literally the default vibe is usually correct. 💅

  • DisablePeriodicScan — Values: true, false. This disables periodic scan. Setting this option to true will prevent iwd from issuing the periodic scans for the available networks while disconnected. Quick clarification: the behavior of 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. Cap it, periodt.
  • DisableRoamingScan — Values: true, false. Disables 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. So like, use with intention, bestie. 🫶

🌐 IPv4 🌐

The [IPv4] group contains settings related to IPv4 network configuration. Slay, networking. ✨

  • APAddressPool — Values: comma-separated list of prefix-notation IP strings. This 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. Also, setting a too-small address space will limit the number of access points that can be running simultaneously on different interfaces. So don't shrink it into oblivion. 😭

🧚 DriverQuirks 🧚

The [DriverQuirks] group contains special flags associated with drivers that are buggy or just don't behave similar enough to the majority of other drivers. Basically the “we love you but you're a little quirky” group. 💀

  • 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. Annoying, but handled.
  • PowerSaveDisable — Values: comma-separated list of drivers or glob matches. If a driver in use 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>

okay so the legal bit, bestie — but make it cute:

Copyright 2013-2019 Intel Corporation

like, that's the whole thing. the folks at Intel held the copyright on this from 2013 through 2019, and we're just out here respectfully citing it 🫶

✨ and that's a wrap on the whole page, fr fr ✨

this little masterpiece comes from the iwd corner of the world, dated 22 September 2019, and it lives in section 5 of the manual as iwd.config(5) — so if you ever need to cite your sources for the group chat, now you know 🌸

go forth and configure your wireless, you absolute icon 👑💅

📦 where this page comes from