docs/api/migrating-to-09.xml

   1 <?xml version="1.0"?>
   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'">
   5 ]>
   6 <chapter id="ref-migrating">
   7   <title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title>
   8
   9   <para>
  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.
  17   </para>
  18
  19   <section>
  20     <title>Architecture and D-Bus API Changes in 0.9</title>
  21
  22     <para>
  23       This section details the architectural and D-Bus API changes in
  24       NetworkManager 0.9.
  25     </para>
  26
  27     <section>
  28     <title>Elimination of the User Settings Service</title>
  29     <para>
  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.
  40     </para>
  41     <para>
  42       Elimination of the user settings service provides the following advantages
  43       for clients of NetworkManager:
  44       <itemizedlist>
  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>
  51       </itemizedlist>
  52     </para>
  53     <para>
  54       With this change, D-Bus methods that previously took a "service name"
  55       argument (like
  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.
  59     </para>
  60     <para>
  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.
  68     </para>
  69     </section>
  70
  71     <section>
  72     <title>User Secret Agents</title>
  73     <para>
  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.
  88     </para>
  89     <para>
  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.
  96     </para>
  97     <para>
  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.
 105     </para>
 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.
 111     <para>
 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.
 117     </para>
 118     </section>
 119
 120     <section>
 121     <title>Settings Service Interface Changes</title>
 122     <para>
 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>.
 131     </para>
 132     <para>
 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.
 145     </para>
 146     <para>
 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.
 155     </para>
 156     </section>
 157
 158     <section>
 159     <title>Connection Object Interface Changes</title>
 160     <para>
 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>
 165       from the previous
 166       <literal>org.freedesktop.NetworkManagerSettings.Connection</literal>.
 167     </para>
 168     <para>
 169       Additionally, the
 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.
 178     </para>
 179     <para>
 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>
 188       method.
 189     </para>
 190     </section>
 191
 192     <section>
 193     <title>Permissions Methods Consolidation</title>
 194     <para>
 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:
 198       <itemizedlist>
 199         <listitem>
 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
 203           hostname
 204         </listitem>
 205         <listitem>
 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.
 210         </listitem>
 211       </itemizedlist>
 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.
 216     </para>
 217     <para>
 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:
 221       <table>
 222         <tgroup cols="2">
 223           <thead>
 224             <row><entry>Old bitfield value</entry><entry>New permission name</entry></row>
 225           </thead>
 226           <tbody>
 227             <row>
 228               <entry><screen>0x1 (connection-modify)</screen></entry>
 229               <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.
 233               </entry>
 234             </row>
 235             <row>
 236               <entry><screen>0x2 (wifi-share-protected)</screen></entry>
 237               <entry>
 238                 <literal>org.freedesktop.NetworkManager.wifi.share.protected</literal>
 239               </entry>
 240             </row>
 241             <row>
 242               <entry><screen>0x4 (wifi-share-open)</screen></entry>
 243               <entry>
 244                 <literal>org.freedesktop.NetworkManager.wifi.share.open</literal>
 245               </entry>
 246             </row>
 247             <row>
 248               <entry><screen>0x8 (hostname-modify)</screen></entry>
 249               <entry>
 250                 <literal>org.freedesktop.NetworkManager.settings.modify.hostname</literal>
 251               </entry>
 252             </row>
 253           </tbody>
 254         </tgroup>
 255       </table>
 256     </para>
 257     <para>
 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>.
 262     </para>
 263     </section>
 264
 265     <section>
 266     <title>AddConnection Returns Object Path of New Connection</title>
 267     <para>
 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.
 275     </para>
 276     <para>
 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.
 280     </para>
 281     </section>
 282
 283     <section>
 284     <title>Support for WiMAX Devices</title>
 285     <para>
 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
 295       WiMAX network.
 296     </para>
 297     <para>
 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.
 303     </para>
 304     </section>
 305
 306     <section>
 307     <title>New Device States</title>
 308     <para>
 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.
 312     </para>
 313     <para>
 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.
 318     </para>
 319     </section>
 320
 321     <section>
 322     <title>New Active Connection State</title>
 323     <para>
 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.
 328     </para>
 329     <para>
 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.
 334     </para>
 335     </section>
 336
 337     <section>
 338     <title>Consolidated Modem Devices</title>
 339     <para>
 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.
 353     </para>
 354     <para>
 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
 358       into the
 359       <ulink url="spec.html#org.freedesktop.NetworkManager.Device.Modem">
 360       <literal>org.freedesktop.NetworkManager.Device.Modem</literal></ulink>
 361       interface in the future.
 362     </para>
 363     <para>
 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
 369       status.
 370     </para>
 371     </section>
 372
 373     <section>
 374     <title>Secret Property Flags</title>
 375     <para>
 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
 380       following values:
 381       <table>
 382         <tgroup cols="2">
 383           <thead>
 384             <row><entry>Flag Value</entry><entry>Meaning</entry></row>
 385           </thead>
 386           <tbody>
 387             <row>
 388               <entry><screen>0x00 (none)</screen></entry>
 389               <entry>
 390                 NetworkManager is responsible for providing and storing this
 391                 secret (default)
 392               </entry>
 393             </row>
 394             <row>
 395               <entry><screen>0x01 (agent-owned)</screen></entry>
 396               <entry>
 397                 A user secret agent is responsible for providing and storing
 398                 this secret; when it is required agents will be asked to
 399                 retrieve it
 400               </entry>
 401             </row>
 402             <row>
 403               <entry><screen>0x02 (not saved)</screen></entry>
 404               <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.
 409               </entry>
 410             </row>
 411             <row>
 412               <entry><screen>0x04 (not required)</screen></entry>
 413               <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.
 418               </entry>
 419             </row>
 420           </tbody>
 421         </tgroup>
 422       </table>
 423     </para>
 424     <para>
 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
 432       is required.
 433     </para>
 434     </section>
 435
 436     <section>
 437     <title>Deprecated Methods Removed</title>
 438     <para>
 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
 444       their replacements:
 445       <table>
 446         <tgroup cols="2">
 447           <thead>
 448             <row><entry>Removed Item</entry><entry>Replacement</entry></row>
 449           </thead>
 450           <tbody>
 451             <row>
 452               <entry><screen>StateChange signal</screen></entry>
 453               <entry>
 454                 Use the <literal>StateChanged</literal> signal, which has the
 455                 same arguments.
 456               </entry>
 457             </row>
 458             <row>
 459               <entry><screen>sleep() and wake() methods</screen></entry>
 460               <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.
 464               </entry>
 465             </row>
 466           </tbody>
 467         </tgroup>
 468       </table>
 469     </para>
 470     <para>
 471       <emphasis role="strong">Action:</emphasis> update code to use these
 472       replacement methods and properties where it used old deprecated ones
 473     </para>
 474     </section>
 475
 476   </section>
 477
 478 </chapter>