Update the readme

git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@4311 4912f4e0-d625-0410-9fb7-b9a5a253dbdc

1 files changed, 74 insertions, 52 deletions

diff --git a/README b/README
index c56641f18f..1d7222c084 100644
--- a/README
+++ b/README
@@ -1,55 +1,77 @@
-THEORY OF OPERATION:
+Networking that Just Works
+--------------------------
 
 NetworkManager attempts to keep an active network connection available at all
 times.  The point of NetworkManager is to make networking configuration and
-setup as painless and automatic as possible.  If using DHCP, NetworkManager is
-_intended_ to replace default routes, obtain IP addresses from a DHCP server,
-and change nameservers whenever it sees fit.  In effect, the goal of
-NetworkManager is to make networking Just Work.  If you have special needs,
-we'd like to hear about them, but understand that NetworkManager is not
-intended to serve the needs of all users.
-
-
-From a list of all adapters currently installed on the system, NetworkManager
-will first try a wired and then a wireless adapter.  Wireless adapters that
-support wireless scanning are preferred over ones that cannot.  NetworkManager
-does not try to keep a connection up as long as possible, meaning that plugging
-into a wired network will switch the connection to the wired network away from
-the wireless one.
-
-For wireless networking support, NetworkManager keeps a list of wireless
-networks, the preferred list.  Preferred Networks are wireless networks that
-the user has explicitly made NetworkManager associate with at some previous
-time.  So if the user walks into a Starbucks and explicitly asks NetworkManager
-to associate with that Starbucks network, NetworkManager will remember the
-Starbucks network information from that point on.  Upon returning to that
-Starbucks, NetworkManager will attempt to associate _automatically_ with the
-Starbucks network since it is now in the Preferred Networks list.  The point of
-this is to ensure that only the user can determine which wireless networks to
-associate with, and that the user is aware which networks are security risks
-and which are not.
-
-
-STRUCTURE:
-
-NetworkManager runs as a root-user system level daemon, since it
-must manipulate hardware directly.  It communicates over DBUS with a
-desktop-level per-user process, nm-applet.  Since Preferred Networks are
-user-specific, there must be some mechanism of getting this information
-per-user.  NetworkManager cannot store that information as it is user-specific,
-and therefore communicates over DBUS to the user daemon which provides those
-lists.  NetworkManager also provides an API over DBUS for any DBUS-aware
-application to determine the current state of the network, including available
-wireless networks the computer is aware of and specific details about those
-networks.  This API also provides the means for forcing NetworkManager to
-associate with a specific wireless network.  Use of DBUS allows separation of
-NetworkManager, which requires no user-interface, and the parts of the user
-interface which might be desktop environment specific.
-
-The nm-applet provides a DBUS service called NetworkManagerInfo, which should
-provide to NetworkManager the Preferred Networks lists upon request.  It also
-should be able to display a dialog to retrieve a WEP/WPA key or passphrase from
-the user when NetworkManager requests it.  The GNOME version of
-NetworkManagerInfo, for example, stores Preferred Networks in GConf and
-WEP/WPA keys in gnome-keyring, and proxies that information to NetworkManager
-upon request.
+setup as painless and automatic as possible.  NetworkManager is intended to
+replace default route, replace other routes, set IP addresses, and in general
+configure networking as NM sees fit (with the possibility of manual override as
+necessary).  In effect, the goal of NetworkManager is to make networking Just
+Work with a minimum of user hassle, but still allow customization and a high
+level of manual network control.  If you have special needs, we'd like to hear
+about them, but understand that NetworkManager is not intended for every
+use-case.
+
+NetworkManager will attempt to keep every network device in the system up and
+active, as long as the device is available for use (has a cable plugged in,
+the killswitch isn't turned on, etc).  Network connections can be set to
+'autoconnect', meaning that NetworkManager will make that connection active
+whenever it and the hardware is available.
+
+"Settings services" store lists of user- or administrator-defined "connections",
+which contain all the settings and parameters required to connect to a specific
+network.  NetworkManager will _never_ activate a connection that is not in this
+list, or that the user has not directed NetworkManager to connect to.
+
+
+How it works:
+
+The NetworkManager daemon runs as a privileged service (since it must access
+and control hardware), but provides a D-Bus interface on the system bus to
+allow for fine-grained control of networking.  NetworkManager does not store
+connections or settings, it is only the mechanism by which those connections
+are selected and activated.
+
+To store pre-defined network connections, two separate services, the "system
+settings service" and the "user settings service" store connection information
+and provide these to NetworkManager, also via D-Bus.  Each settings service
+can determine how and where it persistently stores the connection information;
+for example, the GNOME applet stores its configuration in GConf, and the system
+settings service stores it's config in distro-specific formats, or in a distro-
+agnostic format, depending on user/administrator preference.
+
+A variety of other system services are used by NetworkManager to provide
+network functionality: wpa_supplicant for wireless connections and 802.1x
+wired connections, pppd for PPP and mobile broadband connections, DHCP clients
+for dynamic IP addressing, dnsmasq for proxy nameserver and DHCP server
+functionality for internet connection sharing, and avahi-autoipd for IPv4
+link-local addresses.  Most communication with these daemons occurs, again,
+via D-Bus.
+
+
+Why doesn't my network Just Work?
+
+Driver problems are the #1 cause of why NetworkManager sometimes fails to
+connect to wireless networks.  Often, the driver simply doesn't behave in a
+consistent manner, or is just plain buggy.  NetworkManager supports _only_
+those drivers that are shipped with the upstream Linux kernel, because only
+those drivers can be easily fixed and debugged.  ndiswrapper, vendor binary
+drivers, or other out-of-tree drivers may or may not work well with
+NetworkManager, precisely because they have not been vetted and improved by the
+open-source community, and becuase problems in these drivers usually cannot
+be fixed.
+
+Sometimes, command-line tools like 'iwconfig' will work, but NetworkManager will
+fail.  This is again often due to buggy drivers, becuase these drivers simply
+aren't expecting the dynamic requests that NetworkManager and wpa_supplicant
+make.  Driver bugs should be filed in the bug tracker of the distribution being
+run, since often distributions customize their kernel and drivers.
+
+Sometimes, it really is NetworkManager's fault.  If you think that's the case,
+please file a bug at http://bugzilla.gnome.org and choose the NetworkManager
+component.  Attaching the output of /var/log/messages or /var/log/daemon.log
+(wherever your distribution directs syslog's 'daemon' facility output) is often
+very helpful, and (if you can get) a working wpa_supplicant config file helps
+enormously.
+
+