From Gentoo Wiki
Jump to: navigation, search

NetworkManager is a network management software for Ethernet, Wifi, DSL, dialup, VPN, WiMAX, and mobile broadband network connections.

NetworkManager and other network management services typically do not work together. That includes a standalone instances of dhcpcd and Gentoo's default netifrc scripts. Be sure only one network management service is running at a time. Adding more than one network management service will lead to unpredictable results!


NetworkManager requires an implementation of udev and D-Bus. On laptops and desktops, it is typically built with polkit to enable local users to configure it. It also optionally integrates with systemd, upower, ConsoleKit and others.

It is a good idea to use dhclient from net-misc/dhcp instead of net-misc/dhcpcd as 1.0.0 version is already doing. While dhcpcd in standalone mode provides some interesting features over dhclient, those will not be used by NetworkManager. Most NetworkManager developers do use dhclient and it is therefore much better tested with NetworkManager and is generally a better DHCP client to be used with NetworkManager. NetworkManager does not use the IPv6 support of dhcpcd and instead relies on dhclient for this.

Portage knows the global networkmanager USE flag for enabling support for NetworkManager in other packages. Enabling this USE flag will make those packages pull in net-misc/networkmanager automatically:

root #euse -E networkmanager


For Wifi devices enable also the following options:

[*] Networking support  --->
      Networking options  --->
        <*> Packet socket
  [*] Wireless  --->
        <*>   cfg80211 - wireless configuration API
        [*]     cfg80211 wireless extensions compatibility

Look at the udev page for kernel configuration needed for this NetworkManager dependency.

USE flags

USE flags for net-misc/networkmanager A set of co-operative tools that make networking simple and straightforward

audit Enable support for Linux audit subsystem using sys-process/audit
connection-sharing Use net-dns/dnsmasq and net-firewall/iptables for connection sharing
consolekit Use sys-auth/consolekit for session tracking
dhclient Use dhclient from net-misc/dhcp for getting ip
dhcpcd Use net-misc/dhcpcd for getting ip
elogind Use sys-auth/elogind for session tracking
introspection Add support for GObject based introspection
iwd Use net-wireless/iwd instead of net-wireless/wpa_supplicant for wifi support by default
json Enable JSON validation via dev-libs/jansson in libnm.
modemmanager Enable support for mobile broadband devices using net-misc/modemmanager
nss Use dev-libs/nss for cryptography
ofono Use net-misc/ofono for telephony support.
ovs Enable OpenVSwitch support
ppp Enable support for mobile broadband and PPPoE connections using net-dialup/ppp
resolvconf Use net-dns/openresolv for managing DNS information in /etc/resolv.conf. Generally, a symlink to /run/NetworkManager/resolv.conf is simpler. On systems running systemd-resolved, disable this flag and create a symlink to /run/systemd/resolve/stub-resolv.conf.
teamd Enable Teamd control support
wext Enable support for the deprecated Wext (Wireless Extensions) API; needed for some older drivers (e.g. ipw2200, ndiswrapper)
wifi Enable support for wifi and 802.1x security


After changing use flags run the following command to update the system so the changes take effect:

root #emerge --ask --changed-use --deep @world

To manually install NetworkManager, if not already pulled in automatically from above command:

root #emerge --ask net-misc/networkmanager

Additonal software

Live ebuild (future 1.2 release)

NetworkManager is changing substantially and its feature set is slowly moving from a laptop oriented tool to a universal network management service configured using all sorts of tools from nmcli through nmtui to GUI tools like nm-applet, nm-connection-editor, Gnome Shell's network indicator, Gnome 3 control center, KDE's plasma-nm, and more.

The most convenient way is to add the ixit overlay using Layman or eselect repository.

root #layman -a ixit


root #eselect repository enable ixit

Then you can install the desired NetworkManager release.

root #emerge --ask --autounmask-write =net-misc/networkmanager-9999

If anything goes wrong, contact User:Pavlix. Those are live ebuilds and therefore they can occasionally need updating. I'm also considering starting a separate overlay just for networking related tools, let me know if that would help you.

VPN plugins

The following packages can be used to add VPN support to the base NetworkManager agent:

After emerging a plugin, it will be available when adding new connections to NetworkManager.

Many, if not all, of these packages depend on both the gnome-base/gnome-keyring and explicit enabling of the gtk USE flag. Additionally, they are usually not compatible with the terminal interface, nmtui, and must be launched via nm-applet.

Split DNS and DNSSEC support using unbound and dnssec-trigger

This doesn't yet work well with upstream releases nor in portage. But you can use Layman or eselect repository to add the ixit overlay and install net-misc/networkmanager, net-dns/dnssec-trigger, and net-dns/unbound live ebuilds from there.

root #layman -a ixit


root #eselect repository enable ixit

Now you can install the live ebuilds.

root #emerge --ask --autounmask-write =net-misc/networkmanager-9999 =net-dns/dnssec-trigger-9999 =net-dns/unbound-9999

The main difference from simple DNSSEC support like in the dnsmasq plugin is that dnssec-trigger does its best to ensure that you get a working DNSSEC configuration even on your laptop roaming among third party networks with different capabilities as well as to allow you to still access local resources and that you can choose to work without DNSSEC when it cannot provide a working setup.


The systray applet is in gnome-extra/nm-applet and works in classic Xembed based systrays. If a systray is not included as part of the desktop environment in use, a standalone systray like stalonetray can be installed. The connection editor GUI in the same package as the applet. Note that this package serves all sorts of desktop environments and panels with systrays but it is no longer used by Gnome which has its own implementations in Gnome Shell and Gnome Control Center.

root #emerge --ask gnome-extra/nm-applet

Also note that the current upstream version doesn't support the appindicator API and thus does not work in some systray implementations like those in current versions of KDE and Unity or the development versions of Enlightenment.



On Gentoo, NetworkManager uses the plugdev group to specify which users can manage plugable devices. Be sure to substitute <user_name> in the command below for each user who should be permitted to manage network connections:

root #gpasswd -a <user_name> plugdev



Remove any existing network management services (if activated).

For example, to remove any netifrc scripts from controlling network interfaces (assuming they are all in the default runlevel), issue the following command:

root #find /etc/runlevels/default -type l -name 'net.*' -exec sh -c 'for x; do rc-update del "${x##*/}" default; done' _ {} +

To remove dhcpcd:

root #rc-update del dhcpcd default

Start NetworkManager:

root #rc-service NetworkManager start

To start NetworkManager at boot time add it the default runlevel:

root #rc-update add NetworkManager default


To start NetworkManager now:

root #systemctl start NetworkManager

Enable NetworkManager to be started at boot time.

root #systemctl enable NetworkManager

With NetworkManager older than 0.9.10 or when you have services that order themselves after network.service instead of network-online.service, you may want to enable the NetworkManager-wait-online.service for Note that it extends the boot time even if you don't have any services that need to wait for network connections.

root #systemctl enable NetworkManager-wait-online.service

When writing your own systemd services, you can easily make them wait for NetworkManager to configure the boot time connections. With NetworkManager 0.9.10 and later it works even without explicitly enabling the network-online.service.

FILE /etc/systemd/system/*.service

Setting a hostname

If NetworkManager was built with the dhclient USE flag enabled a hostname can be set using the following command:

FILE /etc/dhcp/dhclient.conf
send host-name "yourhostname";

Checking connectivity

NetworkManager can try to reach a page on Internet when connecting to a network. For those behind a captive portal, the desktop manager can automatically open a window asking for credentials. It's automatically done since NetworkManager 1.8, but it has to be configured manually for earlier versions. To enable this feature, edit (or create) the /etc/NetworkManager/NetworkManager.conf file to look something like this:

FILE /etc/NetworkManager/NetworkManager.conf

nm-applet and X session startup

To be able to get nm-applet started when starting a light X session or light desktop environment, just put the following line in the relevant user's ~/.xinitrc file:

FILE ~/.xinitrc
nm-applet &

For gnome-base/gnome-keyring support, add the following lines before the previous line. This will ease password management for GnuPG, ssh and Wifi:

FILE ~/.xinitrc
# Ensure dbus is either already running, or safely start it
if [[ -z "${DBUS_SESSION_BUS_ADDRESS}" ]];
    eval $(dbus-launch --sh-syntax --exit-with-session)

# Make the keyring daemon ready to communicate with nm-applet
export $(gnome-keyring-daemon --start --components=pkcs11,secrets,ssh,gpg)


NetworkManager way

NetworkManager can be set up to use Dnsmasq as a local DNS server that passes the DNS queries on to your provider's DNS server. /etc/resolv.conf will be set to point to, where dnsmasq runs and processes the queries. This can be useful for example if an application chroots for security reasons and before doing so copies /etc/resolv.conf. Then it would never be informed about changes to the DNS servers as your laptop moves from Wifi to Wifi.

Setup of dnsmasq is simple:

FILE /etc/NetworkManager/NetworkManager.conf

Dnsmasq can be configured with files in /etc/NetworkManager/dnsmasq.d, for more information see the wiki page or the man pages of Dnsmasq.

Then restart NetworkManager.


Dnsmasq can optionally validate DNSSEC data while passing through queries (must be compiled with the dnssec USE flag). This can be accomplished by adding these lines to the NetworkManager dnsmasq config file:

FILE /etc/NetworkManager/dnsmasq.d/dnssec
# DNSSEC setup

The trusted anchor can be found here. After this change dnsmasq will return SERVFAIL and no DNS data if the validation fails. If the validation succeeds it sets the Authenticated Data (AD) flag. In case the domain does not support DNSSEC dnsmasq behaves as before.

If your ISP's DNS server does not forward DNSSEC data then this will fail. In that case you can uncomment the last line, but it will defy the purpose of DNSSEC. Google's server provides DNSSEC data.

Service way

Sometimes you don't want to have Dnsmasq controlled by NetworkManager for different reasons, here is another way you can use both together:

FILE /etc/NetworkManager/NetworkManager.conf

And add localhost to your /etc/resolv.conf:

FILE /etc/resolv.conf
# This should be the first nameserver entry in resolv.conf!

Set your Dnsmasq up, see man pages and the wiki page about Dnsmasq for details.

Don't forget to start Dnsmasq:

root #systemctl enable dnsmasq && systemctl start dnsmasq


root #rc-update add dnsmasq default && /etc/init.d/dnsmasq start


Fixing nm-applet insufficient privileges

If nm-applet fails to create new networks with the error "Insufficient Privileges," then it could be a policy kit issue. Create the following file:

FILE /etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules
polkit.addRule(function(action, subject) {
    if ("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("plugdev")) {
        return polkit.Result.YES;

This lets all users in the plugdev group control network manager.

Hostname problems

The standard "keyfile" plugin does not forward the hostname in default configuration - to avoid having it changed upon network connection, add the following section to your NetworkManager.conf and enter your hostname accordingly:

FILE /etc/NetworkManager/NetworkManager.conf

Alternatively, if a hostname is set which NetworkManager considers valid (Mainly anything other than "localhost" or similar default values), the hostname fetching from DHCP servers is skipped. To set a new hostname, edit the file /etc/conf.d/hostname:

FILE /etc/conf.d/hostname
# Set to the hostname of this machine

Connection sharing

Connection sharing is not working on an Ethernet connection when set to shared via nmtui.

Verify the connection-sharing USE flag has been enabled for net-misc/networkmanager. This can quickly be performed using eix:

user $eix net-misc/networkmanager

Enable the USE flag if it is disabled (-connection-sharing), then reemerge the package:

root #emerge --ask --newuse --deep net-misc/networkmanager

DHCPv6 Unique IDentifier (DUID)

The DUID will be generated by NetworkManager and stored as the first line in the following file:

FILE /var/lib/NetworkManager/dhclient6-*.lease
default-duid "\000\001\000\001\031\012D\036<\331+m3\004";
lease6 {
ISC dhclient6 stores the DUID_ value in a binary representation as shown

To generate a DUID NetworkManager relies on the following file, which is created by systemd. This should be unique to any system.

FILE /etc/machine-id

For non-systemd users, you can use the following command from lubko on #nm irc channel

root #uuidgen | sed 's/-//g' > /etc/machine-id

NetworkManager messing with X authentication

When NetworkManager connects to a wifi access point, it might change your hostname. If it does, it might mess with your X authentication and prevent you from launching X applications. You can verify this with xauth list.

To fix this, you can set hostname-mode = none in your config.

External Links