Imported Upstream version 0.8.999 upstream/0.8.999

1 files changed, 476 insertions, 0 deletions

diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml
new file mode 100644
index 00000000..910c1369
--- /dev/null
+++ b/docs/api/migrating-to-09.xml
@@ -0,0 +1,476 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<chapter id="ref-migrating">
+  <title>Migrating from NetworkManager 0.8 to NetworkManager 0.9</title>
+
+  <para>
+    NetworkManager 0.9 is a new major version of NetworkManager that breaks
+    both API and ABI compared to previous versions.  These changes are
+    intended to make communication with NetworkManager much simpler, especially
+    for network control and configuration programs.  Thankfully, most changes
+    are not difficult to implement, and the advantages of the simpler
+    architecture of NetworkManager 0.9 greatly outweight the effort of
+    updating client programs.
+  </para>
+
+  <section>
+    <title>Architecture and D-Bus API Changes in 0.9</title>
+
+    <para>
+      This section details the architectural and D-Bus API changes in
+      NetworkManager 0.9.
+    </para>
+
+    <section>
+    <title>Elimination of the User Settings Service</title>
+    <para>
+      Previously there were two "settings services", or D-Bus services that
+      provided and saved network configuration information.  NetworkManager
+      owned the "system" settings service, and one user-level applet owned the
+      "user" settings service.  Now, the "user" settings service has been
+      eliminated, so clients only have to track one D-Bus service to read and
+      update network configuration.  The functionality of the old user settings
+      service has been replaced with a "permissions" key on each connection
+      object to preserve the ability to restrict which users can use the
+      connection, and with a "secret agent" D-Bus API for user-session-level
+      secure storage of network secrets and passwords.
+    </para>
+    <para>
+      Elimination of the user settings service provides the following advantages
+      for clients of NetworkManager:
+      <itemizedlist>
+        <listitem>Simpler discovery of network configuration and change tracking</listitem>
+        <listitem>Simpler storage of user-level network secrets by control applets</listitem>
+        <listitem>Correct operation of fast-user switching and multi-seat configurations</listitem>
+        <listitem>More granular network connection permissions for system administrators</listitem>
+        <listitem>Connections are now system-wide by default (unless restricted by the user or system administrator)</listitem>
+        <listitem>Easier deployment of user-specific connections (ie, VPNs)</listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      With this change, D-Bus methods that previously took a "service name"
+      argument (like
+      <literal>org.freedesktop.NetworkManager.ActivateConnection</literal>) and
+      objects with service name properties (like ActiveConnection objects) no
+      longer have those arguments or properties.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> if you develop a network control
+      applet that talks to NetworkManager and used to provide a user settings
+      service, you can eliminate that code and rely on NetworkManager for all
+      storage of network configuration.  Your applet should now implement the
+      Secret Agent D-Bus API (see below) to store user-specific secrets, and
+      add legacy user-specific configuration to NetworkManager when run.  More
+      information about both these changes follows.
+    </para>
+    </section>
+
+    <section>
+    <title>User Secret Agents</title>
+    <para>
+      Even with the elimination of the user settings service, in some cases it
+      is still desirable to store secrets in the user's session and not in
+      system-wide storage (and thus available to all users).  To allow this
+      functionality the concept of agents has been introduced.  Using the new
+      <ulink url="spec.html#org.freedesktop.NetworkManager.AgentManager">
+      <literal>org.freedesktop.NetworkManager.AgentManager</literal></ulink>
+      D-Bus interface provided by NetworkManager, user applications can register
+      themselves as "secret agents", ie programs capable of saving and providing
+      secrets to NetworkManager.  The agent should export the
+      <ulink url="spec.html#org.freedesktop.NetworkManager.SecretAgent">
+      <literal>org.freedesktop.NetworkManager.SecretAgent</literal></ulink>
+      D-Bus interface, but should NOT claim a bus name on the system or session
+      bus.  Instead, NetworkManager talks to the agent directly over the D-Bus
+      connection which the agent used to register itself.
+    </para>
+    <para>
+      Each agent must send a unique identifier to NetworkManager when it
+      registers.  This identifier must follow certain rules (see the NM D-Bus
+      API documentation for more details) but looks essentially the same as
+      a D-Bus service name.  Only one agent using a given identifier may be
+      registered at the same time.  The agent is automatically unregistered
+      if it disconnects from D-Bus or exits.
+    </para>
+    <para>
+      When NetworkManager requires secrets during the attempt to connect to a
+      network, and no secrets are available from the internal settings service,
+      NetworkManager queries each registered agent for secrets.  Agents that
+      are in "active" user sessions (as determined by ConsoleKit) are preferred
+      over inactive ones.  Only agents belonging to users who have permission
+      to view and modify the connection are queried.  For more information on
+      connection permissions, see below.
+    </para>
+      When secrets are requested, the agent is also sent a set of flags that
+      modify the behavior of the request.  By default, the agent should never
+      attempt to query the user for secrets, but should simply return any
+      available saved secrets.  Other flags allow the agent to explicitly
+      request new secrets from the user.
+    <para>
+      <emphasis role="strong">Action:</emphasis> the parts of a previous user
+      settings service that handled secrets may be easily repurposed as the bulk
+      of the implementation of a secret agent.  The agent is sent all available
+      connection settings, and from those should be able to retrieve or save
+      any saved user secrets, or to request new secrets from the user.
+    </para>
+    </section>
+
+    <section>
+    <title>Settings Service Interface Changes</title>
+    <para>
+      With the elimination of the user settings service, the old
+      <literal>org.freedesktop.NetworkManagerUserSettings</literal> and
+      <literal>org.freedesktop.NetworkManagerSystemSettings</literal> D-Bus
+      service names are no longer used.  Instead NetworkManager provides the
+      settings service using its own D-Bus service name,
+      <literal>org.freedesktop.NetworkManager</literal>.  The object path of
+      the settings service remains unchanged.
+    </para>
+    <para>
+      Additionally, the D-Bus interface of the settings service has changed
+      to <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
+      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> from
+      the old interface name of
+      <literal>org.freedesktop.NetworkManagerSettings</literal>, and the old
+      <literal>org.freedesktop.NetworkManagerSettings.System</literal>
+      interface has been merged into the new
+      <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
+      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink> interface
+      as the split no longer made sense. This includes the
+      <literal>SaveHostname</literal> method and the <literal>Hostname</literal>
+      and <literal>CanModify</literal> properties.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> change the service name that
+      your application uses to request system network settings to
+      <literal>org.freedesktop.NetworkManager</literal>, and update the D-Bus
+      interface that codes uses to talk to the settings service to
+      <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
+      <literal>org.freedesktop.NetworkManager.Settings</literal></ulink>.
+      Listen for hostname changes using the new interface name as well.
+    </para>
+    </section>
+
+    <section>
+    <title>Connection Object Interface Changes</title>
+    <para>
+      Consistent with the interface changes to the Settings object, the
+      Connection object's D-Bus interface has changed to
+      <ulink url="spec.html#org.freedesktop.NetworkManager.Settings.Connection">
+      <literal>org.freedesktop.NetworkManager.Settings.Connection</literal></ulink>
+      from the previous 
+      <literal>org.freedesktop.NetworkManagerSettings.Connection</literal>.
+    </para>
+    <para>
+      Additionally, the
+      <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
+      signal of the Connection object no longer includes the updated settings
+      data argument, as that might allow users who are not authorized to
+      view the connection details to do so.  Instead, when a client receives the
+      Updated signal, it should requery the Connection's settings with the
+      <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
+      method.  If the client receives an error as a result of this method call,
+      it should assume the connection has been deleted.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> where code manipulates
+      Connection objects, update the D-Bus interface that code uses to be
+      <literal>org.freedesktop.NetworkManager.Settings.Connection</literal>.
+      Additionally, code that listens for the
+      <literal>org.freedesktop.NetworkManager.Settings.Connection.Updated</literal>
+      signal should no longer expect the new settings data as an argument, but
+      instead should request the new settings data using the
+      <literal>org.freedesktop.NetworkManager.Settings.Connection.GetSettings</literal>
+      method.
+    </para>
+    </section>
+
+    <section>
+    <title>Permissions Methods Consolidation</title>
+    <para>
+      Previously there were two D-Bus method calls to retrieve the list of
+      operations that a user client could perform, and two signals notifying
+      callers that they should recheck permissions.  Those two calls were:
+      <itemizedlist>
+        <listitem>
+          <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
+          which returned a bitfield of operations the caller was allowed to
+          perform related to modify system network settings and the machine
+          hostname
+        </listitem>
+        <listitem>
+          <literal>org.freedesktop.NetworkManager.GetPermissions</literal> which
+          returned a dictionary mapping permission names to result strings like
+          "yes", "auth", or "no", relating to network control permissions like
+          the ability to enable or disable WiFi.
+        </listitem>
+      </itemizedlist>
+      These two calls have been consolidated into an enhanced
+      <literal>org.freedesktop.NetworkManager.GetPermissions</literal> call that
+      uses the same arguments, but includes all permissions, including those which
+      the settings service used to handle.
+    </para>
+    <para>
+      With this change, the bitfield items from
+      <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>
+      are now string-based permissions.  The mapping is as follows:
+      <table>
+        <tgroup cols="2">
+          <thead>
+            <row><entry>Old bitfield value</entry><entry>New permission name</entry></row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><screen>0x1 (connection-modify)</screen></entry>
+              <entry>
+                <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
+                or <literal>org.freedesktop.NetworkManager.settings.modify.system</literal>
+                depending on the permissions of the connection.
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x2 (wifi-share-protected)</screen></entry>
+              <entry>
+                <literal>org.freedesktop.NetworkManager.wifi.share.protected</literal>
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x4 (wifi-share-open)</screen></entry>
+              <entry>
+                <literal>org.freedesktop.NetworkManager.wifi.share.open</literal>
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x8 (hostname-modify)</screen></entry>
+              <entry>
+                <literal>org.freedesktop.NetworkManager.settings.modify.hostname</literal>
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> modify handling of existing
+      code that checks permissions to recognize the new permissions names for
+      old system settings permissions, and remove code that used to call
+      <literal>org.freedesktop.NetworkManagerSettings.System.GetPermissions</literal>.
+    </para>
+    </section>
+
+    <section>
+    <title>AddConnection Returns Object Path of New Connection</title>
+    <para>
+      The <ulink url="spec.html#org.freedesktop.NetworkManager.Settings">
+      <literal>org.freedesktop.NetworkManager.Settings.AddConnection</literal>
+      </ulink> method call now returns the object path of the newly added
+      connection. Previously, if code wanted to manipulate a connection
+      post-addition, it had to wait for the new connection to be announced via
+      the NewConnection signal by matching connection UUIDs.  Now the object
+      path is returned and this workaround is no longer required.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> update code that adds new
+      connections to handle the object path returned from AddConnection, and
+      remove workarounds for finding the new connection via signals.
+    </para>
+    </section>
+
+    <section>
+    <title>Support for WiMAX Devices</title>
+    <para>
+      NetworkManager now supports Intel WiMAX mobile broadband devices.  A
+      corresponding device type (<literal>NM_DEVICE_TYPE_WIMAX</literal>) and
+      a new <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax">
+      <literal>org.freedesktop.NetworkManager.Device.WiMax</literal></ulink>
+      D-Bus interface have been added.  Furthermore, to support connection to
+      different WiMAX Network Service Providers (NSPs) the
+      <ulink url="spec.html#org.freedesktop.NetworkManager.Device.WiMax.Nsp">
+      <literal>org.freedesktop.NetworkManager.Device.WiMax.Nsp</literal></ulink>
+      interface has been added to access information about each available
+      WiMAX network.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> update code that handles
+      devices and/or displays status to users to recognize the new device type,
+      and to display available WiMAX NSPs similar to how WiFi Access Points
+      are displayed. Also update code that creates new connections to allow
+      creation of new WiMAX connections.
+    </para>
+    </section>
+
+    <section>
+    <title>New Device States</title>
+    <para>
+      A few <ulink url="spec.html#type-NM_DEVICE_STATE">new device states</ulink>
+      have been added, and all device states have been renumbered for flexibility.
+      The new devices states IP_CHECK, SECONDARIES, and DEACTIVATING.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> where code checks device state
+      or shows UI indication of the device's state, make sure the new device
+      states are processed correctly, and that code in switch()-type statements
+      is updated to handle the new states.
+    </para>
+    </section>
+
+    <section>
+    <title>New Active Connection State</title>
+    <para>
+      Along with the new device states, an
+      <ulink url="spec.html#type-NM_ACTIVE_CONNECTION_STATE">additional
+      ActiveConnection state</ulink> has been added: DEACTIVATING.  This state
+      is entered when the connection is being torn down and deactivated.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> where code checks active
+      connection states or shows UI indication of active connection states, make
+      sure the DEACTIVATING state is processed correctly, and that code in
+      switch()-type statements is updated to handle it.
+    </para>
+    </section>
+
+    <section>
+    <title>Consolidated Modem Devices</title>
+    <para>
+      Many new mobile broadband devices support multiple access families, like
+      Qualcomm Gobi cards (CDMA/EVDO and GSM/UMTS), or multi-mode EVDO/LTE
+      or UMTS/LTE modems like the Pantech UML290.  The previous hard split
+      between CDMA/EVDO and GSM/UMTS device classes was not flexible enough to
+      deal with these new multi-mode devices.  Thus the previously separate
+      CDMA and GSM device classes have been combined into a single Modem
+      device class, which exposes both hardware "ModemCapabilities" and
+      runtime "CurrentCapabilities" which represent generic access technology
+      families like CDMA/EVDO, GSM/UMTS, and LTE which the device supports.
+      ModemCapabilities indicate all the access technology families which the
+      modem is capable of supporting, while CurrentCapabilities indicate the
+      immediate access technology families the device supports without reloading
+      the firmware and thus restarting the device.
+    </para>
+    <para>
+      Along with this change, the
+      <literal>org.freedesktop.NetworkManager.Device.Serial</literal>
+      interface has been removed as it's functionality will be incorporated
+      into the 
+      <ulink url="spec.html#org.freedesktop.NetworkManager.Device.Modem">
+      <literal>org.freedesktop.NetworkManager.Device.Modem</literal></ulink>
+      interface in the future.
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> combine code that checks for
+      the old CDMA and GSM device types, and instead handle the new Modem device
+      type.  Where behavior must change based on the capabilities of the device,
+      check the CurrentCapabilities device property to determine whether to
+      treat the device as CDMA, GSM, or LTE for purposes of configuration and
+      status.
+    </para>
+    </section>
+
+    <section>
+    <title>Secret Property Flags</title>
+    <para>
+      In the Connection object's configuration properties, each setting's secret
+      properties (like WiFi passphrases, or public key passwords, etc) now has
+      an associated "flags" property that changes how NetworkManager treats the
+      secret.  The "flags" property is a bitfield of one or more of the
+      following values:
+      <table>
+        <tgroup cols="2">
+          <thead>
+            <row><entry>Flag Value</entry><entry>Meaning</entry></row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><screen>0x00 (none)</screen></entry>
+              <entry>
+                NetworkManager is responsible for providing and storing this
+                secret (default)
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x01 (agent-owned)</screen></entry>
+              <entry>
+                A user secret agent is responsible for providing and storing
+                this secret; when it is required agents will be asked to
+                retrieve it
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x02 (not saved)</screen></entry>
+              <entry>
+                The secret is not saved, and should be requested each time it
+                is required.  Used for OTP/token configurations where the
+                secret changes periodically, or if the user simply wants to
+                manually enter the secret each time.
+              </entry>
+            </row>
+            <row>
+              <entry><screen>0x04 (not required)</screen></entry>
+              <entry>
+                In situations where it cannot be automatically determined that
+                the secret is required (some VPNs and PPP providers dont require
+                all possible secrets) this flag indicates that the specific
+                secret is not required.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> user interface code which
+      handles entry of connection secrets should be updated to read and set
+      secret flags.  For example, code that creates new VPN connections may want
+      to set the "agent-owned" flag to ensure that the user's VPN password is
+      not available to all users.  EAP-TLS and VPN interface code might add a
+      checkbox that toggles the "not saved" bit to indicate that the
+      password/PIN code should be requested from a hardware token each time it
+      is required.
+    </para>
+    </section>
+
+    <section>
+    <title>Deprecated Methods Removed</title>
+    <para>
+      A few methods and signals of the <literal>org.freedesktop.NetworkManager</literal>
+      interface deprecated in version 0.7 have been removed.  All the
+      replacement methods and signals have existed since version 0.7 and so are
+      not new to this version of NetworkManager, but some older programs may
+      be using removed items.  The following table lists the removed items and
+      their replacements:
+      <table>
+        <tgroup cols="2">
+          <thead>
+            <row><entry>Removed Item</entry><entry>Replacement</entry></row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><screen>StateChange signal</screen></entry>
+              <entry>
+                Use the <literal>StateChanged</literal> signal, which has the
+                same arguments.
+              </entry>
+            </row>
+            <row>
+              <entry><screen>sleep() and wake() methods</screen></entry>
+              <entry>
+                Use the <literal>Sleep()</literal> method instead, which takes
+                a boolean argument indicating whether NetworkManager should
+                go to sleep or wake up.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </para>
+    <para>
+      <emphasis role="strong">Action:</emphasis> update code to use these
+      replacement methods and properties where it used old deprecated ones
+    </para>
+    </section>
+
+  </section>
+
+</chapter>