This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

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.
2024-10-23 10:59