diff options
| author | Michael Biebl <biebl@debian.org> | 2011-04-21 10:42:53 +0200 |
|---|---|---|
| committer | Michael Biebl <biebl@debian.org> | 2011-04-21 10:42:53 +0200 |
| commit | 8baa1aca8dfd35e3190d7d5655eb83b5b901e263 (patch) | |
| tree | a9ac1e67d0c22a48330c76f08fc5291f85307055 /docs/api/html/ref-migrating.html | |
| parent | f75dd6fd1975146623052b843b182dc32c3fbe46 (diff) | |
Imported Upstream version 0.8.4.0 upstream/0.8.4.0
Diffstat (limited to 'docs/api/html/ref-migrating.html')
| -rw-r--r-- | docs/api/html/ref-migrating.html | 539 |
1 files changed, 0 insertions, 539 deletions
diff --git a/docs/api/html/ref-migrating.html b/docs/api/html/ref-migrating.html deleted file mode 100644 index a08e8f08..00000000 --- a/docs/api/html/ref-migrating.html +++ /dev/null @@ -1,539 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="index.html" title="NetworkManager D-Bus Reference Manual"> -<link rel="up" href="index.html" title="NetworkManager D-Bus Reference Manual"> -<link rel="prev" href="secrets-flags.html" title="Secret flag types"> -<link rel="next" href="ix01.html" title="Index"> -<meta name="generator" content="GTK-Doc V1.17 (XML mode)"> -<link rel="stylesheet" href="style.css" type="text/css"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> -<td><a accesskey="p" href="secrets-flags.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> -<td> </td> -<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> -<th width="100%" align="center">NetworkManager D-Bus Reference Manual</th> -<td><a accesskey="n" href="ix01.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> -</tr></table> -<div class="chapter"> -<div class="titlepage"><div><div><h2 class="title"> -<a name="ref-migrating"></a>Migrating from NetworkManager 0.8 to NetworkManager 0.9</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="ref-migrating.html#id537843">Architecture and D-Bus API Changes in 0.9</a></span></dt> -<dd><dl> -<dt><span class="section"><a href="ref-migrating.html#id551050">Elimination of the User Settings Service</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id532968">User Secret Agents</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id545506">Settings Service Interface Changes</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id546055">Connection Object Interface Changes</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id560506">Permissions Methods Consolidation</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id566633">AddConnection Returns Object Path of New Connection</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id523443">Support for WiMAX Devices</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id565603">New Device States</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id534542">New Active Connection State</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id533386">Consolidated Modem Devices</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id514244">Secret Property Flags</a></span></dt> -<dt><span class="section"><a href="ref-migrating.html#id529216">Deprecated Methods Removed</a></span></dt> -</dl></dd> -</dl></div> -<p> - 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. - </p> -<div class="section"> -<div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="id537843"></a>Architecture and D-Bus API Changes in 0.9</h2></div></div></div> -<p> - This section details the architectural and D-Bus API changes in - NetworkManager 0.9. - </p> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id551050"></a>Elimination of the User Settings Service</h3></div></div></div> -<p> - 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. - </p> -<p> - Elimination of the user settings service provides the following advantages - for clients of NetworkManager: - </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> -<li class="listitem">Simpler discovery of network configuration and change tracking</li> -<li class="listitem">Simpler storage of user-level network secrets by control applets</li> -<li class="listitem">Correct operation of fast-user switching and multi-seat configurations</li> -<li class="listitem">More granular network connection permissions for system administrators</li> -<li class="listitem">Connections are now system-wide by default (unless restricted by the user or system administrator)</li> -<li class="listitem">Easier deployment of user-specific connections (ie, VPNs)</li> -</ul></div> -<p> - </p> -<p> - With this change, D-Bus methods that previously took a "service name" - argument (like - <code class="literal">org.freedesktop.NetworkManager.ActivateConnection</code>) and - objects with service name properties (like ActiveConnection objects) no - longer have those arguments or properties. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id532968"></a>User Secret Agents</h3></div></div></div> -<p> - 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 - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.AgentManager" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.AgentManager</code></a> - 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 - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.SecretAgent" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.SecretAgent</code></a> - 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. - </p> -<p> - 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. - </p> -<p> - 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. - </p> - 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. - <p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id545506"></a>Settings Service Interface Changes</h3></div></div></div> -<p> - With the elimination of the user settings service, the old - <code class="literal">org.freedesktop.NetworkManagerUserSettings</code> and - <code class="literal">org.freedesktop.NetworkManagerSystemSettings</code> D-Bus - service names are no longer used. Instead NetworkManager provides the - settings service using its own D-Bus service name, - <code class="literal">org.freedesktop.NetworkManager</code>. The object path of - the settings service remains unchanged. - </p> -<p> - Additionally, the D-Bus interface of the settings service has changed - to <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Settings" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Settings</code></a> from - the old interface name of - <code class="literal">org.freedesktop.NetworkManagerSettings</code>, and the old - <code class="literal">org.freedesktop.NetworkManagerSettings.System</code> - interface has been merged into the new - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Settings" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Settings</code></a> interface - as the split no longer made sense. This includes the - <code class="literal">SaveHostname</code> method and the <code class="literal">Hostname</code> - and <code class="literal">CanModify</code> properties. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> change the service name that - your application uses to request system network settings to - <code class="literal">org.freedesktop.NetworkManager</code>, and update the D-Bus - interface that codes uses to talk to the settings service to - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Settings" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Settings</code></a>. - Listen for hostname changes using the new interface name as well. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id546055"></a>Connection Object Interface Changes</h3></div></div></div> -<p> - Consistent with the interface changes to the Settings object, the - Connection object's D-Bus interface has changed to - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Settings.Connection" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection</code></a> - from the previous - <code class="literal">org.freedesktop.NetworkManagerSettings.Connection</code>. - </p> -<p> - Additionally, the - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection.Updated</code> - 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 - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection.GetSettings</code> - method. If the client receives an error as a result of this method call, - it should assume the connection has been deleted. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> where code manipulates - Connection objects, update the D-Bus interface that code uses to be - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection</code>. - Additionally, code that listens for the - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection.Updated</code> - signal should no longer expect the new settings data as an argument, but - instead should request the new settings data using the - <code class="literal">org.freedesktop.NetworkManager.Settings.Connection.GetSettings</code> - method. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id560506"></a>Permissions Methods Consolidation</h3></div></div></div> -<p> - 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: - </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> -<li class="listitem"> -<code class="literal">org.freedesktop.NetworkManagerSettings.System.GetPermissions</code> - which returned a bitfield of operations the caller was allowed to - perform related to modify system network settings and the machine - hostname - </li> -<li class="listitem"> -<code class="literal">org.freedesktop.NetworkManager.GetPermissions</code> 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. - </li> -</ul></div> -<p> - These two calls have been consolidated into an enhanced - <code class="literal">org.freedesktop.NetworkManager.GetPermissions</code> call that - uses the same arguments, but includes all permissions, including those which - the settings service used to handle. - </p> -<p> - With this change, the bitfield items from - <code class="literal">org.freedesktop.NetworkManagerSettings.System.GetPermissions</code> - are now string-based permissions. The mapping is as follows: - </p> -<div class="table"> -<a name="id555187"></a><p class="title"><b>Table 17. </b></p> -<div class="table-contents"><table border="1"> -<colgroup> -<col> -<col> -</colgroup> -<thead><tr> -<th>Old bitfield value</th> -<th>New permission name</th> -</tr></thead> -<tbody> -<tr> -<td><pre class="screen">0x1 (connection-modify)</pre></td> -<td> - <code class="literal">org.freedesktop.NetworkManager.settings.modify.system</code> - or <code class="literal">org.freedesktop.NetworkManager.settings.modify.system</code> - depending on the permissions of the connection. - </td> -</tr> -<tr> -<td><pre class="screen">0x2 (wifi-share-protected)</pre></td> -<td> - <code class="literal">org.freedesktop.NetworkManager.wifi.share.protected</code> - </td> -</tr> -<tr> -<td><pre class="screen">0x4 (wifi-share-open)</pre></td> -<td> - <code class="literal">org.freedesktop.NetworkManager.wifi.share.open</code> - </td> -</tr> -<tr> -<td><pre class="screen">0x8 (hostname-modify)</pre></td> -<td> - <code class="literal">org.freedesktop.NetworkManager.settings.modify.hostname</code> - </td> -</tr> -</tbody> -</table></div> -</div> -<p><br class="table-break"> - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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 - <code class="literal">org.freedesktop.NetworkManagerSettings.System.GetPermissions</code>. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id566633"></a>AddConnection Returns Object Path of New Connection</h3></div></div></div> -<p> - The <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Settings" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Settings.AddConnection</code> - </a> 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. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> update code that adds new - connections to handle the object path returned from AddConnection, and - remove workarounds for finding the new connection via signals. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id523443"></a>Support for WiMAX Devices</h3></div></div></div> -<p> - NetworkManager now supports Intel WiMAX mobile broadband devices. A - corresponding device type (<code class="literal">NM_DEVICE_TYPE_WIMAX</code>) and - a new <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Device.WiMax" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Device.WiMax</code></a> - D-Bus interface have been added. Furthermore, to support connection to - different WiMAX Network Service Providers (NSPs) the - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Device.WiMax.Nsp" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Device.WiMax.Nsp</code></a> - interface has been added to access information about each available - WiMAX network. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id565603"></a>New Device States</h3></div></div></div> -<p> - A few <a class="ulink" href="spec.html#type-NM_DEVICE_STATE" target="_top">new device states</a> - have been added, and all device states have been renumbered for flexibility. - The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id534542"></a>New Active Connection State</h3></div></div></div> -<p> - Along with the new device states, an - <a class="ulink" href="spec.html#type-NM_ACTIVE_CONNECTION_STATE" target="_top">additional - ActiveConnection state</a> has been added: DEACTIVATING. This state - is entered when the connection is being torn down and deactivated. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id533386"></a>Consolidated Modem Devices</h3></div></div></div> -<p> - 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. - </p> -<p> - Along with this change, the - <code class="literal">org.freedesktop.NetworkManager.Device.Serial</code> - interface has been removed as it's functionality will be incorporated - into the - <a class="ulink" href="spec.html#org.freedesktop.NetworkManager.Device.Modem" target="_top"> - <code class="literal">org.freedesktop.NetworkManager.Device.Modem</code></a> - interface in the future. - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id514244"></a>Secret Property Flags</h3></div></div></div> -<p> - 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: - </p> -<div class="table"> -<a name="id514253"></a><p class="title"><b>Table 18. </b></p> -<div class="table-contents"><table border="1"> -<colgroup> -<col> -<col> -</colgroup> -<thead><tr> -<th>Flag Value</th> -<th>Meaning</th> -</tr></thead> -<tbody> -<tr> -<td><pre class="screen">0x00 (none)</pre></td> -<td> - NetworkManager is responsible for providing and storing this - secret (default) - </td> -</tr> -<tr> -<td><pre class="screen">0x01 (agent-owned)</pre></td> -<td> - A user secret agent is responsible for providing and storing - this secret; when it is required agents will be asked to - retrieve it - </td> -</tr> -<tr> -<td><pre class="screen">0x02 (not saved)</pre></td> -<td> - 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. - </td> -</tr> -<tr> -<td><pre class="screen">0x04 (not required)</pre></td> -<td> - 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. - </td> -</tr> -</tbody> -</table></div> -</div> -<p><br class="table-break"> - </p> -<p> - <span class="strong"><strong>Action:</strong></span> 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. - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="id529216"></a>Deprecated Methods Removed</h3></div></div></div> -<p> - A few methods and signals of the <code class="literal">org.freedesktop.NetworkManager</code> - 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: - </p> -<div class="table"> -<a name="id529230"></a><p class="title"><b>Table 19. </b></p> -<div class="table-contents"><table border="1"> -<colgroup> -<col> -<col> -</colgroup> -<thead><tr> -<th>Removed Item</th> -<th>Replacement</th> -</tr></thead> -<tbody> -<tr> -<td><pre class="screen">StateChange signal</pre></td> -<td> - Use the <code class="literal">StateChanged</code> signal, which has the - same arguments. - </td> -</tr> -<tr> -<td><pre class="screen">sleep() and wake() methods</pre></td> -<td> - Use the <code class="literal">Sleep()</code> method instead, which takes - a boolean argument indicating whether NetworkManager should - go to sleep or wake up. - </td> -</tr> -</tbody> -</table></div> -</div> -<p><br class="table-break"> - </p> -<p> - <span class="strong"><strong>Action:</strong></span> update code to use these - replacement methods and properties where it used old deprecated ones - </p> -</div> -</div> -</div> -<div class="footer"> -<hr> - Generated by GTK-Doc V1.17</div> -</body> -</html> \ No newline at end of file |