]>

NetworkManager 0.9 is a new major version of NetworkManager that breaks both API and ABI compared to previous versions. These changes are intended to make communication with NetworkManager much simpler, especially for network control and configuration programs. Thankfully, most changes are not difficult to implement, and the advantages of the simpler architecture of NetworkManager 0.9 greatly outweight the effort of updating client programs.

This section details the architectural and D-Bus API changes in NetworkManager 0.9.

Previously there were two "settings services", or D-Bus services that provided and saved network configuration information. NetworkManager owned the "system" settings service, and one user-level applet owned the "user" settings service. Now, the "user" settings service has been eliminated, so clients only have to track one D-Bus service to read and update network configuration. The functionality of the old user settings service has been replaced with a "permissions" key on each connection object to preserve the ability to restrict which users can use the connection, and with a "secret agent" D-Bus API for user-session-level secure storage of network secrets and passwords. Elimination of the user settings service provides the following advantages for clients of NetworkManager: Simpler discovery of network configuration and change tracking Simpler storage of user-level network secrets by control applets Correct operation of fast-user switching and multi-seat configurations More granular network connection permissions for system administrators Connections are now system-wide by default (unless restricted by the user or system administrator) Easier deployment of user-specific connections (ie, VPNs) Action: if you develop a network control applet that talks to NetworkManager and used to provide a user settings service, you can eliminate that code and rely on NetworkManager for all storage of network configuration. Your applet should now implement the Secret Agent D-Bus API (see below) to store user-specific secrets, and add legacy user-specific configuration to NetworkManager when run. More information about both these changes follows.

With the elimination of the user settings service, the old org.freedesktop.NetworkManagerUserSettings and org.freedesktop.NetworkManagerSystemSettings D-Bus service names are no longer used. Instead NetworkManager provides the settings service using its own D-Bus service name, org.freedesktop.NetworkManager. The object path of the settings service remains unchanged. Action: change the service name that your application uses to request system network settings to org.freedesktop.NetworkManager.

Previously there were two D-Bus method calls to retrieve the list of operations that a user client could perform, and two signals notifying callers that they should recheck permissions. Those two calls were: org.freedesktop.NetworkManagerSettings.System.GetPermissions which returned a bitfield of operations the caller was allowed to perform related to modify system network settings and the machine hostname org.freedesktop.NetworkManager.GetPermissions which returned a dictionary mapping permission names to result strings like "yes", "auth", or "no", relating to network control permissions like the ability to enable or disable WiFi. These two calls have been consolidated into an enhanced org.freedesktop.NetworkManager.GetPermissions call that uses the same arguments, but includes all permissions, including those which the settings service used to handle. With this change, the bitfield items from org.freedesktop.NetworkManagerSettings.System.GetPermissions are now string-based permissions. The mapping is as follows: Old bitfield valueNew permission name 0x1 (connection-modify) org.freedesktop.NetworkManager.settings.modify.system or org.freedesktop.NetworkManager.settings.modify.system depending on the permissions of the connection. 0x2 (wifi-share-protected) org.freedesktop.NetworkManager.wifi.share.protected 0x4 (wifi-share-open) org.freedesktop.NetworkManager.wifi.share.open 0x8 (hostname-modify) org.freedesktop.NetworkManager.settings.modify.hostname Action: modify handling of existing code that checks permissions to recognize the new permissions names for old system settings permissions, and remove code that used to call org.freedesktop.NetworkManagerSettings.System.GetPermissions.