-THEORY OF OPERATION:
+
+******************
+2008-12-11: NetworkManager core daemon has moved to git.freedesktop.org!
+
+git clone git://git.freedesktop.org/git/NetworkManager/NetworkManager.git
+******************
+
+
+Networking that Just Works
+--------------------------
NetworkManager attempts to keep an active network connection available at all
-times. It is intended only for the desktop use-case, and is not intended for
-usage on servers. 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. 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 two lists of wireless
-networks: a Trusted list, and a Preferred list. The Trusted list contains
-networks the user specifically adds to it, while the preferred list contains
-networks the user forces NetworkManager to connect to. For example, while the
-company's wireless network and WEP/WPA key would be preloaded into the Trusted
-Networks list, if the user wished to use the wireless network in a Starbucks,
-the user would explicitly tell NetworkManager to associate with that network.
-NetworkManager does not try to use _any_ available network in the area (a
-possible security risk), but will associate with any Trusted Network first, and
-Preferred Networks later. Preferred Networks are ones 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 Trusted and 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 Trusted and 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 Trusted and Preferred Networks in
-GConf and WEP/WPA keys in gnome-keyring, and proxies that information to
-NetworkManager upon request.
+times. The point of NetworkManager is to make networking configuration and
+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 because 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, because 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.
+
projects / NetworkManager.git / blobdiff