NetworkManager

From Gentoo Wiki
Jump to:navigation Jump to:search

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

Important
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!

Installation

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, and others.

The networkmanager USE flag will enable support for NetworkManager in other packages. Enabling this USE flag will make those packages pull in net-misc/networkmanager automatically:

FILE /etc/portage/make.conf
USE="${USE} networkmanager"

Alternatively, the euse tool from app-portage/gentoolkit can do this from the command-line:

root #euse -E networkmanager

Kernel

For WiFi devices enable also the following options:

KERNEL 
[*] 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

+concheck Enable connectivity checking support
+gtk-doc Build and install gtk-doc based developer documentation for dev-util/devhelp, IDE and offline use
+introspection Add support for GObject based introspection
+modemmanager Enable support for mobile broadband devices using net-misc/modemmanager
+nss Use dev-libs/nss for cryptography
+ppp Enable support for mobile broadband and PPPoE connections using net-dialup/ppp
+tools Build cli tools such as nmcli, nmtui and nm_cloud_setup
+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
audit Enable support for Linux audit subsystem using sys-process/audit
bluetooth Enable Bluetooth Support
connection-sharing Support connection sharing (uses net-dns/dnsmasq)
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
dhclient Use dhclient from net-misc/dhcp for getting an IP via DHCP
dhcpcd Use net-misc/dhcpcd for getting an IP
elogind Use sys-auth/elogind for session tracking
gnutls Prefer net-libs/gnutls as SSL/TLS provider (ineffective with USE=-ssl)
iptables Use net-firewall/iptables for connection sharing
iwd Use net-wireless/iwd instead of net-wireless/wpa_supplicant for wifi support by default
libedit Use the libedit library (replacement for readline)
nftables Use net-firewall/nftables for connection sharing
ofono Use net-misc/ofono for telephony support.
ovs Enable OpenVSwitch support
policykit Enable PolicyKit (polkit) authentication support
psl Use public suffix list via net-libs/libpsl
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.
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
syslog Enable support for syslog
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
teamd Enable Teamd control support
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
vala Enable bindings for dev-lang/vala
Data provided by the Gentoo Package Database · Last update: 2024-10-07 02:50 More information about USE flags

Note
NetworkManager uses an internal DHCP client implementation since version 1.20. There is no explicit need for an external DHCP client. The dhclient and dhcpcd USE flags enable alternative implementations.

Emerge

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

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.

Note
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.

GTK GUIs

nm-applet from system tray

There is a systray applet working in classic Xembed-based systrays provided by gnome-extra/nm-applet.

If a systray is not included as a part of the desktop environment in use, a standalone systray like x11-misc/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.

In LXQt when setting panel to autohide and mouse hover on Wi-Fi ico hides panel, the following are needed:

  1. Emerge gnome-extra/nm-applet with USE flag appindicator
  2. Emerge lxqt-base/lxqt-panel with USE flag statusnotifier
  3. Edit autostart in LXQt: change nm-applet to nm-applet --indicator.

See related bug.

KDE GUIs

Note
Enable openconnect USE flag of kde-plasma/plasma-nm to use openconnect.

Configuration

User permission

On Gentoo, NetworkManager uses the plugdev group to specify which non-root users can manage system network connections (treated as pluggable devices). Be sure to add each user who should be permitted to manage the network connections to that group.

Adding user larry can be achieved issuing:

root #gpasswd -a larry plugdev

Service

OpenRC

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 #for x in /etc/runlevels/default/net.* ; do rc-update del $(basename $x) default ; rc-service --ifstarted $(basename $x) stop; 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

systemd

To start NetworkManager immediately:

root #systemctl start NetworkManager

Enable NetworkManager to be started at boot time:

root #systemctl enable NetworkManager

With NetworkManager older than 0.9.10 or with services that order themselves after network.service instead of network-online.service, enabling the NetworkManager-wait-online.service for multi-user.target may be necessary:

root #systemctl enable NetworkManager-wait-online.service
Note
Enabling this service extends the boot time even when no services that need to wait for network connections exist.

When writing custom systemd services, they can wait for NetworkManager to configure the boot time connections:

FILE /etc/systemd/system/*.service
[Unit]
After=network-online.service
Wants=network-online.service

With NetworkManager 0.9.10 and later it works even without explicitly enabling the network-online.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 "customhostname";

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
[connectivity]
uri=http://nmcheck.gnome.org/check_network_status.txt

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}" ]];
then
    eval $(dbus-launch --sh-syntax --exit-with-session)
fi

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

Dnsmasq

NetworkManager way

NetworkManager can be set up to use Dnsmasq as a local DNS server that passes the DNS queries on to a provider's DNS server. /etc/resolv.conf will be set to point to 127.0.0.1, 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 the device moves from one WiFi network to another.

Setup of dnsmasq is simple:

FILE /etc/NetworkManager/NetworkManager.conf
[main]
plugins=keyfile
dns=dnsmasq

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.

DNSSEC

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
dnssec
trust-anchor=.,19036,8,2,49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5
trust-anchor=.,20326,8,2,E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D
dnssec-check-unsigned

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 an ISP's DNS server does not forward DNSSEC data then this will fail. Uncomment the last line, but it will defy the purpose of DNSSEC. Google's server 8.8.8.8 provides DNSSEC data.

Service way

In certain system network setups, Dnsmasq should not be controlled by NetworkManager. An alterantive way they both can be used together:

FILE /etc/NetworkManager/NetworkManager.conf
[main]
plugins=keyfile
dns=none

And add localhost to the /etc/resolv.conf file:

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

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

Don't forget to start Dnsmasq.

On systemd systems:

root #systemctl enable --now dnsmasq

On OpenRC systems:

root #rc-update add dnsmasq default
root #rc-service dnsmasq start

Usage

Plugins

WireGuard

See the NetworkManager section of the WireGuard article for more information on adding a WireGuard tunnel to NetworkManager.

Networks

eduroam

eduroam is an international Wi-Fi network for universities. Please see article about Eduroam.

Troubleshooting

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 (action.id.indexOf("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 NetworkManager.conf and enter hostname accordingly:

FILE /etc/NetworkManager/NetworkManager.conf
[main]
plugins=keyfile
hostname-mode=none

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
hostname="my-hostname"

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 {
...
Note
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
c69de11d6bb240558b98fb1d5e4292b3

For non-systemd users, it is possible to use the following command from lubko on #nm irc channel @freenode.net:

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

NetworkManager messing with X authentication

When NetworkManager connects to a WiFi access point, it might change the system hostname. If it does, it might mess with X authentication and prevent launching X applications. Verify this with xauth list.

To fix this, set hostname-mode = none in the config.

Wifi card driver and firmware are correctly loaded but interface is not available in NetworkManager

In case dmesg | grep wifi shows the kernel and the firmware of the network card has been properly loaded and e.g. beautifully appears in hwinfo | grep wifi but nmcli device show shows a line like GENERAL.DEVICE: wifi0 GENERAL.STATE: 20 (unavailable). This likely means the kernel and firmware are working correctly; the problem is somewhere in userspace.

A possible solution is to load iwd prior to NetworkManager. It is now recommended to replace wpa_supplicant by Iwd. To do so, remove wpa_supplicant from the init system (OpenRC/systemd) and add iwd, which then loads the Wifi card. Note that wireless network password store from wpa_supplicant will not be preserved, so WiFi authentication passwords will be need to be reentered in order to (re)connect to each SSID.

Review the iwd page for further information on setting up iNet wireless daemon backend.

Failed to add new connection: 802.1x connections must have IWD provisioning files

When using iwd backend for wifi connections, NetworkManager cannot autogenerate the provisioning file for 802.1x connections.

In this situation, you can just write the provisioning file manually.

FILE /var/lib/iwd/[SSID].8021x
[Security]
EAP-Method=PEAP
EAP-Identity=your-username
EAP-Password=your-password
EAP-CACert=path/to/ca-cert.pem # (delete this line if you dont need CA certification)
EAP-Phase2-Method=GTC

This example is for WPA/WPA2 Enterprise, PEAP-GTC certification. For other connection method, refer iwd#configuration-per-connection.

See also

  • Iwd — a wireless daemon intended to replace wpa_supplicant
  • Resolv.conf — used to configure hostname resolution.

External Links

Retrieved from "https://wiki.gentoo.org/index.php?title=NetworkManager&oldid=1310477"