Settings Services

Configuration is provided to NetworkManager and client applications by D-Bus services called "settings services", of which there are two: User and System. The settings service stores the configuration in any way it sees fit; for example the Gnome applet reference implementation (nm-applet) uses GConf, and the system reference implementation built into NetworkManager uses distro-dependent plugins to read and store configuration in the distros native file formats.

The User settings service runs in the users session and is often the same process as the GUI network control applet, though it does not have to be. It provides user-defined configuration to NetworkManager via the org.freedesktop.NetworkManagerUserSettings D-Bus service. User connections are *only* available to the specified user and are not visible to other users on the same machine.

The System settings service is privileged and runs as root, because it must access and update system-wide network configuration. It provides configuration to NetworkManager and client applications via the org.freedesktop.NetworkManagerSystemSettings D-Bus service. The connections provided by the system settings service are available to all users, and are usable at boot time before any user has logged in. System connections take precedence over any available user connection. In NetworkManager 0.7, the system settings service is an external process called nm-system-settings. In NetworkManager 0.8, nm-system-settings has been integrated into the NetworkManager core daemon.

Conceptual Objects

Device: A hardware device that is the immediate provider of network connectivity. Wireless card, bluetooth dongle, serial modem, PCI ethernet card, USB wireless or ethernet card, etc. Devices are classified into different "types", ie 802.11 wifi, ethernet, bluetooth, etc.

Connection: a specific, encapsulated, independent group of settings describing all the configuration required to connect to a specific network. Referred to by a unique identifier called the UUID. A connection is tied to a one specific Device type, but not necessarily a specific hardware device. It is composed of one or more Settings objects.

Setting: a group of related key/value pairs describing a specific piece of a Connection. Settings keys and allowed values are currently best described by the code documentation for each of the settings objects in the libnm-util sources. Look for the "class_init" functions near the bottoms of each setting source file.

Conceptual Diagram

  - 0 (Connection)
    |
    |- connection (Setting)
    |   |- name: 'nifty-wireless'
    |   |- uuid: 'c78e4e9d-25b2-4c2c-9227-fdf3e4b9e4f1'
    |   |- devtype: '802-11-wireless'
    |   `- autoconnect: True
    |
    |- 802-11-wireless (Setting)
    |   |- ssid: 'nifty-wireless'
    |   |- mode: 'infrastructure'
    |   `- seen-bssids: ['xx:xx:xx:xx:xx:xx', 'yy:yy:yy:yy:yy:yy']
    |
    |- 802-11-security-wpa (Setting)
    |   |- proto: 'WPA'
    |   |- key_mgmt: 'WPA-PSK'
    |   |- pariwise: ['TKIP', 'CCMP']
    |   |- group: ['TKIP', 'CCMP']
    |   `- psk: '9ad8da8a8da8f8dsa8...'
    |
    `- ip4 (Setting)
        |- dns: ['1.1.1.1', '1.1.1.2']
        `- dns-search: 'foobar.com'

- 1 (Connection)
    |
    |- connection (Setting)
    |   |- name: 'Work @ BigCorp'
    |   |- uuid: '9bad8110-aac8-44db-b2b0-17af4c78675d'
    |   `- devtype: '802-3-ethernet'
    |
    |- 802-3-ethernet (Setting)
    |   `- mtu: 1500
    |
    `- ip4 (Setting)
        |- address: 10.1.1.50
        |- netmask: 255.255.255.0
        |- gateway: 10.1.1.1
        |- dns: ['10.1.1.3', '10.1.1.4']
        |- dns-search: 'bigcorp.com'
        `- ypbind: ['1.1.1.3']

- 2 (Connection)
    |
    |- connection (Setting)
    |   |- name: 'Sprint PCS'
    |   |- uuid: '1cc9daab-957a-4c5e-b2bf-84dc2d7a3cc0'
    |   `- devtype: 'bluetooth'
    |
    `- bluetooth (Setting)
        |- type: 'panu'
        `- bdaddr: xx:xx:xx:xx:xx:xx

• Each Settings object has strictly defined key names and strictly defined value types for each key. When keys are not present, they assume a default value. For example, if static IP settings are unspecified in the 'ip4' Settings object, it is assumed that DHCP is used.

• NetworkManager request the connection objects from both settings services and performs validation on them. If a Settings object's key or values are invalid, the Settings object is rejected and not used by NetworkManager.

• The Connection's UUID should not be derived from the connection's name in any way and is randomly assigned by the settings service, but must be persistent for the lifetime of the connection. The UUID should never be used for another different connection.
• Connections are transported across D-Bus as a dict of Settings. Each Setting is itself another dict.

Administration and Privilege

NetworkManager uses PolicyKit to determine what specific users are authorized and permitted to do. Certain operations are available to be locked down, for example the ability to modify system connections from the connection editor, the ability to modify the machine's persistent hostname, and the ability to share the internet connection via wifi. These permissions, by default, are configured in the /usr/share/PolicyKit/policy/org.freedesktop.network-manager-settings.system.policy file; see PolicyKit documentation in the "DECLARING ACTIONS" section for more details on .policy files.

The reference Gnome UI implementation can also take advantage of GConf default and mandatory settings (example 1 and example 2) to lock down what connections users are able to use.