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.
AutoConnect |
Values: true, false Whether
the network can be connected to automatically |
Hidden |
Values: true, false Whether
the network is hidden, i.e. its SSID must be included in an active scan
request |
AlwaysRandomizeAddress |
Values: true, false If
enabled, the MAC address will be fully randomized on each connection. This
option is only used if [General].AddressRandomization is set to 'network'.
See iwd.config. This setting should not be used with
[Settings].AddressOverride, if both are set AddressOverride will be
used. |
AddressOverride |
MAC address string Override the MAC
address used for connecting to this network. This option is only used if
[General].AddressRandomization is set to 'network'. See iwd.config. This
setting should not be used with [Settings].AlwaysRandomizeAddress, if both
are set AddressOverride will be used. |
The group [Security] contains settings for Wi-Fi security and
authentication configuration.
Passphrase |
8..63 character string Passphrase to
be used when connecting to WPA-Personal networks. Required when connecting
to WPA3-Personal (SAE) networks. Also required if the PreSharedKey
is not provided. If not provided in settings, the agent will be asked for
the passphrase at connection time. |
PreSharedKey |
64 character hex string Processed
passphrase for this network in the form of a hex-encoded 32 byte
pre-shared key. Must be provided if Passphrase is omitted. |
EAP-Method |
one of the following methods: AKA,
AKA', MSCHAPV2, PEAP, PWD, SIM, TLS, TTLS. The following additional
methods are allowed as TTLS/PEAP inner methods: GTC, MD5. |
EAP-Identity |
string Identity string transmitted in
plaintext. Depending on the EAP method, this value can be optional or
mandatory. GTC, MD5, MSCHAPV2, PWD require an identity, so if not
provided, the agent will be asked for it at connection time. TLS based
methods (PEAP, TLS, TTLS) might still require an EAP-Identity to be
set, depending on the RADIUS server configuration. |
EAP-Password |
string Password to be provided for
WPA-Enterprise authentication. If not provided, the agent will be asked
for the password at connection time. Required by: GTC, MD5, MSCHAPV2,
PWD. |
EAP-Password-Hash |
hex string Some EAP methods can
accept a pre-hashed version of the password. For MSCHAPV2, a MD4 hash of
the password can be given here. |
EAP-TLS-CACert, EAP-TTLS-CACert,
EAP-PEAP-CACert |
absolute file path or embedded pem
Path to a PEM-formatted X.509 root certificate list to use for trust
verification of the authenticator. The authenticator's server's
certificate chain must be verified by at least one CA in the list for the
authentication to succeed. If omitted, then authenticator's certificate
chain will not be verified (not recommended.) |
EAP-TLS-ClientCert |
absolute file path or embedded pem
Path to a PEM-formatted client X.509 certificate or certificate chain to
send on server request. |
EAP-TLS-ClientKey |
absolute file path or embedded pem
Path to a PEM-formatted client PKCS#8 private key corresponding to the
public key provided in EAP-TLS-ClientCert. |
EAP-TLS- ClientKeyPassphrase |
string Decryption key for the client
private key file. This is used if the private key given by
EAP-TLS-ClientKey is encrypted. If not provided, then the agent is
asked for the passphrase at connection time. |
EAP-TLS-ServerDomainMask,
EAP-TTLS-ServerDomainMask, EAP-PEAP-ServerDomainMask |
string A mask for the domain names
contained in the server's certificate. At least one of the domain names
present in the certificate's Subject Alternative Name extension's DNS Name
fields or the Common Name has to match at least one mask, or
authentication will fail. Multiple masks can be given separated by
semicolons. The masks are split into segments at the dots. Each segment
has to match its corresponding label in the domain name. An asterisk
segment in the mask matches any label. An asterisk segment at the
beginning of the mask matches one or more consecutive labels from the
beginning of the domain string. |
EAP-TTLS-Phase2-Method |
The following values are allowed: +2
Tunneled-CHAP, Tunneled-MSCHAP, Tunneled-MSCHAPv2, Tunneled-PAP or a valid
EAP method name (see EAP-Method) -2 Phase 2 authentication method
for EAP-TTLS. Can be either one of the TTLS-specific non-EAP methods
(Tunneled-*), or any EAP method documented here. The following two
settings are used if any of the non-EAP methods is used. |
EAP-TTLS-Phase2-Identity |
The secure identity/username string
for the TTLS non-EAP Phase 2 methods. If not provided iwd will
request a username at connection time. |
EAP-TTLS-Phase2-Password |
Password string for the TTLS non-EAP
Phase 2 methods. If not provided IWD will request a passphrase at
connection time. |
EAP-TTLS-Phase2-* |
Any settings to be used for the inner
EAP method if one was specified as EAP-TTLS-Phase2-Method, rather
than a TTLS-specific method. The prefix EAP-TTLS-Phase2- replaces
the EAP- prefix in the setting keys and their usage is unchanged.
Since the inner method's negotiation is encrypted, a secure identity
string can be provided. |
EAP-PEAP-Phase2-* |
Any settings to be used for the inner
EAP method with EAP-PEAP as the outer method. The prefix
EAP-PEAP-Phase2- replaces the EAP- prefix in the setting
keys and their usage is unchanged. Since the inner method's negotiation is
encrypted, a secure identity string can be provided. |
The group [IPv4] contains settings for Internet Protocol version 4 (IPv4)
network configuration with the static addresses.
Address |
IPv4 address string The IPv4 address
to assign. This field is required for the static
configuration. |
Gateway |
IPv4 address string The IPv4 address
of the gateway (router). This field is required for the static
configuration. |
DNS |
IPv4 address string The IPv4 address
of the Domain Name System (DNS). This field is optional. DNS
setting can be used to override the DNS entries received from the DHCP
server. |
Netmask |
IPv4 address string The IPv4 address
of the subnet. This field is optional. 255.255.255.0 is used as
default Netmask. |
Broadcast |
IPv4 address string The IPv4 address
to be used for the broadcast. This field is optional. |
DomainName |
string The DomainName is the name of
the local Internet domain. This field is optional. DomainName
setting can be used to override the DomainName value obtained from the
DHCP server. |
The group [IPv6] contains settings for Internet Protocol
version 6 (IPv6) network configuration.
Enabled |
Boolean Whether IPv6 is enabled for
this network. If not provided, then the global default provided by
[Network].EnableIPv6 setting will be used. If IPv6 is disabled, then the
'disable_ipv6' setting in sysfs will be set to 1 and no IPv6 addresses or
routes will be created for this network. |
Address |
IPv6 address string The IPv6 address
to assign. This field is required for the static configuration. The
recognized format is according to inet_pton followed by '/' and prefix
length. If prefix length is omitted, then 128 is assumed. |
Gateway |
IPv6 address string The IPv6 address
of the gateway (router). This field is required for the static
configuration. |
DNS |
IPv6 address string The IPv6 address
of the Domain Name System (DNS). This field is optional. DNS
setting can be used to override the DNS entries received from the DHCPv6
server or via Router Advertisements. |
DomainName |
string The DomainName is the name of
the local Internet domain. This field is optional. DomainName
setting can be used to override the DomainName value obtained from the
DHCPv6 server or via Router Advertisements. |
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
[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
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