Settings Object Specifications
Each section describes a particular settings object. Every settings object MUST have a 'type' key/value pair that specifies that settings object's type, which is an arbitrary lower-case UTF-8 string. All settings object keys are required to be present unless marked 'optional'.
All key types are D-Bus key types, ie STRING == DBUS_TYPE_STRING. If the type is ARRAY, the contained type is specified within brackets ([]). If there are any length specifications for the array, the length is specified after the item to which it applies, like so: /6. So, ARRAY[BYTE/6] means "a D-Bus byte array of length 6". Optional array members are specified inside ().
Please mark entries that have not been accepted into the official configuration specification with <rowstyle="background-color: #ff7f7f;">.
connection
The connection object describes general information for a network connection.
key
key type
value
notes
name
STRING
connection
id
STRING
user readable UTF-8 connection identifier; must be unique among all connections provided by a settings service
uuid
STRING
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
A universally unique connection identifer. The UUID should be assigned at connection creation time, and should never change over the lifetime of the connection. It should be unique within all connections exported by that settings service that exports the connection. Each character of the UUID must satisfy [a-f][0-9]. See the output of 'uuidgen' from e2fsprogs
type
STRING
The settings object type of the base network device type the connection requires, ex. '802-11-wireless'
autoconnect
BOOLEAN
If true, NM will automatically activate the connection (optional, defaults to true)
timestamp
UINT64
optional, the time in seconds since the Unix epoch (as returned by time(2)) when this connection was last successfully activated
802-3-ethernet
Describes IEEE 802.3 ethernet specific settings.
key
key type
value
notes
name
STRING
802-3-ethernet
port
STRING
tp, aui, bnc, mii
optional, default is driver default
speed
UINT32
[1...]
optional, default is driver default
duplex
STRING
half, full
optional, default is driver default
auto-negotiate
BOOLEAN
optional, default is driver default
mac-address
ARRAY[BYTE/6]
optional, if present the connection will only apply to the device with the given MAC address
mtu
UINT32
[1...]
optional, default is driver default
802-11-wireless
Describes IEEE 802.11 a/b/g wireless specific settings.
key
key type
value
notes
name
STRING
802-11-wireless
ssid
ARRAY[BYTE/32]
mode
STRING
infrastructure, adhoc
band
STRING
a, bg
optional, default is 'bg'. If 'channel' is also specified, it must fall inside the legal values for the specified band
channel
UINT16
[1...14] for bg band, and [7, 8, 9, 11, 12, 16, 34, 36, 40, 44, 48, 52, 56, 60, 64, 100, 104, 108, 112, 116, 120, 124, 128, 132, 136, 140, 149, 153, 157, 161, 165, 183, 184, 185, 187, 188, 192, 196] for a band
optional, but 'band' must also be specified, and the channel must fall inside the legal values for that band
bssid
ARRAY[BYTE/6]
optional, must be 6 bytes in length; connections will only be made to the specified BSSID
rate
UINT16
[1...]
optional, in megabits per second (Mb/s)
tx-power
UINT16
[1...]
optional, in dBm
mac-address
ARRAY[BYTE/6]
optional, if present the connection will only apply to the device with the given MAC address
mtu
UINT32
[1...]
optional, default is driver default
seen-bssids
ARRAY[STRING]
optional, an array of strings, representing BSSIDs that have been previously connected to or roamed to with this connection
security
STRING
802-11-wireless-security
optional; the settings object type of the security to use for this connection, if any. If not present, an open, unencrypted network is assumed.
802-11-wireless-security
Describes IEEE 802.11 a/b/g wireless security settings. These options correspond almost directly to wpa_supplicant configuration options for a network block. Any restrictions that wpa_supplicant places on the options are in effect here as well. For example, you cannot use key-mgmt=WPA-EAP and have wep-key0 set, because those options are mutually exclusive.
Furthermore, all secrets (like WEP keys, WPA pre-shared-keys, certificate passphrases, etc) are retrieved by NM out-of-band. The key must be present in the Settings object, but the value MUST be a blank string. These keys give NM hints about what secrets may be required (for example, that more than one WEP key should be set) but NM will request any secrets it deems necessary irregardless of what's included in the Settings object.
key
key type
value
notes
name
STRING
802-11-wireless-security
key-mgmt
STRING
NONE, IEEE8021X, WPA-NONE, WPA-PSK, WPA-EAP
Required
wep-tx-keyidx
BYTE
[0...3]
WEP transmit key index
auth-alg
STRING
OPEN, SHARED, LEAP
Required for WEP and LEAP, ignored for WPA/802.1x (since these use only OPEN).
proto
STRING
WPA, RSN
(WPA2 not allowed since it's an alias of RSN anyway)
pairwise
ARRAY[STRING]
TKIP, CCMP
Any combination is allowed
group
ARRAY[STRING]
WEP40, WEP104, TKIP, CCMP
Any combination is allowed
leap-username
STRING
The LEAP username to use with legacy LEAP connections (where auth-alg == LEAP)
wep-key0
STRING
secret, do not include if not known
wep-key1
STRING
secret, do not include if not known
wep-key2
STRING
secret, do not include if not known
wep-key3
STRING
secret, do not include if not known
psk
STRING
secret, do not include if not known
leap-password
STRING
secret, do not include if not known
802-1x
Describes 802.1x security settings, either for WPA, WPA2, Dynamic WEP, or wired 802.1x. These options correspond almost directly to wpa_supplicant configuration options for a network block. Any restrictions that wpa_supplicant places on the options are in effect here as well.
key
key type
value
notes
name
STRING
802-1x
eap
ARRAY[STRING]
LEAP, MD5, TLS, PEAP, TTLS, SIM, PSK, FAST
identity
STRING
anonymous-identity
STRING
ca-cert
ARRAY[BYTE]
Contents of PEM- or DER-format certificate (integrate with standard certificate databases somehow?)
ca-path
STRING
Path to system trusted CA list (instead of paths, integrate with standard certificate databases somehow?)
client-cert
ARRAY[BYTE]
Contents of PEM- or DER-format certificate (integrate with standard certificate databases somehow?)
private-key
ARRAY[BYTE]
Contents of PEM-, DER-, or PFX-format private key file (integrate with standard certificate databases somehow?)
phase1-peapver
STRING
0, 1
phase1-peaplabel
STRING
1
phase1-fast-provisioning
STRING
1
Only with eap=FAST
phase2-auth
STRING
PAP, CHAP, MSCHAP, MSCHAPV2, GTC, OTP, MD5, TLS
phase2-autheap
STRING
MD5, MSCHAPV2, OTP, GTC, TLS
phase2-ca-cert
ARRAY[BYTE]
Contents of PEM- or DER-format certificate (integrate with standard certificate databases somehow?)
phase2-ca-path
STRING
Path to system trusted CA list (instead of paths, integrate with standard certificate databases somehow?)
phase2-client-cert
ARRAY[BYTE]
Contents of PEM- or DER-format certificate (integrate with standard certificate databases somehow?)
phase2-private-key
ARRAY[BYTE]
Contents of PEM-, DER-, or PFX-format private key file (integrate with standard certificate databases somehow?)
psk
STRING
secret, do not include if not known
password
STRING
secret, do not include if not known
pin
STRING
secret, do not include if not known
pkcs11-engine-path
STRING
/usr/lib/engines/engine_pkcs11.so
Path to the OpenSSL engine for interfacing to a PKCS#11 module
pkcs11-module-path
STRING
Path to a PKCS#11 module, such as Gnome Keyring's PKCS#11 library or openCryptoki's PKCS#11 library
pkcs11-ca-cert
STRING
PKCS#11 ID of the CA certificate
pkcs11-client-cert
STRING
PKCS#11 ID of the client certificate
pkcs11-private-key
STRING
PKCS#11 ID of the private key
pkcs11-phase2-ca-cert
STRING
PKCS#11 ID of the CA certificate for phase2
pkcs11-phase2-client-cert
STRING
PKCS#11 ID of the client certificate for phase2
pkcs11-phase2-private-key
STRING
PKCS#11 ID of the private key for phase2
ipv4
Describes IPv4 settings.
key
key type
value
notes
name
STRING
ipv4
method
STRING
dhcp, autoip, manual,shared
Determines the IP configuration method. When 'autoip' is specified, no other options are allowed. If 'dhcp' is specified, DHCP will be used but any other specified settings override DHCP server-returned settings. For 'shared' connections, NetworkManager will start a DHCP and forwarding DNS server for the connection, and NAT it to the current default connection.
dns
ARRAY[UINT32]
optional; array of DNS servers in network byte order. If the "manual" key is not present, overrides any automatically detected (ie, DHCP) sett(ie, DHCP)ings
dns-search
ARRAY[STRING]
optional; array of search domains. If the "manual" key is not present, overrides any automatically detected (ie, DHCP) settings
addresses
ARRAY[UINT32,UINT32,(UINT32)]
optional; array of [IP Address, Netmask, optional gateway] in network byte order. If DHCP is used, addresses are applied _in addition_ to any automatically detected settings
routes
ARRAY[UINT32,UINT32,(UINT32)]
optional; array of [IP network, Netmask, optional gateway] in network byte order. If DHCP is used, routes are applied _in addition_ to any automatically detected settings
ignore-dhcp-dns
BOOLEAN
optional; if DHCP is used, setting this to TRUE causes NetworkManager to ignore any DNS information (nameservers and search domains) received from the DHCP server
dhcp-client-id
STRING
optional; a DHCP Client Identifier to send to the DHCP server when DHCP is used
dhcp-hostname
STRING
optional; a machine hostname to send to the DHCP server when DHCP is used; often used by the DHCP server to dynamically update DNS information when the machine obtains a lease. By default, NetworkManager sends the current hostname of the machine unless this option is present.