NetworkManager.conf: NetworkManager D-Bus API Reference Manual

+

Description

+

NetworkManager.conf is the configuration file for NetworkManager. It is used + to set up various aspects of NetworkManager's behavior. The + location of the main file and configuration directories may be changed + through use of the --config, --config-dir, + --system-config-dir, and --intern-config + argument for NetworkManager, respectively. +

+

If a default NetworkManager.conf is + provided by your distribution's packages, you should not modify + it, since your changes may get overwritten by package + updates. Instead, you can add additional .conf + files to the /etc/NetworkManager/conf.d directory. + These will be read in order, with later files overriding earlier ones. + Packages might install further configuration snippets to /usr/lib/NetworkManager/conf.d. + This directory is parsed first, even before NetworkManager.conf. + The loading of a file /usr/lib/NetworkManager/conf.d/name.conf + can be prevented by adding a file /etc/NetworkManager/conf.d/name.conf. + In this case, the file from the etc configuration shadows the file from the + system configuration directory. +

+

+ NetworkManager can overwrite certain user configuration options via D-Bus or other internal + operations. In this case it writes those changes to /var/lib/NetworkManager/NetworkManager-intern.conf. + This file is not intended to be modified by the user, but it is read last and can shadow + user configuration from NetworkManager.conf. +

+

File Format

+

+ The configuration file format is so-called key file (sort of + ini-style format). It consists of sections (groups) of + key-value pairs. Lines beginning with a '#' and blank lines are + considered comments. Sections are started by a header line + containing the section enclosed in '[' and ']', and ended + implicitly by the start of the next section or the end of the + file. Each key-value pair must be contained in a section. +

+

+ For keys that take a list of devices as their value, you can + specify devices by their MAC addresses or interface names, or + "*" to specify all devices. See the section called “Device List Format” + below. +

+

+ Minimal system settings configuration file looks like this: +

+

+[main]
+plugins=keyfile
+

+

+ As an extension to the normal keyfile format, you can also + append a value to a previously-set list-valued key by doing: +

+

+plugins+=another-plugin
+plugins-=remove-me
+

+

+`main` section

+

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`plugins`	+ + Lists system settings plugin names separated by ','. These + plugins are used to read and write system-wide + connections. When multiple plugins are specified, the + connections are read from all listed plugins. When writing + connections, the plugins will be asked to save the + connection in the order listed here; if the first plugin + cannot write out that connection type (or can't write out + any connections) the next plugin is tried, etc. If none of + the plugins can save the connection, an error is returned + to the user. + + + If NetworkManager defines a distro-specific + network-configuration plugin for your system, then that + will normally be listed here. (See below for the available + plugins.) Note that the `keyfile` plugin + is always appended to the end of this list (if it doesn't + already appear earlier in the list), so if there is no + distro-specific plugin for your system then you can leave + this key unset and NetworkManager will fall back to using + `keyfile`. + +
`monitor-connection-files`	Whether the configured settings plugin(s) + should set up file monitors and immediately pick up changes + made to connection files while NetworkManager is running. This + is disabled by default; NetworkManager will only read + the connection files at startup, and when explicitly requested + via the ReloadConnections D-Bus call. If this key is set to + '`true`', then NetworkManager will reload + connection files any time they changed.
`auth-polkit`	Whether the system uses PolicyKit for authorization. + If `false`, all requests will be allowed. If + `true`, non-root requests are authorized using PolicyKit. + The default value is `true`. +
`dhcp`	+ This key sets up what DHCP client + NetworkManager will use. Allowed values are + `dhclient`, `dhcpcd`, and + `internal`. The `dhclient` + and `dhcpcd` options require the indicated + clients to be installed. The `internal` + option uses a built-in DHCP client which is not currently as + featureful as the external clients. + If this key is missing, available DHCP clients are + looked for in this order: `dhclient`, + `dhcpcd`, + `internal`. +
`no-auto-default`	+ Specify devices for which + NetworkManager shouldn't create default wired connection + (Auto eth0). By default, NetworkManager creates a temporary + wired connection for any Ethernet device that is managed and + doesn't have a connection configured. List a device in this + option to inhibit creating the default connection for the + device. May have the special value `` to + apply to all devices. + When the default wired connection is deleted or saved + to a new persistent connection by a plugin, the device is + added to a list in the file + `/var/run/NetworkManager/no-auto-default.state` + to prevent creating the default connection for that device + again. + See the section called “Device List Format” for the syntax how to + specify a device. + + + Example: + + +no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee +no-auto-default=eth0,eth1 +no-auto-default= + + + +
`ignore-carrier`	+ + Specify devices for which NetworkManager will (partially) + ignore the carrier state. Normally, for + device types that support carrier-detect, such as Ethernet + and InfiniBand, NetworkManager will only allow a + connection to be activated on the device if carrier is + present (ie, a cable is plugged in), and it will + deactivate the device if carrier drops for more than a few + seconds. + + + Listing a device here will allow activating connections on + that device even when it does not have carrier, provided + that the connection uses only statically-configured IP + addresses. Additionally, it will allow any active + connection (whether static or dynamic) to remain active on + the device when carrier is lost. + + + Note that the "carrier" property of NMDevices and device D-Bus + interfaces will still reflect the actual device state; it's just + that NetworkManager will not make use of that information. + + See the section called “Device List Format” for the syntax how to + specify a device. + +
`assume-ipv6ll-only`	+ + Specify devices for which NetworkManager will try to + generate a connection based on initial configuration when + the device only has an IPv6 link-local address. + + See the section called “Device List Format” for the syntax how to + specify a device. + +
`configure-and-quit`	+ When set to '`true`', NetworkManager quits after + performing initial network configuration but spawns small helpers + to preserve DHCP leases and IPv6 addresses. This is useful in + environments where network setup is more or less static or it is + desirable to save process time but still handle some dynamic + configurations. When this option is `true`, + network configuration for WiFi, WWAN, Bluetooth, ADSL, and PPPoE + interfaces cannot be preserved due to their use of external + services, and these devices will be deconfigured when NetworkManager + quits even though other interface's configuration may be preserved. + Also, to preserve DHCP addresses the '`dhcp`' option + must be set to '`internal`'. The default value of + the '`configure-and-quit`' option is + '`false`', meaning that NetworkManager will continue + running after initial network configuration and continue responding + to system and hardware events, D-Bus requests, and user commands. +
`dns`	+ Set the DNS (`resolv.conf`) processing mode. + `default`: The default if the key is + not specified. NetworkManager will update + `resolv.conf` to reflect the nameservers + provided by currently active connections. + `dnsmasq`: NetworkManager will run + dnsmasq as a local caching nameserver, using a "split DNS" + configuration if you are connected to a VPN, and then update + `resolv.conf` to point to the local + nameserver. + `unbound`: NetworkManager will talk + to unbound and dnssec-triggerd, providing a "split DNS" + configuration with DNSSEC support. The /etc/resolv.conf + will be managed by dnssec-trigger daemon. + `none`: NetworkManager will not + modify resolv.conf. +
`rc-manager`	+ Set the `resolv.conf` + management mode. The default value depends on how NetworkManager + was built. Regardless of this setting, NetworkManager will + always write resolv.conf to its runtime state directory. + `none`: NetworkManager will symlink + `/etc/resolv.conf` to its private + resolv.conf file in the runtime state directory. + `file`: NetworkManager will write + `/etc/resolv.conf` as file. + `resolvconf`: NetworkManager will run + resolvconf to update the DNS configuration. + `netconfig`: NetworkManager will run + netconfig to update the DNS configuration. +
`debug`	+ Comma separated list of options to aid + debugging. This value will be combined with the environment + variable `NM_DEBUG`. Currently the following + values are supported: + + `RLIMIT_CORE`: set ulimit -c unlimited + to write out core dumps. Beware, that a core dump can contain + sensitive information such as passwords or configuration settings. + + + `fatal-warnings`: set `g_log_set_always_fatal()` + to core dump on warning messages from glib. This is equivalent + to the --g-fatal-warnings command line option. + +

+

+`keyfile` section

+

This section contains keyfile-plugin-specific options, and + is normally only used when you are not using any other + distro-specific plugin.

+

++++ + + + + + + + + + + + + + + +

hostname

This key is deprecated and has no effect + since the hostname is now stored in /etc/hostname or other + system configuration files according to build options. +

path

The location where keyfiles are read and stored. + This defaults to "/usr/local/etc/NetworkManager/conf.d". +

unmanaged-devices

+

Set devices that should be ignored by + NetworkManager. +

+

See the section called “Device List Format” for the syntax how to + specify a device. +

+

+ Example: +

+

+unmanaged-devices=interface-name:em4
+unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
+

+

+`ifupdown` section

+

This section contains ifupdown-specific options and thus only + has effect when using the ifupdown plugin.

+

++++ + + + + +

managed

+

If set to true, then + interfaces listed in + /etc/network/interfaces are managed by + NetworkManager. If set to false, then + any interface listed in + /etc/network/interfaces will be ignored + by NetworkManager. Remember that NetworkManager controls the + default route, so because the interface is ignored, + NetworkManager may assign the default route to some other + interface.

+

+ The default value is false. +

+

+`logging` section

+

This section controls NetworkManager's logging. Any + settings here are overridden by the --log-level + and --log-domains command-line options.

+

++++ + + + + + + + + + + + + + + + + + + + + + + +

`level`	The default logging verbosity level. + One of `OFF`, `ERR`, + `WARN`, `INFO`, + `DEBUG`, `TRACE`. The ERR + level logs only critical errors. WARN logs warnings that may + reflect operation. INFO logs various informational messages that + are useful for tracking state and operations. DEBUG enables + verbose logging for debugging purposes. TRACE enables even more + verbose logging then DEBUG level. Subsequent levels also log + all messages from earlier levels; thus setting the log level + to INFO also logs error and warning messages.
`domains`	+ The following log domains are available: + PLATFORM, RFKILL, ETHER, WIFI, BT, MB, DHCP4, DHCP6, PPP, + WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT, + AGENTS, SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX, + INFINIBAND, FIREWALL, ADSL, BOND, VLAN, BRIDGE, DBUS_PROPS, + TEAM, CONCHECK, DCB, DISPATCH, AUDIT. + In addition, these special domains can be used: NONE, + ALL, DEFAULT, DHCP, IP. + You can specify per-domain log level overrides by + adding a colon and a log level to any domain. E.g., + "`WIFI:DEBUG,WIFI_SCAN:OFF`". +

`backend`	The logging backend. Supported values + are "`debug`", "`syslog`", + "`journal`". + "`debug`" uses syslog and logs to standard error. + If NetworkManager is started in debug mode (`--debug`) + this option is ignored and "`debug`" is always used. + Otherwise, the default is "`journal`". +
`audit`	Whether the audit records are delivered to + auditd, the audit daemon. If `false`, audit + records will be sent only to the NetworkManager logging + system. If set to `true`, they will be also + sent to auditd. The default value is `true`. +

+

+`connection` section

+

Specify default values for connections. +

+

+ Example: +

+

+[connection]
+ipv6.ip6-privacy=0
+

+

Supported Properties

+

+ Not all properties can be overwritten, only the following + properties are supported to have their default values configured + (see nm-settings(5) for details). + A default value is only consulted if the corresponding per-connection value + explicitly allows for that. +

+

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`connection.autoconnect-slaves`
`connection.lldp`
`ethernet.wake-on-lan`
`ipv4.dad-timeout`
`ipv4.dhcp-timeout`	If left unspecified, the default value for + the interface type is used.
`ipv4.route-metric`
`ipv6.ip6-privacy`	If `ipv6.ip6-privacy` is unset, use the content of + "/proc/sys/net/ipv6/conf/default/use_tempaddr" as last fallback. +
`ipv6.route-metric`
`vpn.timeout`	If left unspecified, default value of 60 seconds is used.
`wifi.mac-address-randomization`	If left unspecified, MAC address randomization is disabled.
`wifi.powersave`	If left unspecified, the default value + "`ignore`" will be used.

+

Sections

+

+ You can configure multiple connection + sections, by having different sections with a name that all start + with "connection". + Example: +

+

+[connection]
+ipv6.ip6-privacy=0
+connection.autoconnect-slaves=1
+vpn.timeout=120
+
+[connection-wifi-wlan0]
+match-device=interface-name:wlan0
+ipv4.route-metric=50
+
+[connection-wifi-other]
+match-device=type:wifi
+ipv4.route-metric=55
+ipv6.ip6-privacy=1
+

+

+ The sections within one file are considered in order of appearance, with the + exception that the [connection] section is always + considered last. In the example above, this order is [connection-wifi-wlan0], + [connection-wlan-other], and [connection]. + When checking for a default configuration value, the sections are searched until + the requested value is found. + In the example above, "ipv4.route-metric" for wlan0 interface is set to 50, + and for all other Wi-Fi typed interfaces to 55. Also, Wi-Fi devices would have + IPv6 private addresses enabled by default, but other devices would have it disabled. + Note that also "wlan0" gets "ipv6.ip6-privacy=1", because although the section + "[connection-wifi-wlan0]" matches the device, it does not contain that property + and the search continues. +

+

+ When having different sections in multiple files, sections from files that are read + later have higher priority. So within one file the priority of the sections is + top-to-bottom. Across multiple files later definitions take precedence. +

+

+ The following properties further control how a connection section applies. +

+

++++ + + + + + + + + + + +

`match-device`	An optional device spec that restricts + when the section applies. See the section called “Device List Format” + for the possible values. +
`stop-match`	An optional boolean value which defaults to + `no`. If the section matches (based on + `match-device`), further sections will not be + considered even if the property in question is not present. In + the example above, if `[connection-wifi-wlan0]` would + have `stop-match` set to `yes`, + its `ipv6.ip6-privacy` value would be + unspecified. +

+

+`connectivity` section

+

This section controls NetworkManager's optional connectivity + checking functionality. This allows NetworkManager to detect + whether or not the system can actually access the internet or + whether it is behind a captive portal.

+

++++ + + + + + + + + + + + + + + +

`uri`	The URI of a web page to periodically + request when connectivity is being checked. This page + should return the header "X-NetworkManager-Status" with a + value of "online". Alternatively, it's body content should + be set to "NetworkManager is online". The body content + check can be controlled by the `response` + option. If this option is blank or missing, connectivity + checking is disabled. +
`interval`	Specified in seconds; controls how often + connectivity is checked when a network connection exists. If + set to 0 connectivity checking is disabled. If missing, the + default is 300 seconds.
`response`	If set controls what body content + NetworkManager checks for when requesting the URI for + connectivity checking. If missing, defaults to + "NetworkManager is online"

+

+`global-dns` section

+

This section specifies global DNS settings that override + connection-specific configuration.

+

++++ + + + + + + + + + + +

`searches`	+ A list of search domains to be used during hostname lookup. +
`options`	+ A list of of options to be passed to the hostname resolver. +

+

+`global-dns-domain` sections

+

Sections with a name starting with the "global-dns-domain-" + prefix allow to define global DNS configuration for specific + domains. The part of section name after "global-dns-domain-" + specifies the domain name a section applies to. More specific + domains have the precedence over less specific ones and the + default domain is represented by the wildcard "*". A default + domain section is mandatory. +

+

++++ + + + + + + + + + + +

`servers`	+ A list of addresses of DNS servers to be used for the given domain. +
`options`	+ A list of domain-specific DNS options. Not used at the moment. +

+

+`.config` sections

+

This is a special section that contains options which apply + to the configuration file that contains the option. +

+

++++ + + + + +

enable

+

+ Defaults to "true". If "false", + the configuration file will be skipped during loading. + Note that the main configuration file NetworkManager.conf + cannot be disabled. +

+

+# always skip loading the config file
+[.config]
+enable=false
+

+

+ You can also match against the version of NetworkManager. For example + the following are valid configurations: +

+

+# only load on version 1.0.6
+[.config]
+enable=nm-version:1.0.6
+
+# load on all versions 1.0.x, but not 1.2.x
+[.config]
+enable=nm-version:1.0
+
+# only load on versions >= 1.1.6. This does not match
+# with version 1.2.0 or 1.4.4. Only the last digit is considered.
+[.config]
+enable=nm-version-min:1.1.6
+
+# only load on versions >= 1.2. Contrary to the previous
+# example, this also matches with 1.2.0, 1.2.10, 1.4.4, etc.
+[.config]
+enable=nm-version-min:1.2
+
+# Match against the maximum allowed version. The example matches
+# versions 1.2.0, 1.2.2, 1.2.4. Again, only the last version digit
+# is allowed to be smaller. So this would not match match on 1.1.10.
+[.config]
+enable=nm-version-max:1.2.6
+

+

+ You can also match against the value of the environment variable + NM_CONFIG_ENABLE_TAG, like: +

+

+# always skip loading the file when running NetworkManager with
+# environment variable "NM_CONFIG_ENABLE_TAG=TAG1"
+[.config]
+enable=env:TAG1
+

+

+ More then one match can be specified. The configuration will be + enabled if one of the predicates matches ("or"). The special prefix "except:" can + be used to negate the match. Note that if one except-predicate + matches, the entire configuration will be disabled. + In other words, a except predicate always wins over other predicates. +

+

+# enable the configuration either when the environment variable
+# is present or the version is at least 1.2.0.
+[.config]
+enable=env:TAG2,nm-version-min:1.2
+
+# enable the configuration for version >= 1.2.0, but disable
+# it when the environment variable is set to "TAG3"
+[.config]
+enable=except:env:TAG3,nm-version-min:1.2
+
+# enable the configuration on >= 1.3, >= 1.2.6, and >= 1.0.16.
+# Useful if a certain feature is only present since those releases.
+[.config]
+enable=nm-version-min:1.3,nm-version-min:1.2.6,nm-version-min:1.0.16
+

+

Plugins

+

++++ + + + + + + + + + + + + + + + + + + + + + + +

`keyfile`	+ + The `keyfile` plugin is the generic + plugin that supports all the connection types and + capabilities that NetworkManager has. It writes files out + in an .ini-style format in + /etc/NetworkManager/system-connections. + + + The stored connection file may contain passwords and + private keys, so it will be made readable only to root, + and the plugin will ignore files that are readable or + writable by any user or group other than root. + + + This plugin is always active, and will automatically be + used to store any connections that aren't supported by any + other active plugin. + +
`ifcfg-rh`	+ This plugin is used on the Fedora and Red Hat Enterprise + Linux distributions to read and write configuration from + the standard + `/etc/sysconfig/network-scripts/ifcfg-*` + files. It currently supports reading Ethernet, Wi-Fi, + InfiniBand, VLAN, Bond, Bridge, and Team connections. + Enabling `ifcfg-rh` implicitly enables + `ibft` plugin, if it is available. + This can be disabled by adding `no-ibft`. +
`ifcfg-suse`	+ This plugin is deprecated and its selection has no effect. + The `keyfile` plugin should be used + instead. +
`ifupdown`	+ + This plugin is used on the Debian and Ubuntu + distributions, and reads Ethernet and Wi-Fi connections + from `/etc/network/interfaces`. + + + This plugin is read-only; any connections (of any type) + added from within NetworkManager when you are using this + plugin will be saved using the `keyfile` + plugin instead. + +
`ibft`, `no-ibft`	+ This plugin allows to read iBFT configuration (iSCSI Boot Firmware Table). + The configuration is read using /sbin/iscsiadm. Users are expected to + configure iBFT connections via the firmware interfaces. + If ibft support is available, it is automatically enabled after + `ifcfg-rh`. This can be disabled by `no-ibft`. + You can also explicitly specify `ibft` to load the + plugin without `ifcfg-rh` or to change the plugin order. +

+

Appendix

+

Device List Format

+

+ The configuration options main.no-auto-default, main.ignore-carrier, + and keyfile.unmanaged-devices select devices based on a list of matchings. + Devices can be specified using the following format: +

+

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*	Matches every device.
IFNAME	Case sensitive match of interface name of the device. Globbing is not supported.
HWADDR	Match the MAC address of the device. Globbing is not supported
interface-name:IFNAME, interface-name:~IFNAME	Case sensitive match of interface name of the device. Simple globbing is supported with + `*` and `?`. Ranges and escaping is not supported.
interface-name:=IFNAME	Case sensitive match of interface name of the device. Globbing is disabled and `IFNAME` + is taken literally.
mac:HWADDR	Match the MAC address of the device. Globbing is not supported
s390-subchannels:HWADDR	Match the device based on the subchannel address. Globbing is not supported
type:TYPE	Match the device type. Valid type names are as reported by "`nmcli -f GENERAL.TYPE device show`". + Globbing is not supported.
except:SPEC	Negative match of a device. `SPEC` must be explicitly qualified with + a prefix such as `interface-name:`. A negative match has higher priority then the positive + matches above.
SPEC[,;]SPEC	+ Multiple specs can be concatenated with commas or semicolons. The order does not matter as + matches are either inclusive or negative (`except:`), with negative matches having higher + priority. + + Backslash is supported to escape the separators ';' and ',', and to express special + characters such as newline ('\n'), tabulator ('\t'), whitespace ('\s') and backslash ('\\'). The globbing of + interface names cannot be escaped. Whitespace is not a separator but will be trimmed between + two specs (unless escaped as '\s'). + +

+

+ Example: +

+

+interface-name:em4
+mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
+interface-name:vboxnet*,except:interface-name:vboxnet2
+*,except:mac:00:22:68:1c:59:b1
+

+