diff options
Diffstat (limited to 'docs/api/migrating-to-09.xml')
| -rw-r--r-- | docs/api/migrating-to-09.xml | 476 |
1 files changed, 0 insertions, 476 deletions
diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml deleted file mode 100644 index 910c1369f..000000000 --- a/docs/api/migrating-to-09.xml +++ /dev/null @@ -1,476 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ -<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> -]> -<chapter id="ref-migrating"> - <title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title> - - <para> - 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. - </para> - - <section> - <title>Architecture and D-Bus API Changes in 0.9</title> - - <para> - This section details the architectural and D-Bus API changes in - NetworkManager 0.9. - </para> - - <section> - <title>Elimination of the User Settings Service</title> - <para> - 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. - </para> - <para> - Elimination of the user settings service provides the following advantages - for clients of NetworkManager: - <itemizedlist> - <listitem>Simpler discovery of network configuration and change tracking</listitem> - <listitem>Simpler storage of user-level network secrets by control applets</listitem> - <listitem>Correct operation of fast-user switching and multi-seat configurations</listitem> - <listitem>More granular network connection permissions for system administrators</listitem> - <listitem>Connections are now system-wide by default (unless restricted by the user or system administrator)</listitem> - <listitem>Easier deployment of user-specific connections (ie, VPNs)</listitem> - </itemizedlist> - </para> - <para> - With this change, D-Bus methods that previously took a "service name" - argument (like - <literal>org.freedesktop.NetworkManager.ActivateConnection</literal>) and - objects with service name properties (like ActiveConnection objects) no - longer have those arguments or properties. - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>User Secret Agents</title> - <para> - 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 - <ulink url="spec.html#org.freedesktop.NetworkManager.AgentManager"> - <literal>org.freedesktop.NetworkManager.AgentManager</literal></ulink> - 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 - <ulink url="spec.html#org.freedesktop.NetworkManager.SecretAgent"> - <literal>org.freedesktop.NetworkManager.SecretAgent</literal></ulink> - 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. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - 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. - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>Settings Service Interface Changes</title> - <para> - With the elimination of the user settings service, the old - <literal>org.freedesktop.NetworkManagerUserSettings</literal> and - <literal>org.freedesktop.NetworkManagerSystemSettings</literal> D-Bus - service names are no longer used. Instead NetworkManager provides the - settings service using its own D-Bus service name, - <literal>org.freedesktop.NetworkManager</literal>. The object path of - the settings service remains unchanged. - </para> - <para> - Additionally, the D-Bus interface of the settings service has changed - to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings"> - <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> from - the old interface name of - <literal>org.freedesktop.NetworkManagerSettings</literal>, and the old - <literal>org.freedesktop.NetworkManagerSettings.System</literal> - interface has been merged into the new - <ulink url="spec.html#org.freedesktop.NetworkManager.Settings"> - <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> interface - as the split no longer made sense. This includes the - <literal>SaveHostname</literal> method and the <literal>Hostname</literal> - and <literal>CanModify</literal> properties. - </para> - <para> - <emphasis role="strong">Action:</emphasis> change the service name that - your application uses to request system network settings to - <literal>org.freedesktop.NetworkManager</literal>, and update the D-Bus - interface that codes uses to talk to the settings service to - <ulink url="spec.html#org.freedesktop.NetworkManager.Settings"> - <literal>org.freedesktop.NetworkManager.Settings</literal></ulink>. - Listen for hostname changes using the new interface name as well. - </para> - </section> - - <section> - <title>Connection Object Interface Changes</title> - <para> - Consistent with the interface changes to the Settings object, the - Connection object's D-Bus interface has changed to - <ulink url="spec.html#org.freedesktop.NetworkManager.Settings.Connection"> - <literal>org.freedesktop.NetworkManager.Settings.Connection</literal></ulink> - from the previous - <literal>org.freedesktop.NetworkManagerSettings.Connection</literal>. - </para> - <para> - Additionally, the - <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal> - 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 - <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal> - method. If the client receives an error as a result of this method call, - it should assume the connection has been deleted. - </para> - <para> - <emphasis role="strong">Action:</emphasis> where code manipulates - Connection objects, update the D-Bus interface that code uses to be - <literal>org.freedesktop.NetworkManager.Settings.Connection</literal>. - Additionally, code that listens for the - <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal> - signal should no longer expect the new settings data as an argument, but - instead should request the new settings data using the - <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal> - method. - </para> - </section> - - <section> - <title>Permissions Methods Consolidation</title> - <para> - 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: - <itemizedlist> - <listitem> - <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal> - which returned a bitfield of operations the caller was allowed to - perform related to modify system network settings and the machine - hostname - </listitem> - <listitem> - <literal>org.freedesktop.NetworkManager.GetPermissions</literal> 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. - </listitem> - </itemizedlist> - These two calls have been consolidated into an enhanced - <literal>org.freedesktop.NetworkManager.GetPermissions</literal> call that - uses the same arguments, but includes all permissions, including those which - the settings service used to handle. - </para> - <para> - With this change, the bitfield items from - <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal> - are now string-based permissions. The mapping is as follows: - <table> - <tgroup cols="2"> - <thead> - <row><entry>Old bitfield value</entry><entry>New permission name</entry></row> - </thead> - <tbody> - <row> - <entry><screen>0x1 (connection-modify)</screen></entry> - <entry> - <literal>org.freedesktop.NetworkManager.settings.modify.system</literal> - or <literal>org.freedesktop.NetworkManager.settings.modify.system</literal> - depending on the permissions of the connection. - </entry> - </row> - <row> - <entry><screen>0x2 (wifi-share-protected)</screen></entry> - <entry> - <literal>org.freedesktop.NetworkManager.wifi.share.protected</literal> - </entry> - </row> - <row> - <entry><screen>0x4 (wifi-share-open)</screen></entry> - <entry> - <literal>org.freedesktop.NetworkManager.wifi.share.open</literal> - </entry> - </row> - <row> - <entry><screen>0x8 (hostname-modify)</screen></entry> - <entry> - <literal>org.freedesktop.NetworkManager.settings.modify.hostname</literal> - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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 - <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>. - </para> - </section> - - <section> - <title>AddConnection Returns Object Path of New Connection</title> - <para> - The <ulink url="spec.html#org.freedesktop.NetworkManager.Settings"> - <literal>org.freedesktop.NetworkManager.Settings.AddConnection</literal> - </ulink> 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. - </para> - <para> - <emphasis role="strong">Action:</emphasis> update code that adds new - connections to handle the object path returned from AddConnection, and - remove workarounds for finding the new connection via signals. - </para> - </section> - - <section> - <title>Support for WiMAX Devices</title> - <para> - NetworkManager now supports Intel WiMAX mobile broadband devices. A - corresponding device type (<literal>NM_DEVICE_TYPE_WIMAX</literal>) and - a new <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax"> - <literal>org.freedesktop.NetworkManager.Device.WiMax</literal></ulink> - D-Bus interface have been added. Furthermore, to support connection to - different WiMAX Network Service Providers (NSPs) the - <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax.Nsp"> - <literal>org.freedesktop.NetworkManager.Device.WiMax.Nsp</literal></ulink> - interface has been added to access information about each available - WiMAX network. - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>New Device States</title> - <para> - A few <ulink url="spec.html#type-NM_DEVICE_STATE">new device states</ulink> - have been added, and all device states have been renumbered for flexibility. - The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING. - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>New Active Connection State</title> - <para> - Along with the new device states, an - <ulink url="spec.html#type-NM_ACTIVE_CONNECTION_STATE">additional - ActiveConnection state</ulink> has been added: DEACTIVATING. This state - is entered when the connection is being torn down and deactivated. - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>Consolidated Modem Devices</title> - <para> - 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. - </para> - <para> - Along with this change, the - <literal>org.freedesktop.NetworkManager.Device.Serial</literal> - interface has been removed as it's functionality will be incorporated - into the - <ulink url="spec.html#org.freedesktop.NetworkManager.Device.Modem"> - <literal>org.freedesktop.NetworkManager.Device.Modem</literal></ulink> - interface in the future. - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>Secret Property Flags</title> - <para> - 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> - <tgroup cols="2"> - <thead> - <row><entry>Flag Value</entry><entry>Meaning</entry></row> - </thead> - <tbody> - <row> - <entry><screen>0x00 (none)</screen></entry> - <entry> - NetworkManager is responsible for providing and storing this - secret (default) - </entry> - </row> - <row> - <entry><screen>0x01 (agent-owned)</screen></entry> - <entry> - A user secret agent is responsible for providing and storing - this secret; when it is required agents will be asked to - retrieve it - </entry> - </row> - <row> - <entry><screen>0x02 (not saved)</screen></entry> - <entry> - 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. - </entry> - </row> - <row> - <entry><screen>0x04 (not required)</screen></entry> - <entry> - 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. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - <emphasis role="strong">Action:</emphasis> 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. - </para> - </section> - - <section> - <title>Deprecated Methods Removed</title> - <para> - A few methods and signals of the <literal>org.freedesktop.NetworkManager</literal> - 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> - <tgroup cols="2"> - <thead> - <row><entry>Removed Item</entry><entry>Replacement</entry></row> - </thead> - <tbody> - <row> - <entry><screen>StateChange signal</screen></entry> - <entry> - Use the <literal>StateChanged</literal> signal, which has the - same arguments. - </entry> - </row> - <row> - <entry><screen>sleep() and wake() methods</screen></entry> - <entry> - Use the <literal>Sleep()</literal> method instead, which takes - a boolean argument indicating whether NetworkManager should - go to sleep or wake up. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - <emphasis role="strong">Action:</emphasis> update code to use these - replacement methods and properties where it used old deprecated ones - </para> - </section> - - </section> - -</chapter> |