iwd.network - Man Page

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.

EAP-TLS-CACert,
EAP-TTLS-CACert,
EAP-PEAP-CACert

EAP-TLS-
ClientKeyPassphrase

EAP-TLS-ServerDomainMask,
EAP-TTLS-ServerDomainMask,
EAP-PEAP-ServerDomainMask

EAP-TLS-FastReauthentication,
EAP-TTLS-FastReauthentication,
EAP-PEAP-FastReauthentication,

EAP-TTLS-Phase2-Method

The following values are allowed:
Tunneled-CHAP,
Tunneled-MSCHAP,
Tunneled-MSCHAPv2,
Tunneled-PAP or
a valid EAP method name (see EAP-Method)

EAP-TTLS-Phase2-Identity

EAP-TTLS-Phase2-Password

[@pem@my_ca_cert]
----- BEGIN CERTIFICATE -----
<PEM data>
----- END CERTIFICATE -----

The following are some examples of common configurations

[Settings]
Hidden=true

[Security]
Passphrase=secret123

[Security]
EAP-Method=PWD
EAP-Identity=user@domain.com
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-Identity=open@identity.com
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-Identity=open@identity.com
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 <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(8), iwd.ap(5), iwd.config(5).