iwd.network − Network configuration for wireless daemon
Network configuration files .open, .psk and .8021x
iwd stores information on known networks, and reads information on pre−provisioned networks, from small text configuration files. Those files live in the state directory specified by the environment variable $STATE_DIRECTORY, which is normally provided by systemd. In the absence of such an environment variable it defaults to $LIBDIR/iwd, which normally is set to /var/lib/iwd. You can create, modify or remove those files. iwd monitors the directory for changes and will update its state accordingly. iwd will also modify these files in the course of network connections or as a result of D−Bus API invocations.
The syntax is similar to that of GNOME keyfile syntax (which is based on the format defined in the Desktop Entry Specification, see http://freedesktop.org/Standards/desktop−entry−spec). The recognized groups as well as keys and values in each group are documented here. Defaults are written in bold.
For completeness we include the description of the file syntax here. This is the syntax that the ell library's l_settings class implements. The syntax is based on lines and lines are delimited by newline characters.
Empty lines are ignored and whitespace at the beginning of a line is ignored. Comment lines have # as their first non−whitespace character.
Key−value lines contain a setting key, an equal sign and the value of the setting. Whitespace preceding the key, the equal sign or the value, is ignored. The key must be a continuous string of alphanumeric and underscore characters and minus signs only. The value starts at the first non−whitespace character after the first equal sign on the line and ends at the end of the line and must be correctly UTF−8−encoded. A boolean value can be true or false but 0 or 1 are also allowed. Integer values are written in base 10. String values, including file paths and hexstrings, are written as is except for five characters that may be backslash−escaped: space, \t, \r, \n and backslash itself. The latter three must be escaped. A space character must be escaped if it is the first character in the value string and is written as \s.
Settings are interpreted depending on the group they are in. A group starts with a group header line and contains all settings until the next group's header line. A group header line contains a [ character followed by the group name and a ] character. Whitespace is allowed before the [ and after the ]. A group name consists of printable characters other than [ and ].
If a group name starts with the @ sign, that group's content is handled by a parser extension instead and does not cause the previous non−extension group to end. The initial @ sign must be followed by a non−empty extension name, another @ sign and a group name as defined above. The extension name consists of printable characters other than @. No whitespace is allowed after the group header in this case. The extension payload syntax and length are determined by the extension name. Normal parsing rules defined in this section resume at the end of the payload and any settings after the end of the payload are handled as part of the previous non−extension group.
Currently the only extension supported is named pem and allows embedding the contents of a single RFC7468 PEM−formatted payload or a sequence of multiple PEM payloads. The payload should start with the −−−−−BEGIN string on a line following the group header line and end with an −−−−−END line as specified in the RFC. Newline characters before, between and after PEM payloads are included in the extension payload. No other extra characters are allowed.
File names are based on the network's SSID and security type: Open, PSK−protected or 802.1x. The name consist of the encoding of the SSID followed by .open, .psk or .8021x. The SSID appears verbatim in the name if it contains only alphanumeric characters, spaces, underscores or minus signs. Otherwise it is encoded as an equal sign followed by the lower−case hex encoding of the name.
The settings below are split into several sections and grouped into broad categories. Each category has a group associated with it which is given at the beginning of each sub−section. Recognized keys and valid values are listed following the group definition.
|
The group [Settings] contains general settings. |
The group [Security] contains settings for Wi−Fi security and authentication configuration. This group can be encrypted by enabling SystemdEncrypt, see iwd.config for details on this option. If this section is encrypted (only contains EncryptedSalt/EncryptedSecurity) it should not be modified. Modifying these values will result in the inability to connect to that network.
The group [Network] contains general network settings and any network specific overrides for global defaults defined in the main iwd configuration file.
The group [IPv4] contains settings for Internet Protocol version 4 (IPv4) network configuration with the static addresses.
The group [IPv6] contains settings for Internet Protocol version 6 (IPv6) network configuration.
Rather than including an absolute path to a PEM file (for certificates and keys), the PEM itself can be included inside the settings file and referenced directly. This allows IEEE 802.1x network provisioning using a single file without any references to certificates or keys on the system.
An embedded PEM can appear anywhere in the settings file using the following format (in this example the PEM is named 'my_ca_cert'):
[@pem@my_ca_cert]
−−−−− BEGIN CERTIFICATE
−−−−−
<PEM data>
−−−−− END CERTIFICATE
−−−−−
After this special group tag it's as simple as pasting in a PEM file including the BEGIN/END tags. Now 'my_ca_cert' can be used to reference the certificate elsewhere in the settings file by prefixing the value with 'embed:'
EAP−TLS−CACert=embed:my_ca_cert
This is not limited to CA Certificates either. Client certificates, client keys (encrypted or not), and certificate chains can be included.
The following are some examples of common configurations
[Settings]
Hidden=true
[Security]
Passphrase=secret123
[Security]
EAP−Method=PWD
EAP−[email protected]
EAP−Password=secret123
[Security]
EAP−Method=TLS
EAP−TLS−ClientCert=/certs/client−cert.pem
EAP−TLS−ClientKey=/certs/client−key.pem
EAP−TLS−CACert=/certs/ca−cert.pem
EAP−TLS−ServerDomainMask=*.domain.com
[Security]
EAP−Method=TTLS
EAP−[email protected]
EAP−TTLS−CACert=/certs/ca−cert.pem
EAP−TTLS−Phase2−Method=Tunneled−PAP
EAP−TTLS−Phase2−Identity=username
EAP−TTLS−Phase2−Password=password
EAP−TTLS−ServerDomainMask=*.domain.com
[Security]
EAP−Method=PEAP
EAP−[email protected]
EAP−PEAP−CACert=/certs/ca−cert.pem
EAP−PEAP−Phase2−Method=MSCHAPV2
EAP−PEAP−Phase2−Identity=username
EAP−PEAP−Phase2−Password=password
EAP−PEAP−ServerDomainMask=*.domain.com
iwd(8), iwd.config(5)
Marcel Holtmann <[email protected]>, Denis Kenzior <[email protected]>, Andrew Zaborowski <[email protected]>, Tim Kourt <[email protected]>, James Prestwood <[email protected]>
2013-2019 Intel Corporation