diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index baf21123c..158eb38f6 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -63,6 +63,7 @@ MKTMPL_OPTIONS= content_files = \ version.xml \ settings-spec.xml \ + migrating-to-09.xml \ $(NULL) include $(top_srcdir)/gtk-doc.make diff --git a/docs/api/migrating-to-09.xml b/docs/api/migrating-to-09.xml new file mode 100644 index 000000000..725685298 --- /dev/null +++ b/docs/api/migrating-to-09.xml @@ -0,0 +1,157 @@ + + +]> +
+ Migrating from NetworkManager 0.8 to NetworkManager 0.9 + + + 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. + + +
+ Architecture and D-Bus API Changes in 0.9 + + + This section details the architectural and D-Bus API changes in + NetworkManager 0.9. + + +
+ Elimination of the User Settings Service + + 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. + + + Elimination of the user settings service provides the following advantages + for clients of NetworkManager: + + Simpler discovery of network configuration and change tracking + Simpler storage of user-level network secrets by control applets + Correct operation of fast-user switching and multi-seat configurations + More granular network connection permissions for system administrators + Connections are now system-wide by default (unless restricted by the user or system administrator) + Easier deployment of user-specific connections (ie, VPNs) + + + + Action: 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. + +
+ +
+ Settings Service Name Change + + With the elimination of the user settings service, the old + org.freedesktop.NetworkManagerUserSettings and + org.freedesktop.NetworkManagerSystemSettings D-Bus + service names are no longer used. Instead NetworkManager provides the + settings service using its own D-Bus service name, + org.freedesktop.NetworkManager. The object path of + the settings service remains unchanged. + + + Action: change the service name that + your application uses to request system network settings to + org.freedesktop.NetworkManager. + +
+ +
+ Permissions Methods Consolidation + + 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: + + + org.freedesktop.NetworkManagerSettings.System.GetPermissions + which returned a bitfield of operations the caller was allowed to + perform related to modify system network settings and the machine + hostname + + + org.freedesktop.NetworkManager.GetPermissions 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. + + + These two calls have been consolidated into an enhanced + org.freedesktop.NetworkManager.GetPermissions call that + uses the same arguments, but includes all permissions, including those which + the settings service used to handle. + + + With this change, the bitfield items from + org.freedesktop.NetworkManagerSettings.System.GetPermissions + are now string-based permissions. The mapping is as follows: + + + + Old bitfield valueNew permission name + + + + 0x1 (connection-modify) + + org.freedesktop.NetworkManager.settings.modify.system + or org.freedesktop.NetworkManager.settings.modify.system + depending on the permissions of the connection. + + + + 0x2 (wifi-share-protected) + + org.freedesktop.NetworkManager.wifi.share.protected + + + + 0x4 (wifi-share-open) + + org.freedesktop.NetworkManager.wifi.share.open + + + + 0x8 (hostname-modify) + + org.freedesktop.NetworkManager.settings.modify.hostname + + + + +
+ + + Action: 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 + org.freedesktop.NetworkManagerSettings.System.GetPermissions. + +
+ +
+ +
diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 7e121cc6d..4381bb56f 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -111,6 +111,15 @@ + + Migrating from Previous Versions of NetworkManager + + This part describes changes you need to make in programs that + use older versions of NetworkManager. + + + + Index