1IWD.NETWORK(5) Linux Connectivity IWD.NETWORK(5)
2
6 iwd.network - Network configuration for wireless daemon
7
9 Network configuration files .open, .psk and .8021x
10
12 iwd stores information on known networks, and reads information on
13 pre-provisioned networks, from small text configuration files. Those
14 files live in the state directory specified by the environment variable
15 $STATE_DIRECTORY, which is normally provided by systemd. In the
16 absence of such an environment variable it defaults to $LIBDIR/iwd,
17 which normally is set to /var/lib/iwd. You can create, modify or
18 remove those files. iwd monitors the directory for changes and will
19 update its state accordingly. iwd will also modify these files in the
20 course of network connections or as a result of D-Bus API invocations.
21
23 The syntax is similar to that of GNOME keyfile syntax (which is based
24 on the format defined in the Desktop Entry Specification, see
25 http://freedesktop.org/Standards/desktop-entry-spec). The recognized
26 groups as well as keys and values in each group are documented here.
27 Defaults are written in bold.
28 For completeness we include the description of the file syntax here.
30 This is the syntax that the ell library's l_settings class implements.
31 The syntax is based on lines and lines are delimited by newline charac‐
32 ters.
33 Empty lines are ignored and whitespace at the beginning of a line is
35 ignored. Comment lines have # as their first non-whitespace character.
36 Key-value lines contain a setting key, an equal sign and the value of
38 the setting. Whitespace preceding the key, the equal sign or the
39 value, is ignored. The key must be a continuous string of alphanumeric
40 and underscore characters and minus signs only. The value starts at
41 the first non-whitespace character after the first equal sign on the
42 line and ends at the end of the line and must be correctly
43 UTF-8-encoded. A boolean value can be true or false but 0 or 1 are also
44 allowed. Integer values are written in base 10. String values,
45 including file paths and hexstrings, are written as is except for five
46 characters that may be backslash-escaped: space, \t, \r, \n and back‐
47 slash itself. The latter three must be escaped. A space character
48 must be escaped if it is the first character in the value string and is
49 written as \s.
50 Settings are interpreted depending on the group they are in. A group
52 starts with a group header line and contains all settings until the
53 next group's header line. A group header line contains a [ character
54 followed by the group name and a ] character. Whitespace is allowed
55 before the [ and after the ]. A group name consists of printable char‐
56 acters other than [ and ].
57
59 File names are based on the network's SSID and security type: Open,
60 PSK-protected or 802.1x. The name consist of the encoding of the SSID
61 followed by .open, .psk or .8021x. The SSID appears verbatim in the
62 name if it contains only alphanumeric characters, spaces, underscores
63 or minus signs. Otherwise it is encoded as an equal sign followed by
64 the lower-case hex encoding of the name.
65
67 The settings below are split into several sections and grouped into
68 broad categories. Each category has a group associated with it which
69 is given at the beginning of each sub-section. Recognized keys and
70 valid values are listed following the group definition.
71 General Settings
73 The group [Settings] contains general settings.
74 ┌───────────────────────┬────────────────────────────┐
76 │AutoConnect │ Values: true, false │
77 │ │ │
78 │ │ Whether the network can be │
79 │ │ connected to automatically │
80 ├───────────────────────┼────────────────────────────┤
81 │Hidden │ Values: true, false │
82 │ │ │
83 │ │ Whether the network is │
84 │ │ hidden, i.e. its SSID must │
85 │ │ be included in an active │
86 │ │ scan request │
87 ├───────────────────────┼────────────────────────────┤
88 │AlwaysRandomizeAddress │ Values: true, false │
89 │ │ │
90 │ │ If enabled, the MAC │
91 │ │ address will be fully ran‐ │
92 │ │ domized on each connec‐ │
93 │ │ tion. This option is only │
94 │ │ used if [General].Address‐ │
95 │ │ Randomization is set to │
96 │ │ 'network'. See iwd.config. │
97 │ │ This value should not be │
98 │ │ used with [Set‐ │
99 │ │ tings].AddressOverride, if │
100 │ │ both are set AddressOver‐ │
101 │ │ ride will be used. │
102 ├───────────────────────┼────────────────────────────┤
103 │AddressOverride │ MAC address string │
104 │ │ │
105 │ │ Override the MAC address │
106 │ │ used for connecting to │
107 │ │ this network. This option │
108 │ │ is only used if [Gen‐ │
109 │ │ eral].AddressRandomization │
110 │ │ is set to 'network'. See │
111 │ │ iwd.config. This value │
112 │ │ should not be used with │
113 │ │ [Settings].FullAddressRan‐ │
114 │ │ domization, if both are │
115 │ │ set AddressOverride will │
116 │ │ be used. │
117 └───────────────────────┴────────────────────────────┘
118 Network Authentication Settings
120 The group [Security] contains settings for Wi-Fi security and authenti‐
121 cation configuration.
122 ┌───────────────────────────┬────────────────────────────────────────────┐
138 │Passphrase │ 8..63 character string │
139 │ │ │
140 │ │ Passphrase to be used when │
141 │ │ connecting to WPA-Personal │
142 │ │ networks. Required when │
143 │ │ connecting to WPA3-Per‐ │
144 │ │ sonal (SAE) networks. │
145 │ │ Also required if the Pre‐ │
146 │ │ SharedKey is not provided. │
147 │ │ If not provided in set‐ │
148 │ │ tings, the agent will be │
149 │ │ asked for the passphrase │
150 │ │ at connection time. │
151 ├───────────────────────────┼────────────────────────────────────────────┤
152 │PreSharedKey │ 64 character hex string │
153 │ │ │
154 │ │ Processed passphrase for │
155 │ │ this network in the form │
156 │ │ of a hex-encoded 32 byte │
157 │ │ pre-shared key. Must be │
158 │ │ provided if Passphrase is │
159 │ │ omitted. │
160 ├───────────────────────────┼────────────────────────────────────────────┤
161 │EAP-Method │ one of the following meth‐ │
162 │ │ ods: │
163 │ │ │
164 │ │ AKA, AKA', GTC, MD5, │
165 │ │ MSCHAPV2, PEAP, PWD, SIM, │
166 │ │ TLS, TTLS │
167 ├───────────────────────────┼────────────────────────────────────────────┤
168 │EAP-Identity │ string │
169 │ │ │
170 │ │ Identity string transmit‐ │
171 │ │ ted in plaintext. Depend‐ │
172 │ │ ing on the EAP method, │
173 │ │ this value can be optional │
174 │ │ or mandatory. GTC, MD5, │
175 │ │ MSCHAPV2, PWD require an │
176 │ │ identity, so if not pro‐ │
177 │ │ vided, the agent will be │
178 │ │ asked for it at connection │
179 │ │ time. TLS based methods │
180 │ │ (PEAP, TLS, TTLS) might │
181 │ │ still require an EAP-Iden‐ │
182 │ │ tity to be set, depending │
183 │ │ on the RADIUS server con‐ │
184 │ │ figuration. │
185 ├───────────────────────────┼────────────────────────────────────────────┤
186 │EAP-Password │ string │
187 │ │ │
188 │ │ Password to be provided │
189 │ │ for WPA-Enterprise authen‐ │
190 │ │ tication. If not pro‐ │
191 │ │ vided, the agent will be │
192 │ │ asked for the password at │
193 │ │ connection time. Required │
194 │ │ by: GTC, MD5, MSCHAPV2, │
195 │ │ PWD. │
196 └───────────────────────────┴────────────────────────────────────────────┘
197 │EAP-Password-Hash │ hex string │
206 │ │ │
207 │ │ Some EAP methods can │
208 │ │ accept a pre-hashed ver‐ │
209 │ │ sion of the password. For │
210 │ │ MSCHAPV2, a MD4 hash of │
211 │ │ the password can be given │
212 │ │ here. │
213 ├───────────────────────────┼────────────────────────────────────────────┤
214 │EAP-TLS-CACert, │ absolute file path or │
215 │EAP-TTLS-CACert, │ embedded pem │
216 │EAP-PEAP-CACert │ │
217 │ │ Path to a PEM-formatted │
218 │ │ X.509 root certificate │
219 │ │ list to use for trust ver‐ │
220 │ │ ification of the authenti‐ │
221 │ │ cator. The authentica‐ │
222 │ │ tor's server's certificate │
223 │ │ chain must be verified by │
224 │ │ at least one CA in the │
225 │ │ list for the authentica‐ │
226 │ │ tion to succeed. If omit‐ │
227 │ │ ted, then authenticator's │
228 │ │ certificate chain will not │
229 │ │ be verified (not recom‐ │
230 │ │ mended.) │
231 ├───────────────────────────┼────────────────────────────────────────────┤
232 │EAP-TLS-ClientCert │ absolute file path or │
233 │ │ embedded pem │
234 │ │ │
235 │ │ Path to a PEM-formatted │
236 │ │ client X.509 certificate │
237 │ │ or certificate chain to │
238 │ │ send on server request. │
239 ├───────────────────────────┼────────────────────────────────────────────┤
240 │EAP-TLS-ClientKey │ absolute file path or │
241 │ │ embedded pem │
242 │ │ │
243 │ │ Path to a PEM-formatted │
244 │ │ client PKCS#8 private key │
245 │ │ corresponding to the pub‐ │
246 │ │ lic key provided in │
247 │ │ EAP-TLS-ClientCert. │
248 ├───────────────────────────┼────────────────────────────────────────────┤
249 │EAP-TLS- │ string │
250 │ClientKeyPassphrase │ │
251 │ │ Decryption key for the │
252 │ │ client private key file. │
253 │ │ This is used if the pri‐ │
254 │ │ vate key given by │
255 │ │ EAP-TLS-ClientKey is │
256 │ │ encrypted. If not pro‐ │
257 │ │ vided, then the agent is │
258 │ │ asked for the passphrase │
259 │ │ at connection time. │
260 └───────────────────────────┴────────────────────────────────────────────┘
261 │EAP-TLS-ServerDomainMask, │ string │
274 │EAP-TTLS-ServerDomainMask, │ │
275 │EAP-PEAP-ServerDomainMask │ A mask for the domain │
276 │ │ names contained in the │
277 │ │ server's certificate. At │
278 │ │ least one of the domain │
279 │ │ names present in the cer‐ │
280 │ │ tificate's Subject Alter‐ │
281 │ │ native Name extension's │
282 │ │ DNS Name fields or the │
283 │ │ Common Name has to match │
284 │ │ at least one mask, or │
285 │ │ authentication will fail. │
286 │ │ Multiple masks can be │
287 │ │ given separated by semi‐ │
288 │ │ colons. The masks are │
289 │ │ split into segments at the │
290 │ │ dots. Each segment has to │
291 │ │ match its corresponding │
292 │ │ label in the domain name. │
293 │ │ An asterisk segment in the │
294 │ │ mask matches any label. │
295 │ │ An asterisk segment at the │
296 │ │ beginning of the mask │
297 │ │ matches one or more con‐ │
298 │ │ secutive labels from the │
299 │ │ beginning of the domain │
300 │ │ string. │
301 ├───────────────────────────┼────────────────────────────────────────────┤
302 │EAP-TTLS-Phase2-Method │ The following values are allowed: │
303 │ │ Tunneled-CHAP, │
304 │ │ Tunneled-MSCHAP, │
305 │ │ Tunneled-MSCHAPv2, │
306 │ │ Tunneled-PAP or │
307 │ │ a valid EAP method name (see EAP-Method) │
308 │ │ │
309 │ │ │
310 │ │ Phase 2 authentication │
311 │ │ method for EAP-TTLS. Can │
312 │ │ be either one of the │
313 │ │ TTLS-specific non-EAP │
314 │ │ methods (Tunneled-*), or │
315 │ │ any EAP method documented │
316 │ │ here. The following two │
317 │ │ settings are used if any │
318 │ │ of the non-EAP methods is │
319 │ │ used. │
320 ├───────────────────────────┼────────────────────────────────────────────┤
321 │EAP-TTLS-Phase2-Identity │ The secure identity/username string for │
322 │ │ the TTLS non-EAP Phase 2 methods. If not │
323 │ │ provided iwd will request a username at │
324 │ │ connection time. │
325 ├───────────────────────────┼────────────────────────────────────────────┤
326 │EAP-TTLS-Phase2-Password │ Password string for the TTLS non-EAP Phase │
327 │ │ 2 methods. If not provided IWD will │
328 │ │ request a passphrase at connection time. │
329 ├───────────────────────────┼────────────────────────────────────────────┤
330 │EAP-TTLS-Phase2-* │ Any settings to be used for the inner EAP │
331 │ │ method if one was specified as │
332 │ │ EAP-TTLS-Phase2-Method, rather than a │
333 │ │ TTLS-specific method. The prefix │
334 │ │ EAP-TTLS-Phase2- replaces the EAP- prefix │
335 │ │ in the setting keys and their usage is │
336 │ │ unchanged. Since the inner method's nego‐ │
337 │ │ tiation is encrypted, a secure identity │
338 │ │ string can be provided. │
339 └───────────────────────────┴────────────────────────────────────────────┘
340 │EAP-PEAP-Phase2-* │ Any settings to be used for the inner EAP │
342 │ │ method with EAP-PEAP as the outer method. │
343 │ │ The prefix EAP-PEAP-Phase2- replaces the │
344 │ │ EAP- prefix in the setting keys and their │
345 │ │ usage is unchanged. Since the inner │
346 │ │ method's negotiation is encrypted, a │
347 │ │ secure identity string can be provided. │
348 └───────────────────────────┴────────────────────────────────────────────┘
349 Network Configuration Settings
351 The group [IPv4] contains settings for Internet Protocol version 4
352 (IPv4) network configuration with the static addresses.
353 ┌───────────┬────────────────────────────┐
355 │Address │ IPv4 address string │
356 │ │ │
357 │ │ The IPv4 address to │
358 │ │ assign. This field is │
359 │ │ required for the static │
360 │ │ configuration. │
361 ├───────────┼────────────────────────────┤
362 │Gateway │ IPv4 address string │
363 │ │ │
364 │ │ The IPv4 address of the │
365 │ │ gateway (router). This │
366 │ │ field is required for the │
367 │ │ static configuration. │
368 ├───────────┼────────────────────────────┤
369 │DNS │ IPv4 address string │
370 │ │ │
371 │ │ The IPv4 address of the │
372 │ │ Domain Name System (DNS). │
373 │ │ This field is optional. │
374 │ │ DNS setting can be used to │
375 │ │ override the DNS entries │
376 │ │ received from the DHCP │
377 │ │ server. │
378 ├───────────┼────────────────────────────┤
379 │Netmask │ IPv4 address string │
380 │ │ │
381 │ │ The IPv4 address of the │
382 │ │ subnet. This field is │
383 │ │ optional. 255.255.255.0 is │
384 │ │ used as default Netmask. │
385 ├───────────┼────────────────────────────┤
386 │Broadcast │ IPv4 address string │
387 │ │ │
388 │ │ The IPv4 address to be │
389 │ │ used for the broadcast. │
390 │ │ This field is optional. │
391 ├───────────┼────────────────────────────┤
392 │DomainName │ string │
393 │ │ │
394 │ │ The DomainName is the name │
395 │ │ of the local Internet │
396 │ │ domain. This field is │
397 │ │ optional. DomainName set‐ │
398 │ │ ting can be used to over‐ │
399 │ │ ride the DomainName value │
400 │ │ obtained from the DHCP │
401 │ │ server. │
402 └───────────┴────────────────────────────┘
403 Embedded PEMs
405 Rather than including an absolute path to a PEM file (for certificates
406 and keys), the PEM itself can be included inside the settings file and
407 referenced directly. This allows IEEE 802.1x network provisioning using
408 a single file without any references to certificates or keys on the
409 system.
410 An embedded PEM can appear anywhere in the settings file using the fol‐
412 lowing format (this example the PEM is named 'my_ca_cert'):
413 [@pem@my_ca_cert]
415 ----- BEGIN CERTIFICATE -----
416 <PEM data>
417 ----- END CERTIFICATE -----
418 After this special group tag its as simple as pasting in a PEM file
420 including the BEGIN/END tags. Now 'my_ca_cert' can be used to reference
421 the certificate elsewhere in the settings file by prefixing the value
422 with 'embed:'
423 EAP-TLS-CACert=embed:my_ca_cert
425 This is not limited to CA Certificates either. Client certificates,
427 client keys (encrypted or not), and certificate chains can be included.
428
430 The following are some examples of common configurations
431 Open Network (Hidden)
433 [Settings]
434 Hidden=true
435 Pre-Shared Key (PSK)
437 [Security]
438 Passphrase=secret123
439 PWD
441 [Security]
442 EAP-Method=PWD
443 EAP-Identity=user@domain.com
444 EAP-Password=secret123
445 TLS
447 [Security]
448 EAP-Method=TLS
449 EAP-TLS-ClientCert=/certs/client-cert.pem
450 EAP-TLS-ClientKey=/certs/client-key.pem
451 EAP-TLS-CACert=/certs/ca-cert.pem
452 EAP-TLS-ServerDomainMask=*.domain.com
453 TTLS + PAP
455 [Security]
456 EAP-Method=TTLS
457 EAP-Identity=open@identity.com
458 EAP-TTLS-CACert=/certs/ca-cert.pem
459 EAP-TTLS-Phase2-Method=Tunneled-PAP
460 EAP-TTLS-Phase2-Identity=username
461 EAP-TTLS-Phase2-Password=password
462 EAP-TTLS-ServerDomainMask=*.domain.com
463 PEAP + MSCHAPv2
465 [Security]
466 EAP-Method=PEAP
467 EAP-Identity=open@identity.com
468 EAP-PEAP-CACert=/certs/ca-cert.pem
469 EAP-PEAP-Phase2-Method=MSCHAPV2
470 EAP-PEAP-Phase2-Identity=username
471 EAP-PEAP-Phase2-Password=password
472 EAP-PEAP-ServerDomainMask=*.domain.com
473
475 iwd(8), iwd.config(5)
476
478 Marcel Holtmann <marcel@holtmann.org>, Denis Kenzior
479 <denkenz@gmail.com>, Andrew Zaborowski <andrew.zaborowski@intel.com>,
480 Tim Kourt <tim.a.kourt@linux.intel.com>, James Prestwood <prest‐
481 woj@gmail.com>
482
484 2013-2019 Intel Corporation
485iwd 22 September 2019 IWD.NETWORK(5)