Migrating from NetworkManager 0.8 to NetworkManager 0.9

+Migrating from NetworkManager 0.8 to NetworkManager 0.9

Architecture and D-Bus API Changes in 0.9

Elimination of the User Settings Service
User Secret Agents
Settings Service Interface Changes
Connection Object Interface Changes
Permissions Methods Consolidation
AddConnection Returns Object Path of New Connection
Support for WiMAX Devices
New Device States
New Active Connection State
Consolidated Modem Devices
Secret Property Flags
Deprecated Methods Removed

+ 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. +

+Architecture and D-Bus API Changes in 0.9

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

+Elimination of the User Settings Service

+ 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)

+ With this change, D-Bus methods that previously took a "service name" + argument (like + org.freedesktop.NetworkManager.ActivateConnection) and + objects with service name properties (like ActiveConnection objects) no + longer have those arguments or properties. +

+ 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. +

+User Secret Agents

+ Even with the elimination of the user settings service, in some cases it + is still desirable to store secrets in the user's session and not in + system-wide storage (and thus available to all users). To allow this + functionality the concept of agents has been introduced. Using the new + + org.freedesktop.NetworkManager.AgentManager + D-Bus interface provided by NetworkManager, user applications can register + themselves as "secret agents", ie programs capable of saving and providing + secrets to NetworkManager. The agent should export the + + org.freedesktop.NetworkManager.SecretAgent + D-Bus interface, but should NOT claim a bus name on the system or session + bus. Instead, NetworkManager talks to the agent directly over the D-Bus + connection which the agent used to register itself. +

+ Each agent must send a unique identifier to NetworkManager when it + registers. This identifier must follow certain rules (see the NM D-Bus + API documentation for more details) but looks essentially the same as + a D-Bus service name. Only one agent using a given identifier may be + registered at the same time. The agent is automatically unregistered + if it disconnects from D-Bus or exits. +

+ When NetworkManager requires secrets during the attempt to connect to a + network, and no secrets are available from the internal settings service, + NetworkManager queries each registered agent for secrets. Agents that + are in "active" user sessions (as determined by ConsoleKit) are preferred + over inactive ones. Only agents belonging to users who have permission + to view and modify the connection are queried. For more information on + connection permissions, see below. +

+ When secrets are requested, the agent is also sent a set of flags that + modify the behavior of the request. By default, the agent should never + attempt to query the user for secrets, but should simply return any + available saved secrets. Other flags allow the agent to explicitly + request new secrets from the user. +

+ Action: the parts of a previous user + settings service that handled secrets may be easily repurposed as the bulk + of the implementation of a secret agent. The agent is sent all available + connection settings, and from those should be able to retrieve or save + any saved user secrets, or to request new secrets from the user. +

+Settings Service Interface Changes

+ 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. +

+ Additionally, the D-Bus interface of the settings service has changed + to + org.freedesktop.NetworkManager.Settings from + the old interface name of + org.freedesktop.NetworkManagerSettings, and the old + org.freedesktop.NetworkManagerSettings.System + interface has been merged into the new + + org.freedesktop.NetworkManager.Settings interface + as the split no longer made sense. This includes the + SaveHostname method and the Hostname + and CanModify properties. +

+ Action: change the service name that + your application uses to request system network settings to + org.freedesktop.NetworkManager, and update the D-Bus + interface that codes uses to talk to the settings service to + + org.freedesktop.NetworkManager.Settings. + Listen for hostname changes using the new interface name as well. +

+Connection Object Interface Changes

+ Consistent with the interface changes to the Settings object, the + Connection object's D-Bus interface has changed to + + org.freedesktop.NetworkManager.Settings.Connection + from the previous + org.freedesktop.NetworkManagerSettings.Connection. +

+ Additionally, the + org.freedesktop.NetworkManager.Settings.Connection.Updated + signal of the Connection object no longer includes the updated settings + data argument, as that might allow users who are not authorized to + view the connection details to do so. Instead, when a client receives the + Updated signal, it should requery the Connection's settings with the + org.freedesktop.NetworkManager.Settings.Connection.GetSettings + method. If the client receives an error as a result of this method call, + it should assume the connection has been deleted. +

+ Action: where code manipulates + Connection objects, update the D-Bus interface that code uses to be + org.freedesktop.NetworkManager.Settings.Connection. + Additionally, code that listens for the + org.freedesktop.NetworkManager.Settings.Connection.Updated + signal should no longer expect the new settings data as an argument, but + instead should request the new settings data using the + org.freedesktop.NetworkManager.Settings.Connection.GetSettings + method. +

+Permissions Methods Consolidation

+ 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: +

Table 17.

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

Old bitfield value	New 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. +

+AddConnection Returns Object Path of New Connection

+ The + org.freedesktop.NetworkManager.Settings.AddConnection + method call now returns the object path of the newly added + connection. Previously, if code wanted to manipulate a connection + post-addition, it had to wait for the new connection to be announced via + the NewConnection signal by matching connection UUIDs. Now the object + path is returned and this workaround is no longer required. +

+ Action: update code that adds new + connections to handle the object path returned from AddConnection, and + remove workarounds for finding the new connection via signals. +

+Support for WiMAX Devices

+ NetworkManager now supports Intel WiMAX mobile broadband devices. A + corresponding device type (NM_DEVICE_TYPE_WIMAX) and + a new + org.freedesktop.NetworkManager.Device.WiMax + D-Bus interface have been added. Furthermore, to support connection to + different WiMAX Network Service Providers (NSPs) the + + org.freedesktop.NetworkManager.Device.WiMax.Nsp + interface has been added to access information about each available + WiMAX network. +

+ Action: update code that handles + devices and/or displays status to users to recognize the new device type, + and to display available WiMAX NSPs similar to how WiFi Access Points + are displayed. Also update code that creates new connections to allow + creation of new WiMAX connections. +

+New Device States

+ A few new device states + have been added, and all device states have been renumbered for flexibility. + The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING. +

+ Action: where code checks device state + or shows UI indication of the device's state, make sure the new device + states are processed correctly, and that code in switch()-type statements + is updated to handle the new states. +

+New Active Connection State

+ Along with the new device states, an + additional + ActiveConnection state has been added: DEACTIVATING. This state + is entered when the connection is being torn down and deactivated. +

+ Action: where code checks active + connection states or shows UI indication of active connection states, make + sure the DEACTIVATING state is processed correctly, and that code in + switch()-type statements is updated to handle it. +

+Consolidated Modem Devices

+ Many new mobile broadband devices support multiple access families, like + Qualcomm Gobi cards (CDMA/EVDO and GSM/UMTS), or multi-mode EVDO/LTE + or UMTS/LTE modems like the Pantech UML290. The previous hard split + between CDMA/EVDO and GSM/UMTS device classes was not flexible enough to + deal with these new multi-mode devices. Thus the previously separate + CDMA and GSM device classes have been combined into a single Modem + device class, which exposes both hardware "ModemCapabilities" and + runtime "CurrentCapabilities" which represent generic access technology + families like CDMA/EVDO, GSM/UMTS, and LTE which the device supports. + ModemCapabilities indicate all the access technology families which the + modem is capable of supporting, while CurrentCapabilities indicate the + immediate access technology families the device supports without reloading + the firmware and thus restarting the device. +

+ Along with this change, the + org.freedesktop.NetworkManager.Device.Serial + interface has been removed as it's functionality will be incorporated + into the + + org.freedesktop.NetworkManager.Device.Modem + interface in the future. +

+ Action: combine code that checks for + the old CDMA and GSM device types, and instead handle the new Modem device + type. Where behavior must change based on the capabilities of the device, + check the CurrentCapabilities device property to determine whether to + treat the device as CDMA, GSM, or LTE for purposes of configuration and + status. +

+Secret Property Flags

+ In the Connection object's configuration properties, each setting's secret + properties (like WiFi passphrases, or public key passwords, etc) now has + an associated "flags" property that changes how NetworkManager treats the + secret. The "flags" property is a bitfield of one or more of the + following values: +

Table 18.

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

Flag Value	Meaning
0x00 (none)	+ NetworkManager is responsible for providing and storing this + secret (default) +
0x01 (agent-owned)	+ A user secret agent is responsible for providing and storing + this secret; when it is required agents will be asked to + retrieve it +
0x02 (not saved)	+ The secret is not saved, and should be requested each time it + is required. Used for OTP/token configurations where the + secret changes periodically, or if the user simply wants to + manually enter the secret each time. +
0x04 (not required)	+ In situations where it cannot be automatically determined that + the secret is required (some VPNs and PPP providers dont require + all possible secrets) this flag indicates that the specific + secret is not required. +

+ Action: user interface code which + handles entry of connection secrets should be updated to read and set + secret flags. For example, code that creates new VPN connections may want + to set the "agent-owned" flag to ensure that the user's VPN password is + not available to all users. EAP-TLS and VPN interface code might add a + checkbox that toggles the "not saved" bit to indicate that the + password/PIN code should be requested from a hardware token each time it + is required. +

+Deprecated Methods Removed

+ A few methods and signals of the org.freedesktop.NetworkManager + interface deprecated in version 0.7 have been removed. All the + replacement methods and signals have existed since version 0.7 and so are + not new to this version of NetworkManager, but some older programs may + be using removed items. The following table lists the removed items and + their replacements: +

Table 19.

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

Removed Item	Replacement
StateChange signal	+ Use the `StateChanged` signal, which has the + same arguments. +
sleep() and wake() methods	+ Use the `Sleep()` method instead, which takes + a boolean argument indicating whether NetworkManager should + go to sleep or wake up. +

+ Action: update code to use these + replacement methods and properties where it used old deprecated ones +