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. |