1IWD.CONFIG(5) Linux Connectivity IWD.CONFIG(5)
2
6 iwd.config - Configuration file for wireless daemon
7
9 Configuration file main.conf
10
12 The main.conf configuration file configures the system-wide settings
13 for iwd. This file lives in the configuration directory specified by
14 the environment variable $CONFIGURATION_DIRECTORY, which is normally
15 provided by systemd. In the absence of such an environment variable it
16 defaults to /etc/iwd. If no main.conf is present, then default values
17 are chosen. The presence of main.conf is not required.
18
20 See iwd.network for details on the file format.
21
23 The settings are split into several categories. Each category has a
24 group associated with it and described in separate tables below.
25 General Settings
27 The group [General] contains general settings.
28 ┌───────────────────────────┬────────────────────────────┐
68 │EnableNetworkConfiguration │ Values: true, false │
69 │ │ │
70 │ │ Enable network configura‐ │
71 │ │ tion. │
72 │ │ │
73 │ │ Setting this option to │
74 │ │ true enables iwd to con‐ │
75 │ │ figure the network inter‐ │
76 │ │ faces with the IP ad‐ │
77 │ │ dresses. There are two │
78 │ │ types IP addressing sup‐ │
79 │ │ ported by iwd: static and │
80 │ │ dynamic. The static IP │
81 │ │ addresses are configured │
82 │ │ through the network con‐ │
83 │ │ figuration files. If no │
84 │ │ static IP configuration │
85 │ │ has been provided for a │
86 │ │ network, iwd will attempt │
87 │ │ to obtain the dynamic ad‐ │
88 │ │ dresses from the network │
89 │ │ through the built-in DHCP │
90 │ │ client. │
91 │ │ │
92 │ │ This also enables network │
93 │ │ configuration and the DHCP │
94 │ │ server when in AP mode and │
95 │ │ the AP profile being acti‐ │
96 │ │ vated does not override │
97 │ │ it. │
98 │ │ │
99 │ │ The network configuration │
100 │ │ feature is disabled by de‐ │
101 │ │ fault. See [Network] set‐ │
102 │ │ tings for additional set‐ │
103 │ │ tings related to network │
104 │ │ configuration. │
105 ├───────────────────────────┼────────────────────────────┤
106 │UseDefaultInterface │ Values: true, false │
107 │ │ │
108 │ │ Do not allow iwd to de‐ │
109 │ │ stroy / recreate wireless │
110 │ │ interfaces at startup, in‐ │
111 │ │ cluding default inter‐ │
112 │ │ faces. Enable this behav‐ │
113 │ │ ior if your wireless card │
114 │ │ driver is buggy or does │
115 │ │ not allow such an opera‐ │
116 │ │ tion, or if you do not │
117 │ │ want iwd to manage netdevs │
118 │ │ for another reason. For │
119 │ │ most users with an up‐ │
120 │ │ stream driver it should be │
121 │ │ safe to omit/disable this │
122 │ │ setting. │
123 └───────────────────────────┴────────────────────────────┘
124 │AddressRandomization │ Values: disabled, once, │
134 │ │ network │
135 │ │ │
136 │ │ If AddressRandomization is │
137 │ │ set to disabled, the de‐ │
138 │ │ fault kernel behavior is │
139 │ │ used. This means the ker‐ │
140 │ │ nel will assign a mac ad‐ │
141 │ │ dress from the permanent │
142 │ │ mac address range provided │
143 │ │ by the hardware / driver. │
144 │ │ Thus it is possible for │
145 │ │ networks to track the user │
146 │ │ by the mac address which │
147 │ │ is permanent. │
148 │ │ │
149 │ │ If AddressRandomization is │
150 │ │ set to once, MAC address │
151 │ │ is randomized a single │
152 │ │ time when iwd starts or │
153 │ │ when the hardware is de‐ │
154 │ │ tected for the first time │
155 │ │ (due to hotplug, etc.) │
156 │ │ │
157 │ │ If AddressRandomization is │
158 │ │ set to network, the MAC │
159 │ │ address is randomized on │
160 │ │ each connection to a net‐ │
161 │ │ work. The MAC is generated │
162 │ │ based on the SSID and per‐ │
163 │ │ manent address of the │
164 │ │ adapter. This allows the │
165 │ │ same MAC to be generated │
166 │ │ each time connecting to a │
167 │ │ given SSID while still │
168 │ │ hiding the permanent ad‐ │
169 │ │ dress. │
170 ├───────────────────────────┼────────────────────────────┤
171 │AddressRandomizationRange │ Values: full, nic │
172 │ │ │
173 │ │ One can control which part │
174 │ │ of the address is random‐ │
175 │ │ ized using this setting. │
176 │ │ │
177 │ │ When using AddressRandom‐ │
178 │ │ izationRange set to nic, │
179 │ │ only the NIC specific │
180 │ │ octets (last 3 octets) are │
181 │ │ randomized. Note that the │
182 │ │ randomization range is │
183 │ │ limited to 00:00:01 to │
184 │ │ 00:00:FE. The permanent │
185 │ │ mac address of the card is │
186 │ │ used for the initial 3 │
187 │ │ octets. │
188 │ │ │
189 │ │ When using AddressRandom‐ │
190 │ │ izationRange set to full, │
191 │ │ all 6 octets of the ad‐ │
192 │ │ dress are randomized. The │
193 │ │ locally-administered bit │
194 │ │ will be set. │
195 └───────────────────────────┴────────────────────────────┘
196 │RoamThreshold │ Value: rssi dBm value, │
200 │ │ from -100 to 1, default: │
201 │ │ -70 │
202 │ │ │
203 │ │ This value can be used to │
204 │ │ control how aggressively │
205 │ │ iwd roams when connected │
206 │ │ to a 2.4Ghz access point. │
207 ├───────────────────────────┼────────────────────────────┤
208 │RoamThreshold5G │ Value: rssi dBm value, │
209 │ │ from -100 to 1, default: │
210 │ │ -76 │
211 │ │ │
212 │ │ This value can be used to │
213 │ │ control how aggressively │
214 │ │ iwd roams when connected │
215 │ │ to a 5GHz access point. │
216 ├───────────────────────────┼────────────────────────────┤
217 │RoamRetryInterval │ Value: unsigned int value │
218 │ │ in seconds (default: 60) │
219 │ │ │
220 │ │ Specifies how long iwd │
221 │ │ will wait before attempt‐ │
222 │ │ ing to roam again if the │
223 │ │ last roam attempt failed, │
224 │ │ or if the signal of the │
225 │ │ newly connected BSS is │
226 │ │ still considered weak. │
227 ├───────────────────────────┼────────────────────────────┤
228 │ManagementFrameProtection │ Values: 0, 1 or 2 │
229 │ │ │
230 │ │ When ManagementFramePro‐ │
231 │ │ tection is 0, MFP is com‐ │
232 │ │ pletely turned off, even │
233 │ │ if the hardware is capa‐ │
234 │ │ ble. This setting is not │
235 │ │ recommended. │
236 │ │ │
237 │ │ When ManagementFramePro‐ │
238 │ │ tection is 1, MFP is en‐ │
239 │ │ abled if the local hard‐ │
240 │ │ ware and remote AP both │
241 │ │ support it. │
242 │ │ │
243 │ │ When ManagementFramePro‐ │
244 │ │ tection is 2, MFP is al‐ │
245 │ │ ways required. This can │
246 │ │ prevent successful connec‐ │
247 │ │ tion establishment on some │
248 │ │ hardware or to some net‐ │
249 │ │ works. │
250 └───────────────────────────┴────────────────────────────┘
251 │ControlPortOverNL80211 │ Values: false, true │
266 │ │ │
267 │ │ Enable/Disable sending │
268 │ │ EAPoL packets over │
269 │ │ NL80211. Enabled by de‐ │
270 │ │ fault if kernel support is │
271 │ │ available. Doing so sends │
272 │ │ all EAPoL traffic over di‐ │
273 │ │ rectly to the supplicant │
274 │ │ process (iwd) instead of │
275 │ │ putting these on the Eth‐ │
276 │ │ ernet device. Since only │
277 │ │ the supplicant can usually │
278 │ │ make sense / decrypt these │
279 │ │ packets, enabling this op‐ │
280 │ │ tion can save some CPU cy‐ │
281 │ │ cles on your system and │
282 │ │ avoids certain long-stand‐ │
283 │ │ ing race conditions. │
284 ├───────────────────────────┼────────────────────────────┤
285 │DisableANQP │ Values: false, true │
286 │ │ │
287 │ │ Enable/disable ANQP │
288 │ │ queries. The way IWD does │
289 │ │ ANQP queries is dependent │
290 │ │ on a recent kernel patch │
291 │ │ (available in Kernel 5.3). │
292 │ │ If your kernel does not │
293 │ │ have this functionality │
294 │ │ this should be disabled │
295 │ │ (default). Some drivers │
296 │ │ also do a terrible job of │
297 │ │ sending public action │
298 │ │ frames (freezing or │
299 │ │ crashes) which is another │
300 │ │ reason why this has been │
301 │ │ turned off by default. If │
302 │ │ you want to easily utilize │
303 │ │ Hotspot 2.0 networks, then │
304 │ │ setting DisableANQP to │
305 │ │ false is recommended. │
306 ├───────────────────────────┼────────────────────────────┤
307 │DisableOCV │ Value: false, true │
308 │ │ │
309 │ │ Disable Operating Channel │
310 │ │ Validation. Support for │
311 │ │ this is not advertised by │
312 │ │ the kernel so if ker‐ │
313 │ │ nels/drivers exist which │
314 │ │ don't support OCV it can │
315 │ │ be disabled here. │
316 └───────────────────────────┴────────────────────────────┘
317 │SystemdEncrypt │ Value: Systemd key ID │
332 │ │ │
333 │Warning: This is a highly │ Enables network profile │
334 │experimental feature │ encryption using a systemd │
335 │ │ provided secret key. Once │
336 │ │ enabled all PSK/8021x net‐ │
337 │ │ work profiles will be en‐ │
338 │ │ crypted automatically. │
339 │ │ Once the profile is en‐ │
340 │ │ crypted there is no way of │
341 │ │ going back using IWD │
342 │ │ alone. A tool, iwd-de‐ │
343 │ │ crypt-profile, is provided │
344 │ │ assuming the secret is │
345 │ │ known which will decrypt a │
346 │ │ profile. This decrypted │
347 │ │ profile could manually be │
348 │ │ set to /var/lib/iwd to │
349 │ │ 'undo' any profile encryp‐ │
350 │ │ tion, but its going to be │
351 │ │ a manual process. │
352 │ │ │
353 │ │ Setting up systemd to pro‐ │
354 │ │ vide the secret is left up │
355 │ │ to the user as IWD has no │
356 │ │ way of performing this au‐ │
357 │ │ tomatically. The systemd │
358 │ │ options required are Load‐ │
359 │ │ CredentialEncrypted or │
360 │ │ SetCredentialEncrypted, │
361 │ │ and the secret identifier │
362 │ │ should be named whatever │
363 │ │ SystemdEncrypt is set to. │
364 ├───────────────────────────┼────────────────────────────┤
365 │Country │ Value: Country Code (ISO │
366 │ │ Alpha-2) │
367 │ │ │
368 │ │ Requests the country be │
369 │ │ set for the system. Note │
370 │ │ that setting this is sim‐ │
371 │ │ ply a request to set the │
372 │ │ country, and does not │
373 │ │ guarantee the country will │
374 │ │ be set. For a self-managed │
375 │ │ wiphy it is never possible │
376 │ │ to set the country from │
377 │ │ userspace. For other de‐ │
378 │ │ vices any regulatory do‐ │
379 │ │ main request is just a │
380 │ │ 'hint' and ultimately left │
381 │ │ up to the kernel to set │
382 │ │ the country. │
383 └───────────────────────────┴────────────────────────────┘
384 Network
386 The group [Network] contains network configuration related settings.
387 ┌─────────────────────┬────────────────────────────┐
398 │EnableIPv6 │ Values: true, false │
399 │ │ │
400 │ │ Sets the global default │
401 │ │ that tells iwd whether it │
402 │ │ should configure IPv6 ad‐ │
403 │ │ dresses and routes (either │
404 │ │ provided via static set‐ │
405 │ │ tings, Router Advertise‐ │
406 │ │ ments or DHCPv6 protocol). │
407 │ │ This setting is enabled by │
408 │ │ default. This setting can │
409 │ │ also be overridden on a │
410 │ │ per-network basis. │
411 ├─────────────────────┼────────────────────────────┤
412 │NameResolvingService │ Values: resolvconf, sys‐ │
413 │ │ temd, none │
414 │ │ │
415 │ │ Configures a DNS resolu‐ │
416 │ │ tion method used by the │
417 │ │ system. │
418 │ │ │
419 │ │ This configuration option │
420 │ │ must be used in conjunc‐ │
421 │ │ tion with EnableNetwork‐ │
422 │ │ Configuration and provides │
423 │ │ the choice of system re‐ │
424 │ │ solver integration. │
425 │ │ │
426 │ │ If not specified, systemd │
427 │ │ is used as default. │
428 │ │ │
429 │ │ If none is specified, then │
430 │ │ DNS and domain name infor‐ │
431 │ │ mation is ignored. │
432 ├─────────────────────┼────────────────────────────┤
433 │RoutePriorityOffset │ Values: uint32 value (de‐ │
434 │ │ fault: 300) │
435 │ │ │
436 │ │ Configures a route prior‐ │
437 │ │ ity offset used by the │
438 │ │ system to prioritize the │
439 │ │ default routes. The route │
440 │ │ with lower priority offset │
441 │ │ is preferred. │
442 │ │ │
443 │ │ If not specified, 300 is │
444 │ │ used as default. │
445 └─────────────────────┴────────────────────────────┘
446 Blacklist
448 The group [Blacklist] contains settings related to blacklisting of
449 BSSes. If iwd determines that a connection to a BSS fails for a reason
450 that indicates the BSS is currently misbehaving or misconfigured (e.g.
451 timeouts, unexpected status/reason codes, etc), then iwd will blacklist
452 this BSS and avoid connecting to it for a period of time. These op‐
453 tions let the user control how long a misbehaved BSS spends on the
454 blacklist.
455 ┌───────────────┬────────────────────────────┐
464 │InitialTimeout │ Values: uint64 value in │
465 │ │ seconds (default: 60) │
466 │ │ │
467 │ │ The initial time that a │
468 │ │ BSS spends on the black‐ │
469 │ │ list. │
470 ├───────────────┼────────────────────────────┤
471 │Multiplier │ Values: unsigned int value │
472 │ │ in seconds (default: 30) │
473 │ │ │
474 │ │ If the BSS was blacklisted │
475 │ │ previously and another │
476 │ │ connection attempt has │
477 │ │ failed after the initial │
478 │ │ timeout has expired, then │
479 │ │ the BSS blacklist time │
480 │ │ will be extended by a mul‐ │
481 │ │ tiple of Multiplier for │
482 │ │ each unsuccessful attempt │
483 │ │ up to MaxiumTimeout time │
484 │ │ in seconds. │
485 ├───────────────┼────────────────────────────┤
486 │MaximumTimeout │ Values: uint64 value in │
487 │ │ seconds (default: 86400) │
488 │ │ │
489 │ │ Maximum time that a BSS is │
490 │ │ blacklisted. │
491 └───────────────┴────────────────────────────┘
492 Rank
494 The group [Rank] contains settings related to ranking of networks for
495 autoconnect purposes.
496 ┌─────────────────┬────────────────────────────┐
498 │BandModifier5Ghz │ Values: floating point │
499 │ │ value (default: 1.0) │
500 │ │ │
501 │ │ Increase or decrease the │
502 │ │ preference for 5GHz access │
503 │ │ points by increasing or │
504 │ │ decreasing the value of │
505 │ │ this modifier. 5GHz net‐ │
506 │ │ works are already pre‐ │
507 │ │ ferred due to their in‐ │
508 │ │ crease throughput / data │
509 │ │ rate. However, 5GHz net‐ │
510 │ │ works are highly RSSI sen‐ │
511 │ │ sitive, so it is still │
512 │ │ possible for IWD to prefer │
513 │ │ 2.4Ghz APs in certain cir‐ │
514 │ │ cumstances. │
515 └─────────────────┴────────────────────────────┘
516 │BandModifier6Ghz │ Values: floating point │
530 │ │ value (default: 1.0) │
531 │ │ │
532 │ │ Increase or decrease the │
533 │ │ preference for 6GHz access │
534 │ │ points by increasing or │
535 │ │ decreasing the value of │
536 │ │ this modifier. Since 6GHz │
537 │ │ networks are highly RSSI │
538 │ │ sensitive, this gives an │
539 │ │ option to prefer 6GHz APs │
540 │ │ over 5GHz APs. │
541 └─────────────────┴────────────────────────────┘
542 Scan
544 The group [Scan] contains settings related to scanning functionality.
545 No modification from defaults is normally required.
546 ┌──────────────────────────┬────────────────────────────┐
548 │DisablePeriodicScan │ Values: true, false │
549 │ │ │
550 │ │ Disable periodic scan. │
551 │ │ Setting this option to │
552 │ │ 'true' will prevent iwd │
553 │ │ from issuing the periodic │
554 │ │ scans for the available │
555 │ │ networks while discon‐ │
556 │ │ nected. The behavior of │
557 │ │ the user-initiated scans │
558 │ │ isn't affected. The peri‐ │
559 │ │ odic scan is enabled by │
560 │ │ default. │
561 ├──────────────────────────┼────────────────────────────┤
562 │InitialPeriodicScanInter‐ │ Values: unsigned int value │
563 │val │ in seconds (default: 10) │
564 │ │ │
565 │ │ The initial periodic scan │
566 │ │ interval upon disconnect. │
567 ├──────────────────────────┼────────────────────────────┤
568 │MaximumPeriodicScanInter‐ │ Values: unsigned int value │
569 │val │ in seconds (default: 300) │
570 │ │ │
571 │ │ The maximum periodic scan │
572 │ │ interval. │
573 ├──────────────────────────┼────────────────────────────┤
574 │DisableRoamingScan │ Values: true, false │
575 │ │ │
576 │ │ Disable roaming scan. Set‐ │
577 │ │ ting this option to 'true' │
578 │ │ will prevent iwd from try‐ │
579 │ │ ing to scan when roaming │
580 │ │ decisions are activated. │
581 │ │ This can prevent iwd from │
582 │ │ roaming properly, but can │
583 │ │ be useful for networks op‐ │
584 │ │ erating under extremely │
585 │ │ low rssi levels where │
586 │ │ roaming isn't possible. │
587 └──────────────────────────┴────────────────────────────┘
588 IPv4
590 The group [IPv4] contains settings related to IPv4 network configura‐
591 tion.
592 ┌──────────────┬────────────────────────────┐
596 │APAddressPool │ Values: comma-separated │
597 │ │ list of prefix-notation IP │
598 │ │ strings │
599 │ │ │
600 │ │ Defines the space of IPs │
601 │ │ used for the Access │
602 │ │ Point-mode subnet ad‐ │
603 │ │ dresses and the DHCP │
604 │ │ server. Defaults to │
605 │ │ 192.168.0.0/16. The pre‐ │
606 │ │ fix length decides the │
607 │ │ size of the pool from │
608 │ │ which an address is se‐ │
609 │ │ lected but the actual sub‐ │
610 │ │ net size (netmask) is │
611 │ │ based on the AP profile │
612 │ │ being activated and de‐ │
613 │ │ faults to 28 bits. The AP │
614 │ │ profile's [IPv4].Address │
615 │ │ setting overrides the │
616 │ │ global value set here. │
617 │ │ Setting a too small ad‐ │
618 │ │ dress space will limit the │
619 │ │ number of access points │
620 │ │ that can be running simul‐ │
621 │ │ taneously on different in‐ │
622 │ │ terfaces. │
623 └──────────────┴────────────────────────────┘
624 DriverQuirks
626 The group [DriverQuirks] contains special flags associated with drivers
627 that are buggy or just don't behave similar enough to the majority of
628 other drivers.
629 ┌─────────────────┬────────────────────────────┐
631 │DefaultInterface │ Values: comma-separated │
632 │ │ list of drivers or glob │
633 │ │ matches │
634 │ │ │
635 │ │ If a driver in use matches │
636 │ │ one in this list IWD will │
637 │ │ not attempt to remove and │
638 │ │ re-create the default in‐ │
639 │ │ terface. │
640 ├─────────────────┼────────────────────────────┤
641 │ForcePae │ Values: comma-separated │
642 │ │ list of drivers or glob │
643 │ │ matches │
644 │ │ │
645 │ │ If a driver in use matches │
646 │ │ one in this list Control‐ │
647 │ │ PortOverNL80211 will not │
648 │ │ be used, and PAE will be │
649 │ │ used instead. Some drivers │
650 │ │ do not properly support │
651 │ │ ControlPortOverNL80211 │
652 │ │ even though they advertise │
653 │ │ support for it. │
654 └─────────────────┴────────────────────────────┘
655 │PowerSaveDisable │ Values: comma-separated │
662 │ │ list of drivers or glob │
663 │ │ matches │
664 │ │ │
665 │ │ If a driver in user │
666 │ │ matches one in this list │
667 │ │ power save will be dis‐ │
668 │ │ abled. │
669 └─────────────────┴────────────────────────────┘
670
672 iwd(8), iwd.network(5)
673
675 Marcel Holtmann <marcel@holtmann.org>, Denis Kenzior
676 <denkenz@gmail.com>, Andrew Zaborowski <andrew.zaborowski@intel.com>,
677 Tim Kourt <tim.a.kourt@linux.intel.com>, James Prestwood <prest‐
678 woj@gmail.com>
679
681 2013-2019 Intel Corporation
682iwd 22 September 2019 IWD.CONFIG(5)