diff options
Diffstat (limited to 'docs/api/html/ref-migrating.html')
| -rw-r--r-- | docs/api/html/ref-migrating.html | 539 |
1 files changed, 539 insertions, 0 deletions
diff --git a/docs/api/html/ref-migrating.html b/docs/api/html/ref-migrating.html new file mode 100644 index 000000000..a08e8f081 --- /dev/null +++ b/docs/api/html/ref-migrating.html @@ -0,0 +1,539 @@ +<!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 |