Update README.Debian for the latest changes.

2 files changed, 55 insertions, 70 deletions

diff --git a/debian/changelog b/debian/changelog
index 7cab49cd..ac3c28fd 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -21,6 +21,7 @@ network-manager (0.9.4.0-9) UNRELEASED; urgency=low
     network-manager package afterwards, show a warning in postinst if we
     find any interface configurations in /etc/network/interfaces.
     (Closes: #688355, #690987, #606268)
+  * Update README.Debian for the latest changes.
 
  -- Michael Biebl <biebl@debian.org>  Mon, 28 Jan 2013 18:25:50 +0100
 
diff --git a/debian/network-manager.README.Debian b/debian/network-manager.README.Debian
index 43fad371..f11dfa72 100644
--- a/debian/network-manager.README.Debian
+++ b/debian/network-manager.README.Debian
@@ -1,62 +1,36 @@
-NetworkManager consists of two parts: one is on the system level daemon that
-manages the connections and gathers information about new networks. The other
-is a systray applet that users can use to interact with the NetworkManager
-daemon.
-
-Security
-~~~~~~~~
-
-To allow users to connect to the NetworkManager daemon they have to be in the
-group "netdev". If you want to add a user to group "netdev" use the command
-"adduser username netdev" or one of the graphical user management frontends.
-After that you have to reload D-Bus with the command "service dbus reload".
-
-Alternatively you can install the "consolekit" package which will grant access
-for all locally logged in users.
-
-
-Managed vs. Unmanaged mode and /etc/network/interfaces
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Devices listed in /etc/network/interfaces _will_ be managed by NetworkManager
-unless the ifupdown system-config-setting is enabled and is setup to run
-in "Unmanaged mode".
-
-The config to select unmanaged/managed mode is in
-/etc/NetworkManager/NetworkManager.conf:
-
-  [ifupdown]
-  managed=true/false
-
-Unmanaged mode will make NetworkManager not touch any wired/wireless device
-matching an interface name configured in /etc/network/interfaces.
-
-Managed mode will make NetworkManager manage all devices and will make
-NetworkManager honour all dhcp and static configurations for wired and
-wireless devices.
-
-After modifying /etc/NetworkManager/NetworkManager.conf _or_
-/etc/network/interfaces you may want to tell NetworkManager about the changes
-by running "service network-manager restart".
-
-System settings
-~~~~~~~~~~~~~~~
-
-System settings allow to setup network connections which are available at
-boot time, before login and to all users of the machine. The settings are
-stored in a system-wide location.
-There are plugins for different configuration sources.
-By default the ifupdown and keyfile plugin are enabled, see
-/etc/NetworkManager/NetworkManager.conf:
-
-  [main]
-  plugins=ifupdown,keyfile
-
-The ifupdown plugin is read-only and reads the native ifupdown configuration
-file /etc/network/interfaces.
-
-The keyfile plugin is read-write. The configuration files for network
-connections are stored in /etc/NetworkManager/system-connections/.
+NetworkManager is a set of co-operative tools that make networking simple and
+straightforward. Whether WiFi, wired, 3G, or Bluetooth, NetworkManager allows
+you to quickly move from one network to another.
+
+It has two components:
+
+1. a system level service which manages connections and reports network changes
+2. a graphical desktop applet which allows the user to manipulate network
+   connections. The nmcli tool provides similar functionality on the command
+   line.
+
+
+system connections and security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In NetworkManager version 0.9, network connections are stored as keyfiles in
+the /etc/NetworkManager/system-connections/ directory.
+When creating new wireless or wired connections, they are by default
+system-owned (i.e. available to everyone) and the secrets (e.g WPA-PSK or WEP
+key) are stored as plain text in the corresponding connection configuration
+file. The advantage of system connections is, that they can be active before a
+user has logged in and they are active across user sessions.
+Modifying or creating such system-owned connections requires admin privileges.
+To avoid prompts for the root/admin password, NetworkManager ships a PolicyKit
+configuration file which grants everyone in group "netdev" or "sudo" the
+privilege to modify a system connection without prior authentication. Adding a
+user to group sudo grants him root-like privileges though. If that is not
+wanted, you can choose to add him to group netdev instead.
+If the user should not have the privilege to add and modify system connections
+don't add him to either groups.
+In that case, the user clients (like nm-applet) will default to creating
+user-owned connections where the secrets are stored in the user keyring.
+VPN and 3G type connections are by default also user-owned.
 
 For more information see NetworkManager.conf(5) or
 http://live.gnome.org/NetworkManager/SystemSettings
@@ -64,19 +38,29 @@ http://live.gnome.org/NetworkManager/SystemSettings
 The keyfile specification is available at
 http://projects.gnome.org/NetworkManager/developers/settings-spec-08.html
 
+unmanaged devices and /etc/network/interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Network devices which are configured in /etc/network/interfaces will typically
+be managed by ifupdown. Such devices will by default be marked as "unmanaged"
+in NetworkManager.
 
-Dial-up configuration
-~~~~~~~~~~~~~~~~~~~~~
+You can tell NetworkManager to read and use the network configuration from
+/etc/network/interfaces by editing /etc/NetworkManager/NetworkManager.conf
+and changing the configuration as follows:
+
+  [ifupdown]
+  managed=true
 
-Your dialup configurations can now be done in nm-connection-editor.
-Because of that /etc/network/interfaces configurations are considered "legacy"
-from a network manager point of view.
+After modifying /etc/NetworkManager/NetworkManager.conf or
+/etc/network/interfaces you need to restart the NetworkManager service via
+"service network-manager restart".
 
-However, if you want to use your /etc/network/interfaces configuration make
-sure that you have the ifupdown plugin in "Unmanaged mode" and take care that
-the used wired/wireless device is also configured in /etc/network/interfaces.
+It needs to be considered though that the network interface will also still be
+managed by ifupdown. This can lead to unexpected behaviour if two network
+configuration systems manage the same device.
 
-Note that NetworkManager 0.7 will not provide UI hooks to up and down ppp
-connections managed outside of NetworkManager itself (not that it ever worked
-nicely before).
+If you want to have a network interface managed by NetworkManager it is thus
+recommended to manually remove any configuration for that interface from
+/etc/network/interfaces.