Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc
Merge-arrows.gifIt has been suggested that this article be Merged into one article with Wireless/Managers.    (Discuss)

NetworkManager is a networking addition aimed at simplifying connecting to computer networks. Its goal is to allow Linux users to simplify connecting with modern networking with less manual configuration, particularly wireless networking. NetworkManager takes an opportunistic approach to network selection, attempting to use the best available connection.

Network Manager Logo


About NetworkManager

The NetworkManager service monitors the network interfaces and can connect various types of interfaces. NetworkManager may automatically switch to the best connection at any given time. If the network requires an encryption key, NetworkManager will prompt for one. NetworkManager supports most types of encrypted networks. Applications that include NetworkManager support have the ability to automatically switch between on-line and off-line modes when the system gains or loses network connectivity. NetworkManager also supports modem connections, and certain types of VPN.

Before installing NetworkManager

NetworkManager is desktop agnostic in that it runs on both Gnome and KDE and has an applet where it can be access from both.

Drivers Installed?

NetworkManager requires Linux to have drivers for the wired and wireless cards on the computer - some manufacturers of modems and wireless devices provide limited support for Linux and newer devices can sometimes take awhile to be developed. Research your card manufacturer and item number and see if the driver is available in the kernel then check to see if the driver is available separately in portage.

Installing NetworkManager

Installing and configuring NetworkManager.

Emerge and Add Runlevels

Network Manager is in the official Gentoo tree.

Emerge for Gnome:

emerge -av net-misc/networkmanager

Emerge for KDE:

emerge -av kde-misc/knetworkmanager

Add the Runlevels:

rc-update add NetworkManager default
rc-update add dhcdbd default


NetworkManager reads the /etc/dhcp/dhclient.conf to determine the hostname. If no value is assigned then an IP address is set as a hostname which can cause problems opening new windows in Gnome. To prevent this, add the following to /etc/dhcp/dhclient.conf:

File: /etc/dhcp/dhclient.conf
send host-name "YOUR_HOSTNAME";
supersede host-name "YOUR_HOSTNAME";

Baselayout Settings

Baselayout is Gentoo's system initialization system when Gentoo boots. If all goes well installing NetworkManager then disable any baselayout networking scripts.

Remove your current network devices from start up. If you don't, you will have dueling dhcp clients fighting over your interfaces and eating up CPU:

rc-update del net.eth0
rc-update del net.ath0

If you are using udev, you will also need to block it from attempting to automatically initialize your network interfaces. This can be done by modifying the /etc/conf.d/rc file (or /etc/rc.conf on OpenRC). For example, to block eth0 from loading, add this:

File: /etc/conf.d/rc

The following line should block all Ethernet and wireless interfaces:

File: /etc/conf.d/rc
RC_PLUG_SERVICES="!net.eth* !net.wlan*"

Start NetworkManager

For the first run, restart the dbus and then start NetworkManager daemon. Restarting the dbus is not a good idea when the desktop is running. For Gnome, GDM will need to be stopped.

/etc/init.d/xdm stop 

Kill the desktop "ctrl-alt-backspace" first and restart the dbus in console.

/etc/init.d/dbus restart
/etc/init.d/NetworkManager start

Then start Gnome again and Network Manager applet will load in the notification area if everything is configured correctly.

Dependencies of Baselayouts Networking Script

Any dependencies of baselayouts networking script (ntp, samba...) will require the use NetworkManagerDispatcher to start them. This is needed since NetworkManager does not initialize the network till after the desktop is loaded. To start these scripts they will need to be identified to NetworkManager.


NetworkManager offers a tool called NetworkManagerDispatcher, which executes files in /etc/Networkmanager/dispatcher.d when changing the state of interfaces. Although, at the moment this service isn't started we need to get this service started first. This is done by an init-file:

File: /etc/init.d/NetworkManagerDispatcher
# NetworkManagerDispatcher:   NetworkManagerDispatcher daemon
# chkconfig: 345 98 02
# description:  This is a daemon for automatically executing certain
#               actions, when switching networks
# processname: NetworkManagerDispatcher
# pidfile: /var/run/



# Sanity checks.

# so we can rearrange this easily

depend() {
        need NetworkManager

        if [ -e ${pidfile} ]; then
                rm -f ${pidfile}
        ebegin "Starting NetworkManagerDispatcher"
        start-stop-daemon --start --quiet --exec ${processname}
        eend $?
        echo $(/bin/pidof NetworkManagerDispatcher) > ${pidfile}

        ebegin "Stopping NetworkManagerDispatcher"
        start-stop-daemon --stop --quiet --exec ${processname} --pidfile ${pidfile}
        eend $?
        if [ -e ${pidfile} ]; then
                rm -f $pidfile

chmod +x /etc/init.d/NetworkManagerDispatcher
rc-update add NetworkManagerDispatcher default
/etc/init.d/NetworkManagerDispatcher start

Dependent Scripts

Now follows the short but important script, which starts our dependent script when we're online for the first time. ntp-client is used and an example here:

File: /etc/NetworkManager/dispatcher.d/50-ntp-client

/etc/init.d/ntp-client status | grep -q "started"

if test "$2" == "up" -a "$?" != "0" ; then
        rc-config start ntp-client
        rc-config stop ntp-client

Make the script executable:

Code: Making it executable
chmod +x /etc/NetworkManager/dispatcher.d/50-ntp-client
rc-update add NetworkManagerDispatcher default

The above script for ntp should can be adapted for any baselayout network dependency. Anytime NetworkManager is initialized these scripts will be run.

Alternative: NetworkManagerDispatcher and a runlevel

Using a runlevel for the services to be managed by NetworkManagerDispatcher makes adding, removing and showing the status of the services easy. You will be able to use rc-update and rc-status to manage these services; just like with any other runlevel.

Note: The runlevel in this example is network_services
Warning: Switching to this runlevel will cause other services to be stopped. Don't explicitly switch to this runlevel.

First, create a new runlevel.

mkdir /etc/runlevels/network_services

We also need a script for NetworkManagerDispatcher to properly execute the service scripts in the runlevel. Create it and make it executable.

File: /etc/NetworkManager/dispatcher.d/
# Run the init.d scripts for services in our pseudo runlevel in ``${SERVICES_RUNLEVEL}''

source /etc/conf.d/NetworkManagerDispatcher

if [ -z "${SERVICES_RUNLEVEL}" ]; then
        echo "SERVICES_RUNLEVEL not set, cannot continue!"
        exit 1

for name in $(find /etc/runlevels/${SERVICES_RUNLEVEL} -executable -type l); do
        $name status | grep -q "started"

        if test "$2" == "up" -a "$?" != "0"; then
                rc-config start $(basename $name)
                rc-config stop $(basename $name)

chmod +x /etc/NetworkManager/dispatcher.d/ takes the variable SERVICES_RUNLEVEL from /etc/conf.d/NetworkManagerDispatcher. We need to set this variable.

File: /etc/conf.d/NetworkManagerDispatcher
# This it the configuration file for, the wrapper
# script for NetworkManagerDispatcher and the network service runlevel


Make sure to add any services that you want NetworkManagerDispacter to handle.

rc-update add ntp-client network_services
Note: When adding, removing, or attempting to view the status of a service for NetworkManagerDispatcher be sure you specify the network_services runlevel. E.g. rc-status network_services

NM Applet

NM Applet
NM Applet

Network Manager includes an applet for both KDE and Gnome. It will allow the user to specify the network to connect to.


The networkmanager-vpn-plugins have made it to the official portage-tree.

emerge networkmanager-openvpn


Several Troubleshooting ideas.

Survive Suspend/Resume

Several methods may be able to help issues with suspend. NetworkManager includes built in support for suspend/resume and works very well, if NetworkManager doesn't resume from suspend it is likely an issue with the driver. Sometimes the network driver will not be unloaded and hence properly reloaded.

Put the Driver in the Whitelist

Perhaps the simplest solution is adding the driver to the Whitelist:

emerge -pv hal-device-manager
nano  /etc/default/acpi-support

A Script Loads the Driver

If the above method doesn't work, this may. The Linux power control system - Advanced Configuration and Power Interface (ACPI) - can read scripts before and after suspend. It uses two directories in /etc/acpi, create the directories if they doesn't exist yet.

nano /etc/acpi/suspend.d/

rmmod some-driver

(Use your driver you found about above.) And one for resume:


sleep 2
modprobe some-driver

and then make them executable:

sudo chmod +x /etc/acpi/suspend.d/
sudo chmod +x /etc/acpi/resume.d/

Failed emerge

If you get errors when emerging, like these:

/usr/include/linux/if.h:95: error: redefinition of `struct ifmap'
/usr/include/linux/if.h:131: error: redefinition of `struct ifreq'
usr/include/linux/if.h:181: error: redefinition of `struct ifconf'

This can be solved by updating to a newer version of linux-headers.

WPA won't work on my PowerPC based machine (e.g. iBook G4)

As of 12th November 07, this is a known bug: see

Although it seems that it has been fixed upstream, this has not made it into the gentoo ebuild yet.

NetworkManager won't start

Error requesting name, org.freedesktop.DBus.Error.AccessDenied: Connection ":1.7" is not allowed to own the service "org.freedesktop.NetworkManagerInfo" due to security policies in the configuration file

Edit /etc/dbus-1/system.d/NetworkManager.conf or /etc/dbus-1/system.d/knetworkmanager.conf and add/modify either policies or user groups for your user to "own" the service.

You need something like this for knetworkmanager:

File: /etc/dbus-1/system.d/knetworkmanager.conf
<!DOCTYPE busconfig PUBLIC
 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
        <policy user="root">
                <allow own="org.freedesktop.NetworkManagerInfo"/>

                <allow send_destination="org.freedesktop.NetworkManagerInfo"/>
                <allow send_interface="org.freedesktop.NetworkManagerInfo"/>
        <policy group="plugdev">
                <allow own="org.freedesktop.NetworkManagerInfo"/>

                <allow send_destination="org.freedesktop.NetworkManagerInfo"/>
                <allow send_interface="org.freedesktop.NetworkManagerInfo"/>
        <policy context="default">
                <deny own="org.freedesktop.NetworkManagerInfo"/>

                <deny send_destination="org.freedesktop.NetworkManagerInfo"/>
                <deny send_interface="org.freedesktop.NetworkManagerInfo"/>

make sure your user is in the plugdev group!

/etc/resolv.conf empty

If you have a static configuration for your network (no DHCP) and your /etc/resolv.conf stays empty (except for the NetworkManager comments) then you have to change the format of dns_servers in /etc/conf.d/net to use single quotes only. e.g.:

File: /etc/conf.d/net


Introducing NetworkManager
NetworkManager, netapplet, and ipw2200
Retrieved from ""

Last modified: Sun, 03 Aug 2008 14:57:00 +0000 Hits: 50,659