2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
6 <chapter id="ref-migrating">
7 <title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title>
10 NetworkManager 0.9 is a new major version of NetworkManager that breaks
11 both API and ABI compared to previous versions. These changes are
12 intended to make communication with NetworkManager much simpler, especially
13 for network control and configuration programs. Thankfully, most changes
14 are not difficult to implement, and the advantages of the simpler
15 architecture of NetworkManager 0.9 greatly outweight the effort of
16 updating client programs.
20 <title>Architecture and D-Bus API Changes in 0.9</title>
23 This section details the architectural and D-Bus API changes in
28 <title>Elimination of the User Settings Service</title>
30 Previously there were two "settings services", or D-Bus services that
31 provided and saved network configuration information. NetworkManager
32 owned the "system" settings service, and one user-level applet owned the
33 "user" settings service. Now, the "user" settings service has been
34 eliminated, so clients only have to track one D-Bus service to read and
35 update network configuration. The functionality of the old user settings
36 service has been replaced with a "permissions" key on each connection
37 object to preserve the ability to restrict which users can use the
38 connection, and with a "secret agent" D-Bus API for user-session-level
39 secure storage of network secrets and passwords.
42 Elimination of the user settings service provides the following advantages
43 for clients of NetworkManager:
45 <listitem>Simpler discovery of network configuration and change tracking</listitem>
46 <listitem>Simpler storage of user-level network secrets by control applets</listitem>
47 <listitem>Correct operation of fast-user switching and multi-seat configurations</listitem>
48 <listitem>More granular network connection permissions for system administrators</listitem>
49 <listitem>Connections are now system-wide by default (unless restricted by the user or system administrator)</listitem>
50 <listitem>Easier deployment of user-specific connections (ie, VPNs)</listitem>
54 With this change, D-Bus methods that previously took a "service name"
56 <literal>org.freedesktop.NetworkManager.ActivateConnection</literal>) and
57 objects with service name properties (like ActiveConnection objects) no
58 longer have those arguments or properties.
61 <emphasis role="strong">Action:</emphasis> if you develop a network control
62 applet that talks to NetworkManager and used to provide a user settings
63 service, you can eliminate that code and rely on NetworkManager for all
64 storage of network configuration. Your applet should now implement the
65 Secret Agent D-Bus API (see below) to store user-specific secrets, and
66 add legacy user-specific configuration to NetworkManager when run. More
67 information about both these changes follows.
72 <title>User Secret Agents</title>
74 Even with the elimination of the user settings service, in some cases it
75 is still desirable to store secrets in the user's session and not in
76 system-wide storage (and thus available to all users). To allow this
77 functionality the concept of agents has been introduced. Using the new
78 <ulink url="spec.html#org.freedesktop.NetworkManager.AgentManager">
79 <literal>org.freedesktop.NetworkManager.AgentManager</literal></ulink>
80 D-Bus interface provided by NetworkManager, user applications can register
81 themselves as "secret agents", ie programs capable of saving and providing
82 secrets to NetworkManager. The agent should export the
83 <ulink url="spec.html#org.freedesktop.NetworkManager.SecretAgent">
84 <literal>org.freedesktop.NetworkManager.SecretAgent</literal></ulink>
85 D-Bus interface, but should NOT claim a bus name on the system or session
86 bus. Instead, NetworkManager talks to the agent directly over the D-Bus
87 connection which the agent used to register itself.
90 Each agent must send a unique identifier to NetworkManager when it
91 registers. This identifier must follow certain rules (see the NM D-Bus
92 API documentation for more details) but looks essentially the same as
93 a D-Bus service name. Only one agent using a given identifier may be
94 registered at the same time. The agent is automatically unregistered
95 if it disconnects from D-Bus or exits.
98 When NetworkManager requires secrets during the attempt to connect to a
99 network, and no secrets are available from the internal settings service,
100 NetworkManager queries each registered agent for secrets. Agents that
101 are in "active" user sessions (as determined by ConsoleKit) are preferred
102 over inactive ones. Only agents belonging to users who have permission
103 to view and modify the connection are queried. For more information on
104 connection permissions, see below.
106 When secrets are requested, the agent is also sent a set of flags that
107 modify the behavior of the request. By default, the agent should never
108 attempt to query the user for secrets, but should simply return any
109 available saved secrets. Other flags allow the agent to explicitly
110 request new secrets from the user.
112 <emphasis role="strong">Action:</emphasis> the parts of a previous user
113 settings service that handled secrets may be easily repurposed as the bulk
114 of the implementation of a secret agent. The agent is sent all available
115 connection settings, and from those should be able to retrieve or save
116 any saved user secrets, or to request new secrets from the user.
121 <title>Settings Service Interface Changes</title>
123 With the elimination of the user settings service, the old
124 <literal>org.freedesktop.NetworkManagerUserSettings</literal> and
125 <literal>org.freedesktop.NetworkManagerSystemSettings</literal> D-Bus
126 service names are no longer used. Instead NetworkManager provides the
127 settings service using its own D-Bus service name,
128 <literal>org.freedesktop.NetworkManager</literal>. The object path of
129 the settings service has also changed to
130 <literal>/org/freedesktop/NetworkManager/Settings</literal>.
133 Additionally, the D-Bus interface of the settings service has changed
134 to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
135 <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> from
136 the old interface name of
137 <literal>org.freedesktop.NetworkManagerSettings</literal>, and the old
138 <literal>org.freedesktop.NetworkManagerSettings.System</literal>
139 interface has been merged into the new
140 <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
141 <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> interface
142 as the split no longer made sense. This includes the
143 <literal>SaveHostname</literal> method and the <literal>Hostname</literal>
144 and <literal>CanModify</literal> properties.
147 <emphasis role="strong">Action:</emphasis> change the service name and
148 object path that your application uses to request system network settings
149 to <literal>org.freedesktop.NetworkManager</literal> and
150 <literal>/org/freedesktop/NetworkManager/Settings</literal> respectively,
151 and update the D-Bus interface that codes uses to talk to the settings
152 service to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
153 <literal>org.freedesktop.NetworkManager.Settings</literal></ulink>.
154 Listen for hostname changes using the new interface name as well.
159 <title>Connection Object Interface Changes</title>
161 Consistent with the interface changes to the Settings object, the
162 Connection object's D-Bus interface has changed to
163 <ulink url="spec.html#org.freedesktop.NetworkManager.Settings.Connection">
164 <literal>org.freedesktop.NetworkManager.Settings.Connection</literal></ulink>
166 <literal>org.freedesktop.NetworkManagerSettings.Connection</literal>.
170 <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
171 signal of the Connection object no longer includes the updated settings
172 data argument, as that might allow users who are not authorized to
173 view the connection details to do so. Instead, when a client receives the
174 Updated signal, it should requery the Connection's settings with the
175 <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
176 method. If the client receives an error as a result of this method call,
177 it should assume the connection has been deleted.
180 <emphasis role="strong">Action:</emphasis> where code manipulates
181 Connection objects, update the D-Bus interface that code uses to be
182 <literal>org.freedesktop.NetworkManager.Settings.Connection</literal>.
183 Additionally, code that listens for the
184 <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
185 signal should no longer expect the new settings data as an argument, but
186 instead should request the new settings data using the
187 <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
193 <title>Permissions Methods Consolidation</title>
195 Previously there were two D-Bus method calls to retrieve the list of
196 operations that a user client could perform, and two signals notifying
197 callers that they should recheck permissions. Those two calls were:
200 <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
201 which returned a bitfield of operations the caller was allowed to
202 perform related to modify system network settings and the machine
206 <literal>org.freedesktop.NetworkManager.GetPermissions</literal> which
207 returned a dictionary mapping permission names to result strings like
208 "yes", "auth", or "no", relating to network control permissions like
209 the ability to enable or disable WiFi.
212 These two calls have been consolidated into an enhanced
213 <literal>org.freedesktop.NetworkManager.GetPermissions</literal> call that
214 uses the same arguments, but includes all permissions, including those which
215 the settings service used to handle.
218 With this change, the bitfield items from
219 <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
220 are now string-based permissions. The mapping is as follows:
224 <row><entry>Old bitfield value</entry><entry>New permission name</entry></row>
228 <entry><screen>0x1 (connection-modify)</screen></entry>
230 <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
231 or <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
232 depending on the permissions of the connection.
236 <entry><screen>0x2 (wifi-share-protected)</screen></entry>
238 <literal>org.freedesktop.NetworkManager.wifi.share.protected</literal>
242 <entry><screen>0x4 (wifi-share-open)</screen></entry>
244 <literal>org.freedesktop.NetworkManager.wifi.share.open</literal>
248 <entry><screen>0x8 (hostname-modify)</screen></entry>
250 <literal>org.freedesktop.NetworkManager.settings.modify.hostname</literal>
258 <emphasis role="strong">Action:</emphasis> modify handling of existing
259 code that checks permissions to recognize the new permissions names for
260 old system settings permissions, and remove code that used to call
261 <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>.
266 <title>AddConnection Returns Object Path of New Connection</title>
268 The <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
269 <literal>org.freedesktop.NetworkManager.Settings.AddConnection</literal>
270 </ulink> method call now returns the object path of the newly added
271 connection. Previously, if code wanted to manipulate a connection
272 post-addition, it had to wait for the new connection to be announced via
273 the NewConnection signal by matching connection UUIDs. Now the object
274 path is returned and this workaround is no longer required.
277 <emphasis role="strong">Action:</emphasis> update code that adds new
278 connections to handle the object path returned from AddConnection, and
279 remove workarounds for finding the new connection via signals.
284 <title>Support for WiMAX Devices</title>
286 NetworkManager now supports Intel WiMAX mobile broadband devices. A
287 corresponding device type (<literal>NM_DEVICE_TYPE_WIMAX</literal>) and
288 a new <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax">
289 <literal>org.freedesktop.NetworkManager.Device.WiMax</literal></ulink>
290 D-Bus interface have been added. Furthermore, to support connection to
291 different WiMAX Network Service Providers (NSPs) the
292 <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax.Nsp">
293 <literal>org.freedesktop.NetworkManager.Device.WiMax.Nsp</literal></ulink>
294 interface has been added to access information about each available
298 <emphasis role="strong">Action:</emphasis> update code that handles
299 devices and/or displays status to users to recognize the new device type,
300 and to display available WiMAX NSPs similar to how WiFi Access Points
301 are displayed. Also update code that creates new connections to allow
302 creation of new WiMAX connections.
307 <title>New Device States</title>
309 A few <ulink url="spec.html#type-NM_DEVICE_STATE">new device states</ulink>
310 have been added, and all device states have been renumbered for flexibility.
311 The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING.
314 <emphasis role="strong">Action:</emphasis> where code checks device state
315 or shows UI indication of the device's state, make sure the new device
316 states are processed correctly, and that code in switch()-type statements
317 is updated to handle the new states.
322 <title>New Active Connection State</title>
324 Along with the new device states, an
325 <ulink url="spec.html#type-NM_ACTIVE_CONNECTION_STATE">additional
326 ActiveConnection state</ulink> has been added: DEACTIVATING. This state
327 is entered when the connection is being torn down and deactivated.
330 <emphasis role="strong">Action:</emphasis> where code checks active
331 connection states or shows UI indication of active connection states, make
332 sure the DEACTIVATING state is processed correctly, and that code in
333 switch()-type statements is updated to handle it.
338 <title>Consolidated Modem Devices</title>
340 Many new mobile broadband devices support multiple access families, like
341 Qualcomm Gobi cards (CDMA/EVDO and GSM/UMTS), or multi-mode EVDO/LTE
342 or UMTS/LTE modems like the Pantech UML290. The previous hard split
343 between CDMA/EVDO and GSM/UMTS device classes was not flexible enough to
344 deal with these new multi-mode devices. Thus the previously separate
345 CDMA and GSM device classes have been combined into a single Modem
346 device class, which exposes both hardware "ModemCapabilities" and
347 runtime "CurrentCapabilities" which represent generic access technology
348 families like CDMA/EVDO, GSM/UMTS, and LTE which the device supports.
349 ModemCapabilities indicate all the access technology families which the
350 modem is capable of supporting, while CurrentCapabilities indicate the
351 immediate access technology families the device supports without reloading
352 the firmware and thus restarting the device.
355 Along with this change, the
356 <literal>org.freedesktop.NetworkManager.Device.Serial</literal>
357 interface has been removed as it's functionality will be incorporated
359 <ulink url="spec.html#org.freedesktop.NetworkManager.Device.Modem">
360 <literal>org.freedesktop.NetworkManager.Device.Modem</literal></ulink>
361 interface in the future.
364 <emphasis role="strong">Action:</emphasis> combine code that checks for
365 the old CDMA and GSM device types, and instead handle the new Modem device
366 type. Where behavior must change based on the capabilities of the device,
367 check the CurrentCapabilities device property to determine whether to
368 treat the device as CDMA, GSM, or LTE for purposes of configuration and
374 <title>Secret Property Flags</title>
376 In the Connection object's configuration properties, each setting's secret
377 properties (like WiFi passphrases, or public key passwords, etc) now has
378 an associated "flags" property that changes how NetworkManager treats the
379 secret. The "flags" property is a bitfield of one or more of the
384 <row><entry>Flag Value</entry><entry>Meaning</entry></row>
388 <entry><screen>0x00 (none)</screen></entry>
390 NetworkManager is responsible for providing and storing this
395 <entry><screen>0x01 (agent-owned)</screen></entry>
397 A user secret agent is responsible for providing and storing
398 this secret; when it is required agents will be asked to
403 <entry><screen>0x02 (not saved)</screen></entry>
405 The secret is not saved, and should be requested each time it
406 is required. Used for OTP/token configurations where the
407 secret changes periodically, or if the user simply wants to
408 manually enter the secret each time.
412 <entry><screen>0x04 (not required)</screen></entry>
414 In situations where it cannot be automatically determined that
415 the secret is required (some VPNs and PPP providers dont require
416 all possible secrets) this flag indicates that the specific
417 secret is not required.
425 <emphasis role="strong">Action:</emphasis> user interface code which
426 handles entry of connection secrets should be updated to read and set
427 secret flags. For example, code that creates new VPN connections may want
428 to set the "agent-owned" flag to ensure that the user's VPN password is
429 not available to all users. EAP-TLS and VPN interface code might add a
430 checkbox that toggles the "not saved" bit to indicate that the
431 password/PIN code should be requested from a hardware token each time it
437 <title>Deprecated Methods Removed</title>
439 A few methods and signals of the <literal>org.freedesktop.NetworkManager</literal>
440 interface deprecated in version 0.7 have been removed. All the
441 replacement methods and signals have existed since version 0.7 and so are
442 not new to this version of NetworkManager, but some older programs may
443 be using removed items. The following table lists the removed items and
448 <row><entry>Removed Item</entry><entry>Replacement</entry></row>
452 <entry><screen>StateChange signal</screen></entry>
454 Use the <literal>StateChanged</literal> signal, which has the
459 <entry><screen>sleep() and wake() methods</screen></entry>
461 Use the <literal>Sleep()</literal> method instead, which takes
462 a boolean argument indicating whether NetworkManager should
463 go to sleep or wake up.
471 <emphasis role="strong">Action:</emphasis> update code to use these
472 replacement methods and properties where it used old deprecated ones