Provided by: iwd_1.26-3_amd64 
NAME
iwd.network - Network configuration for wireless daemon
SYNOPSIS
Network configuration files .open, .psk and .8021x
DESCRIPTION
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.
FILE FORMAT
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.
NAMING
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.
SETTINGS
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.
General Settings
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.
───────────────────────────────────────────────────────────────────
TransitionDisable Values: true, false
If enabled, the use of TKIP pairwise
cipher and connections without
Management Frame Protection are
disallowed. This will make certain
legacy access points unavailable for
use. Additional security hardening
can also be applied via the
[Settings].DisabledTransitionModes
setting.
Properly configured Access Points
will typically update this setting
appropriately via Transition Disable
indications. User customization of
this value is thus typically not
required.
───────────────────────────────────────────────────────────────────
DisabledTransitionModes Comma-separated list of disabled
transition modes:
• personal
• enterprise
• open
If 'personal' mode is
disabled, then legacy
WPA2-Personal access points
are no longer available to be
connected to or roamed to.
Only access points utilizing
WPA3-Personal will be
considered.
If 'enterprise' mode is
disabled, then legacy
WPA2-Enterprise access points
are no longer available to be
connected to or roamed to.
If 'open' mode is disabled,
then non-OWE enabled access
points will not be connected
to.
Properly configured Access
Points will typically update
this setting appropriately via
Transition Disable
indications. User
customization of this value is
thus typically not required.
┌─────────────────────────┬───────────────────────────────────────┐
│ │ │
Network Authentication│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.
───────────────────────────────────────────────────────────────────────────
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, absolute file path or embedded pem
EAP-TTLS-CACert,
EAP-PEAP-CACert 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 the client X.509 certificate
or certificate chain to send on
server request.
───────────────────────────────────────────────────────────────────────────
EAP-TLS-ClientKey absolute file path or embedded pem
Path to the client private key
corresponding to the public key
provided in EAP-TLS-ClientCert. The
recommended format is PKCS#8 PEM.
───────────────────────────────────────────────────────────────────────────
EAP-TLS-ClientKeyBundle absolute file path
As an alternative to
EAP-TLS-ClientCert and
EAP-TLS-ClientKey IWD can load both
the certificate and the private key
from a container file pointed by this
setting. The recommended format is
PKCS#12 when this is used.
───────────────────────────────────────────────────────────────────────────
EAP-TLS- string
ClientKeyPassphrase
Decryption key for the client key
files. This should be used if the
certificate or the private key in the
files mentioned above is encrypted.
When not given, the agent is asked
for the passphrase at connection
time.
───────────────────────────────────────────────────────────────────────────
EAP-TLS-ServerDomainMask, string
EAP-TTLS-ServerDomainMask,
EAP-PEAP-ServerDomainMask 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:
Tunneled-CHAP,
Tunneled-MSCHAP,
Tunneled-MSCHAPv2,
Tunneled-PAP or
a valid EAP method name (see EAP-Method)
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. │
└────────────────────────────┴────────────────────────────────────────────┘
Network Configuration Settings
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 list, space
delimited
The IPv4 address(es) 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.
────────────────────────────────────────────────────────
SendHostname Values: true, false
Configures DHCP to include the
hostname in the request. This setting
is disabled by default.
┌──────────────┬───────────────────────────────────────┐
│ │ │
--
EXAMPLES
The following are some examples of common configurations
Open Network (Hidden)
[Settings]
Hidden=true
Pre-Shared Key (PSK)
[Security]
Passphrase=secret123
PWD
[Security]
EAP-Method=PWD
EAP-Identity=user@domain.com
EAP-Password=secret123
TLS
[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
TTLS + PAP
[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
PEAP + MSCHAPv2
[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
SEE ALSO
iwd(8), iwd.config(5)
AUTHOR
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>
COPYRIGHT
2013-2019 Intel Corporation
iwd 22 September 2019 IWD.NETWORK(5)