Configuration Plugins

NetworkManager tries to read and write your distribution's normal network configuration files through plugins called "system settings plugins". These plugins allow you to use the file formats you're already comfortable with and the tools you already know how to use to manage your network configuration. You can use NetworkManager's D-Bus interface too.

A generic plugin called 'keyfile' is also provided to read and write configuration that your distro's native file format cannot handle.

These plugins are configured through the /etc/NetworkManager/NetworkManager.conf configuration file. Since the 'keyfile' plugin is built-in, if all you want is the generic NetworkManager configuration file format, you don't need to do anything. But if you'd like to have NetworkManager read and write your distro's normal network configuration files, you might need to enable that plugin if the distribution hasn't done that for you already.

You can read more details of these plugins in the NetworkManager.conf(5) manual page.

To enable/disable a plugin, add or remove it from the "plugins" line of /etc/NetworkManager/NetworkManager.conf and restart NetworkManager:

[main]
plugins=ifupdown

Reloading configuration

When changes are made to network configuration outside of NetworkManager, by editing the configuration directly or adding/removing configuration files from scripts, the command:

nmcli con reload

should be called to ensure NetworkManager is aware of the changes. Alternatively, the configuration option "monitor-connection-files" should be set to "true" in the [main] section of NetworkManager.conf.

Plugins

keyfile

The keyfile plugin is documented in nm-settings-keyfile(5) manual page.

The 'keyfile' plugin is the generic plugin that supports all the connection types and capabilities that NM has. It writes files out in a .ini-style format in /etc/NetworkManager/system-connections/. For security, it will ignore files that are readable or writeable by any user or group other than 'root' since private keys and passphrases may be stored in plaintext inside the file.

The keyfile config format is a simple .ini-style format with each section corresponding to a setting name as described in the nm-settings(5) manual page. Each configuration key/value pair in the section is one of the keys listed in the settings specification. If the specification says the value type is "string" then the keyfile value type should be a string; if it's "byte array" the keyfile value type should be a list of hexadecimal-formatted bytes separated by semicolon (';'). MAC addresses may be written as textual MAC addresses (ie, "00:11:22:33:44:55"). Some values are inconvenient for people to use and it is expected that these will be fixed to be more useful in the near future.

A sample keyfile configuration for a wired network is:

[connection]
id=Auto eth0
uuid=27afa607-ee36-43f0-b8c3-9d245cdc4bb3
type=802-3-ethernet
autoconnect=true

[ipv4]
method=auto

[802-3-ethernet]
mac-address=0:23:5a:47:1f:71

Persistent Hostname

The keyfile plugin pulls the system persistent hostname from the system settings service configuration file from the "[keyfile]" section. To set a persistent hostname when using the keyfile plugin, add the following block to NetworkManager.conf:

[keyfile]
hostname=myhostname

ifcfg-rh

The ifcfg-rh plugin is documented in nm-settings-ifcfg-rh(5) manual page.

The 'ifcfg-rh' plugin is used on Fedora and Red Hat Enterprise Linux distributions to read and write configuration from the standard /etc/sysconfig/network-scripts/ifcfg-* files. It current supports reading ethernet, WiFi, 802.1x, bridge, bond, VLAN, IP alias, and InfiniBand-over-IP connections, but does not support reading or writing WWAN, PPPoE, VPN, or ADSL connections.

As of NetworkManager 1.0, iBFT/iSCSI has been moved to a separate 'ibft' plugin, and minimal BOOTPROTO=ibft ifcfg files are no longer required.

Persistent Hostname

The persistent machine hostname is pulled from /etc/hostname and falls back to /etc/sysconfig/network's HOSTNAME variable if that the hostname file is not present.

Device Aliases

The ifcfg-rh plugin supports reading interface "aliases" (ie, eth0:1), but we do not recommend using this format. This is a legacy configuration mechanism from the days when /sbin/ip and netlink didn't exist. Instead, put all IP addresses and prefixes into the main ifcfg file like so:

IPADDR=192.168.0.2
PREFIX=24
GATEWAY=192.168.0.1
IPADDR2=10.0.0.25
PREFIX2=8

Nameservers

Many users run into problem with resolv.conf not showing the proper nameservers with ifcfg-rh. Because /etc/resolv.conf must be reconstructed every time a connection is activated or deactivated as DNS information changes depending on the active connection, static nameservers should be added to the specific ifcfg file they are for like so:

DNS1=4.2.2.1
DNS2=4.2.2.2
DOMAIN=foobar.com

This will ensure that the nameservers are correct every time for static IP configurations.

Logging

In general, the ifcfg-rh plugin is pretty good about logging what it's doing, including why various ifcfg files may fail validation and thus be ignored. Check /var/log/messages when NetworkManager starts up for more information. You'll see output like:

NetworkManager:    ifcfg-rh: parsing /etc/sysconfig/network-scripts/ifcfg-Auto_eth0 ...
NetworkManager:    ifcfg-rh:     read connection 'Auto eth0'
NetworkManager:    ifcfg-rh: parsing /etc/sysconfig/network-scripts/ifcfg-Test_LEAP ...
NetworkManager:    ifcfg-rh:     error: Missing LEAP identity
NetworkManager:    ifcfg-rh: parsing /etc/sysconfig/network-scripts/ifcfg-Test_Wifi_LEAP ...
NetworkManager:    ifcfg-rh:     read connection 'Test Wifi LEAP'
NetworkManager:    ifcfg-rh: parsing /etc/sysconfig/network-scripts/ifcfg-wlan0 ...
NetworkManager:    ifcfg-rh:     read connection 'System wlan0'

In this case, one file failed to validate because it was missing the LEAP username.

iBFT (iSCSI)

For NetworkManager 1.0, a new 'ibft' plugin has been added. This plugin queries the 'iscsiadm' tool and generates connections based on the firmware configuration. This plugin is read-only; to change the iSCSI/iBFT configuration you must edit the settings in the machine's firmware.

This plugin must be enabled through NetworkManager.conf or through a configuration snippet in /etc/NetworkManager/conf.d/.

ifupdown

This plugin is used on the Debian and Ubuntu distributions, and reads connections from /etc/network/interfaces. Since it cannot write connections out (that support isn't planned) it is usually paired with the 'keyfile' plugin to enabled saving and editing of new connections. The ifupdown plugin supports basic wired and wifi connections, including WPA-PSK.

Persistent Hostname

As the standard location for the persistent system hostname on Debian-base distributions is /etc/hostname, the ifupdown plugin reads the hostname from that location.

Unmanaged Devices

The ifupdown plugin also uses the /etc/NetworkManager/NetworkManager.conf for some configuration. All ifupdown-specific options go in a "[ifupdown]" section. If the "managed" key is set to "false", then any device listed in /etc/network/interfaces will be completely ignored by NetworkManager. Remember that NetworkManager controls the default route, so because the device is hidden, NetworkManager will assign the default route to some other device.

ifcfg-suse

The ifcfg-suse plugin is only provided for simple backward compatibility with SUSE and openSUSE configuration. Most setups should be using the 'keyfile' plugin instead. The ifcfg-suse plugins supports reading wired and wifi connections, but does not support saving any connection types.