From f75dd6fd1975146623052b843b182dc32c3fbe46 Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Fri, 8 Apr 2011 07:30:59 +0200 Subject: Imported Upstream version 0.8.998 --- docs/api/migrating-to-09.xml | 476 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 docs/api/migrating-to-09.xml (limited to 'docs/api/migrating-to-09.xml') diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml new file mode 100644 index 00000000..910c1369 --- /dev/null +++ b/docs/api/migrating-to-09.xml @@ -0,0 +1,476 @@ + + +]> + + Migrating from NetworkManager 0.8 to NetworkManager 0.9 + + + 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: + + + + 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. + +
+ +
+ 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: + + + + Flag ValueMeaning + + + + 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: + + + + Removed ItemReplacement + + + + 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 + +
+ +
+ + -- cgit 1.3.0-6-gf8a5