summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorDan Williams <dcbw@redhat.com>2008-11-20 14:45:27 +0000
committerDan Williams <dcbw@redhat.com>2008-11-20 14:45:27 +0000
commit7eb455978b555db48d337e2f54ab0ab1acea159e (patch)
treebeee777ef458d9618b95af2c77da0ae25259719a /README
parent9fd459f326b31417318446f6c3eeaf08009f01e8 (diff)
downloadNetworkManager-7eb455978b555db48d337e2f54ab0ab1acea159e.tar.gz
Update the readme
git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@4311 4912f4e0-d625-0410-9fb7-b9a5a253dbdc
Diffstat (limited to 'README')
-rw-r--r--README126
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.
+
+