479 lines
22 KiB
XML
479 lines
22 KiB
XML
<?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 has also changed to
|
|
<literal>/org/freedesktop/NetworkManager/Settings</literal>.
|
|
</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 and
|
|
object path that your application uses to request system network settings
|
|
to <literal>org.freedesktop.NetworkManager</literal> and
|
|
<literal>/org/freedesktop/NetworkManager/Settings</literal> respectively,
|
|
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>
|