User Tools

Site Tools


networkconfigurationsettings

IWD stores information on known networks, and reads information on pre-provisioned networks, from small text configuration files. Those files live in $LIBDIR/iwd, by default /var/lib/iwd. You can create, modify or remove those files. IWD monitors the directory for changes and will also modify these files in the course of network connections as necessary.

For most up-to-date information on network settings see the iwd.network(5) man page shipped with IWD (source), which incorporates most of this page's content now.

File format

The syntax is similar to that of GNOME keyfile syntax and other popular formats, using comment lines, group header lines and Key=Value lines. The allowed keys and values in each group are documented here. Defaults are written in bold. Values marked as internal should not normally be used by users or administrators.

General network configuration settings

Setting Key Values Description
Group header: [Settings]
AutoConnect true, false (optional)
Autoconnect true, false (deprecated in favour or AutoConnect) (optional)
Hidden true, false Used for hidden networks i.e. those that do not reply to scan probing except when their SSIDs are included explicitly (optional)
AlwaysRandomizeAddress true, false Always randomize MAC address on each new connection. Requires AddressRandomization=network in main.conf (optional)
AddressOverride MAC Address Override the MAC address used for this network. Requires AddressRandomization=network in main.conf (optional)

Pre-Shared Key (WPA/WPA2 Personal/SAE) network settings

Setting Key Values Description
Group header: [Security]
Passphrase text The passphrase for passphrase-protected networks. No default, if not provided IWD will request the passphrase at connection time. 8 to 63 characters.
PreSharedKey 32-byte hexstring Processed version of the passphrase+SSID strings for daemon's internal use (optional)

802.1x (WPA/WPA2 Enterprise) settings

The values here will apply to both IWD and EAD.

Setting Key Values Description
Group header: [Security]
EAP-Method AKA, AKA', GTC (internal), MD5 (internal), MSCHAPV2, PEAP, PWD, SIM, TLS, TTLS, WSC (internal) No default
Applies to: EAP-SIM, EAP-AKA, EAP-AKA'
EAP-Identity text EAP identity string transmitted in plaintext, if any (optional)
Applies to: EAP-GTC (Only EAD or TTLS/PEAP inner method)
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP GTC secret string. No default, if not provided IWD will request a passphrase at connection time
EAP-GTC-Secret text (deprecated in favour of EAP-Password)
Applies to: EAP-MD5 (Only EAD or TTLS/PEAP inner method)
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP MD5 secret string. No default, if not provided IWD will request a passphrase at connection time
EAP-MD5-Secret text (deprecated in favour of EAP-Password)
Applies to: EAP-MSCHAPV2
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP MsCHAPv2 password string. No default, if neither Password nor Password-Hash are provided IWD will request a passphrase at connection time
EAP-Password-Hash 16-byte hexstring An alternative way to specify the MsCHAPv2 password as an MD4 hash, see RFC 2433
Applies to: EAP-TLS, EAP-TTLS, EAP-PEAP
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time. See RFC 5216 Section 5.2 for requirements on peer identity with regards to client certificate contents.
EAP-TLS-CACert,
EAP-TTLS-CACert,
EAP-PEAP-CACert
file path or embedded pem Path to a PEM-formatted X.509 root certificate list to use for trust verification, both for the server's certificate chain and the chain specified with ClientCert (if any). IWD will require that the root in the verified certificate chains is trusted by at least one CA in the list. If not provided IWD will have no way to authenticate the server – discouraged. (optional)
EAP-TLS-ClientCert,
EAP-TTLS-ClientCert,
EAP-PEAP-ClientCert
file path or embedded pem Path to a PEM-formatted client X.509 certificate or certificate chain to send on server request. For some networks this is mandatory, for others optional.
EAP-TLS-ClientKey,
EAP-TTLS-ClientKey,
EAP-PEAP-ClientKey
file path or embedded pem Path to a PEM-formatted PKCS #8 private key corresponding to the certified client public key to authenticate ourselves to the server with. For some networks this is manadatory, for others optional.
EAP-TLS-ClientKeyPassphrase,
EAP-TTLS-ClientKeyPassphrase,
EAP-PEAP-ClientKeyPassphrase
text Decryption key for the client private key file. Must be present iff the private key under ClientKey is encrypted.
EAP-TLS-ServerDomainMask,
EAP-TTLS-ServerDomainMask,
EAP-PEAP-ServerDomainMask
text 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 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. No default value.
EAP-TTLS-Phase2-Identity text The secure identity/username string for the TTLS non-EAP Phase 2 methods. No default, if not provided IWD will request a username at connection time.
EAP-TTLS-Phase2-Password text Password string for the TTLS non-EAP Phase 2 methods. No default, 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.
Applies to: EAP-PWD
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP PWD password string. No default, if not provided IWD will request a passphrase at connection time
EAP-PWD-Secret text (deprecated in favour of EAP-Password)

Embedded PEMs

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

CA certificates, client certificate chains and client keys (encrypted or not) can be included in this way.

File naming and syntax

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.

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 the \n 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.

Example network configuration files

EAP Transport Layer Security (EAP-TLS)

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TLS-ClientCert=</certs/client-cert.pem>
#EAP-TLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TLS-ClientKeyPassphrase=<client private key passphrase>

EAP Tunneled Transport Layer Security (EAP-TTLS)

iNet Wireless Daemon (iwd) supports Extensible Authentication Protocol Tunneled Transport Layer Security Authenticated Protocol Version 0 (EAP-TTLSv0). The tunneled authentication mechanism may itself be EAP, or it may be another authentication protocol such as PAP, CHAP, MS-CHAP, or MS-CHAP-V2.

EAP-TTLS with tunneled CHAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-CHAP
 
# Uncomment to provide CHAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled MS-CHAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-MSCHAP
 
# Uncomment to provide MS-CHAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled MS-CHAP-V2

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-MSCHAPv2
 
# Uncomment to provide MS-CHAPv2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled PAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-PAP
 
# Uncomment to provide PAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled EAP method

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=MSCHAPV2
 
# Uncomment to provide EAP-MSCHAPV2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-PEAP

Protected EAP (PEAP) is comprised of a two-part conversation:

  • In Part 1, a TLS session is negotiated, with server authenticating to the client and optionally the client to the server. The negotiated key is then used to encrypt the rest of the conversation.
  • In Part 2, within the TLS session, a complete EAP conversation is carried out. The configuration examples of the most commonly supported methods: EAP-MSCHAPV2, EAP-GTC and EAP-SIM are provided below.

iNet Wireless Daemon (iwd) offers two versions of PEAP: PEAPv0 and PEAPv1. The highest version supported by authenticator will be negotiated at the connection time.

EAP-PEAP with tunneled EAP-MSCHAPV2

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=MSCHAPV2
 
# Uncomment to provide EAP-MSCHAPV2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-PEAP-Phase2-Identity=<username>
#EAP-PEAP-Phase2-Password=<password>

EAP-PEAP with tunneled EAP-GTC

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=GTC
 
# Uncomment to provide EAP-GTC Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-PEAP-Phase2-Identity=<username>
#EAP-PEAP-Phase2-Password=<password>

EAP-PEAP with tunneled EAP-SIM

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=SIM
 
# Uncomment to provide EAP-SIM Identity
#EAP-PEAP-Phase2-Identity=<identity>
networkconfigurationsettings.txt · Last modified: 2020/11/19 06:33 by Andrew Zaborowski