NetworkManagerConfiguration has a good overview of settings services in general. "System settings" is the name of the D-Bus service (using the bus name org.freedesktop.NetworkManagerSystemSettings) that provides system-wide configuration data to NetworkManager. In NM 0.7, this service is implemented in a separate process (nm-system-settings) while in NM 0.8 the service is built into NetworkManager itself. The system settings service implements the org.freedesktop.NetworkManagerSettings and the org.freedesktop.NetworkManagerSystemSettings D-Bus interfaces.
System settings are stored in a system-wide location (typically somewhere in /etc) and are available at boot time, before login, and to all users of the machine. To accomplish this, and to provide a good level of integration with various distribution-specific configuration systems that users are already familiar with, the system settings service relies on "system settings plugins" to read and write the distros native configuration file format.
By default, the system settings service is configured through the /etc/NetworkManager/nm-system-settings.conf (NM 0.7 and 0.8.0) or /etc/NetworkManager/NetworkManager.conf (NM 0.8.1 and later) file, which may be changed through use of the "--config=" argument for either nm-system-settings (NM 0.7) or NetworkManager (NM 0.8). This file must contain a "[main]" section that has at least one configuration option: "plugins". So a minimal system settings configuration file looks like this:
Multiple plugins may be specified in a preference order using ',' as a separator (ie, "plugins=ifcfg-rh,keyfile") to allow more than one plugin to be used. This will cause connections to be read from all listed plugins. In the previous example ("plugins=ifcfg-rh,keyfile") both standard ifcfg files from /etc/sysconfig/network-scripts and keyfile connections from /etc/NetworkManager/system-connections would be read and used. When creating new connections, or making a user-settings connection into a system-settings connection, 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. If none of the plugins can save the connection, the error is returned to the user.
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 settings specifications (0.7 0.8). 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 timestamp=0 [ipv4] method=auto [802-3-ethernet] mac-address=0:23:5a:47:1f:71
NOTE: since SSIDs may contain embedded NULLs, they must be specified as byte arrays (ie, "ssid=102;111;111;98;97;114;").
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 the system settings service configuration file:
It is not necessary to restart NetworkManager or nm-system-settings when making these changes, as the configuration files are watched for changes and reloaded when necessary.
The keyfile plugin uses the nm-system-settings.conf file (0.7 and 0.8.0) or NetworkManager.conf (0.8.1 and later) for configuration of unmanaged devices. To set devices that should be ignored by NetworkManager, list them in "unmanaged-devices" key in "[keyfile]" section. Devices are specified in the following format: "mac:<hwaddr>", where <hwaddr> is MAC address of the device in hex-digits-and-colons notation. Multiple entries are separated by semicolons. No spaces are allowed in the value. The configuration could look like this:
At this time, the keyfile plugin won't give you much feedback about what its doing or why configuration failed to validate. We hope to fix this soon.
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 wired, wifi, and 802.1x connections, but does not support reading or writing mobile broadband, PPPoE, or VPN connections. To allow reading and writing of these until the ifcfg-rh plugin is updated, add ",keyfile" to your "plugins=" line in /etc/NetworkManager/nm-system-settings.conf (0.7 and 0.8.0) or NetworkManager.conf (0.8.1 and later). In NM 0.7, the ifcfg-rh plugin does not support IPv6. Full IPv6 support is being added for NM 0.8 and will be finished by NM 0.8.1.
The persistent machine hostname is pulled from /etc/sysconfig/network's HOSTNAME variable.
In order for a device to be ignored by NetworkManager, it has to be marked such in its ifcfg-* file. The indication is done by NM_CONTROLLED variable, but you must also specify the device's HWADDR:
The plugin does not yet support interface "aliases" (ie, eth0:1). This is a legacy configuration mechanism from the days when /sbin/ip and netlink didn't exist. ifcfg-rh will support reading alias files in the future, but as the alias style is deprecated write support will not be added. 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
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=220.127.116.11 DNS2=18.104.22.168 DOMAIN=foobar.com
This will ensure that the nameservers are correct every time for static IP configurations.
In NM 0.8, the ifcfg-rh plugin has the ability to read preconfigured iSCSI connections. You must have a valid iSCSI ifcfg in /etc/sysconfig/network-scripts like the following:
# Intel Corporation 82540EP Gigabit Ethernet Controller (Mobile) DEVICE=eth0 HWADDR=00:33:21:98:b9:f1 BOOTPROTO=ibft
ifcfg-rh will then query the iscsiadm tool to retrieve firmware settings for your iSCSI adapter and use those when bringing up the device.
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.
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.
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.
The ifupdown plugin also uses the /etc/NetworkManager/nm-system-settings.conf file (0.7 and 0.8.0) or NetworkManager.conf (0.8.1 and later) 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.
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.
User Settings and System Settings
The user settings will be stored here.
The System settings will be stored here.