From d9c99a29a0d3384c9c3d2adce430f5cb1134ab6a Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Wed, 30 Mar 2016 00:56:30 +0200 Subject: Imported Upstream version 1.1.92 --- docs/api/migrating-to-09.xml | 478 ------------------------------------------- 1 file changed, 478 deletions(-) delete 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 deleted file mode 100644 index f282d646..00000000 --- a/docs/api/migrating-to-09.xml +++ /dev/null @@ -1,478 +0,0 @@ - - -]> - - 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 has also changed to - /org/freedesktop/NetworkManager/Settings. - - - 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 and - object path that your application uses to request system network settings - to org.freedesktop.NetworkManager and - /org/freedesktop/NetworkManager/Settings respectively, - 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