NetworkManager is a system service that manages network interfaces and connections based on user or automatic configuration. It supports Ethernet, Bridge, Bond, VLAN, team, InfiniBand, Wi-Fi, mobile broadband (WWAN), PPPoE and other devices, and supports a variety of different VPN services. You can manage it a couple different ways, from config files to a rich command-line client, a curses-like client for non-GUI systems, graphical clients for the major desktop environments, and even web-based management consoles like Cockpit.
There’s an old perception that NetworkManager is only useful on laptops for controlling Wi-Fi, but nothing could be further from the truth. No laptop I know of has InfiniBand ports. We recently released NetworkManager 1.0 with a whole load of improvements for workstations, servers, containers, and tiny systems from embedded to RaspberryPi. In the spirit of making double-plus sure that everyone knows how capable and useful NetworkManager is, let’s take a magical journey into Administrator-land and start at the very bottom…
Daemon Configuration Files
Basic configuration is stored in /etc/NetworkManager/NetworkManager.conf in a standard key/value ini-style format. The sections and values are well-described by ‘man NetworkManager.conf’. A standard default configuration looks like this:
[main]
plugins=ifcfg-rh
You can override default configuration through either command-line switches or by dropping “configuration snippets” into /etc/NetworkManager/conf.d. These snippets use the same configuration options from ‘man NetworkManager.conf’ but are much easier to distribute among larger numbers of machines though packages or tools like Puppet, or even just to install features through your favorite package manager. For example, in Fedora, there is a NetworkManager-config-connectivity-fedora RPM package that installs a snippet that enables connectivity checking to Fedora Project servers. If you don’t care about connectivity checking, you simply ‘rpm -e NetworkManager-config-connectivity-fedora’ instead of tracking down and deleting /etc/NetworkManager/conf.d/20-connectivity-fedora.conf.
Just for kicks, let’s take a walk through the various configuration options, what they do, and why you might care about them in a server, datacenter, or minimal environment…
Configuration Snippets
First, each configuration “snippet” in /etc/NetworkManager/conf.d can override values set in earlier snippets, or even the default configuration (but not command-line options). So the same option specified in 50-foobar.conf will override that option specified in 10-barfoo.conf. Many options also support the “+” modifier, which allows their value to be added to earlier ones instead of replacing. So “plugins+=something-else” will add “something-else” to the list, instead of overwriting any earlier values. You’ll see why this is quite useful in a minute…
Dive Deep
[main]
plugins=ifcfg-rh | ifupdown | ifnet | ifcfg-suse | ibft (default empty)
This option enables or disables certain settings plugins, which are small loadable libraries that read and write distribution-specific network configuration. For example, Fedora/RHEL would specify ‘plugins=ifcfg-rh’ for reading and writing the ifcfg file format, while Debian/Ubuntu would use ‘plugins=ifupdown’ for reading /etc/network/interfaces, and Gentoo would use ‘plugins=ifnet’. If you know your distro’s config format like the back of your hand, NetworkManager doesn’t make you change it.
There is one default plugin though, ‘keyfile’, which NetworkManager uses to read and write configurations that the distro-specific plugins can’t handle. These files go into /etc/NetworkManager/system-connections and are standard .ini-style key/value files. If you’re interested in the key and value definitions, you can check out ‘man nm-settings’ and ‘man nm-settings-keyfiles’, or even look at some examples.
[main]
monitor-connection-files=yes | no (default no)
By popular demand, NetworkManager no longer watches configuration files for changes. Instead, you make all the changes you want, and then explicitly tell NetworkManager when you’re done with “nmcli con reload” or “nmcli con load <filename>”. This prevents reading partial configuration and allows you to double-check that everything is correct before making the configuration update. Note that changes made through the D-Bus interface (instead of the filesystem) always happen immediately.
However, if you want the old behavior back, you can set this option to “yes”.
[main]
auth-polkit=yes | no (default yes)
If built with support for it, NetworkManager uses PolicyKit for fine-grained authorization of network actions. This will be the subject of another article in this series, but the TLDR is that PolicyKit easily allows user A the permission to use WiFi while denying user B WiFi but allowing WWAN. These things can be done with Unix groups, but that quickly gets unwieldy and isn’t fine-grained enough for some organizations. In any case, PolicyKit is often unecessary on small, single-user systems or in datacenters with controlled access. So even if your distribution builds NetworkManager with PolicyKit enabled, you can turn it off for simpler root-only operation.
[main]
dhcp=dhclient | dhcpcd | internal (default determined at build time, dhclient preferred if enabled)
With NetworkManager 1.0 we’ve added a new internal DHCP client (based off systemd code which was based off ConnMan code) which is smaller, faster, and lighter than dhclient or dhcpcd. It doesn’t do DHCPv6 yet, but we’re working on that. We think you’ll like it, and it’s certainly much less of a resource hog than a dhclient process for every interface. To use it, set this option to “internal” and restart NetworkManager.
If NetworkManager was built with support for dhclient or dhcpcd, you can use either of these clients by setting this option to the client’s name. Note that if you enable both dhclient and dhcpcd, dhclient will be preferred for maximum compatibility.
[main]
no-auto-default= (default empty)
By default, NetworkManager will create an in-memory DHCP connection for every Ethernet interface on your system, which ensures that you have connectivity when bringing a new system up or booting a live DVD. But that’s not ideal on large systems with many NICs, or on systems where you’d like to control initial network bring-up yourself. In that case, you should set this option to “*” to disable the auto-Ethernet behavior for all interfaces, indicating that you’d like to create explicit configuration instead. You can also use MAC addresses or interface names here too! On Fedora we’ve created a package called NetworkManager-config-server that sets this option to “*” by default.
[main]
ignore-carrier= (default empty)
Trip over a cable? Want to make sure a critical interface stays configured if the switch port goes down? This option is for you! Setting it to “*” (all interfaces) or using MAC addresses or interface names here will tell NetworkManager to ignore carrier events after the interface is configured. For DHCP connections a carrier is obviously required for initial configuration, while static connections can start regardless of carrier status. After that, feel free to unplug the cable every time Apple sells an iPhone!
[main]
configure-and-quit=yes | no (default no)
New with 1.0 is the “configure and quit” mode where NetworkManager configures interfaces (including, if desired, blocking startup until networking is active) and then quits, spawning small helpers to maintain DHCP leases and IPv6 address lifetimes if required. In a datacenter or cloud where cycles are money, this can save you some cash and deliver a more stable setup with known behavior.
[main]
dns=dnsmasq | unbound | none | default (default empty, equivalent to “default”)
Want to control DNS yourself? NetworkManager makes it easy! Don’t want to? NetworkManager makes that easy too! When you set this option to ‘dnsmasq’ NetworkManager will configure dnsmasq as a local caching nameserver, including split DNS for VPN tunnels. If you set it to ‘none’ then NetworkManager won’t touch /etc/resolv.conf and you can use dispatcher scripts that NetworkManager calls at various points to set up DNS any way you choose.
Leaving the option empty or setting it to “default” asks NetworkManager to own resolv.conf, updating system DNS with any information from your explicit network settings or those received from automatic means like DHCP.
In the upcoming NetworkManager 1.2, DNS information is written to /var/lib/NetworkManager/resolv.conf and, if NM is allowed to manage /etc/resolv.conf, that file will be a symlink to the one in /var similar to systemd-resolvd. This makes it easier for external tools to incorporate the DNS information that NetworkManager combines from multiple sources like DHCP, PPP, IPv6, VPNs, and more.
[keyfile]
unmanaged-devices= (default empty)
Want to keep NetworkManager’s hands off a specific device? That’s what this option is for, where you can use “interface-name:eth0” or “mac:00:22:68:1c:59:b1” to prevent automatic management of a device. While there are some situations that require this, by default NetworkManager doesn’t touch virtual interfaces that it didn’t create, like bridges, bonds, VLANs, teams, macvlan, tun, tap, etc. So while it’s unusual to need this option, we realize that NetworkManager can be used in concert with other tools, so it’s here if you do.
[connectivity]
uri= (default empty = disabled)
interval=(default 0 = disabled)
response= (default “NetworkManager is online”)
Connectivity checking helps users log into captive ports and hotspots, while also providing information about whether or not the Internet is reachable. When NetworkManager connects a network interface, it sends an HTTP request to the given URI and waits for the specified response. If you’re connected to the Internet and the connectivity server isn’t down, the response should match and NetworkManager will change state from CONNECTED_SITE to CONNECTED. It will also check connectivity every ‘interval’ seconds so that clients can report status to the user.
If you’re instead connected to a WiFi hotspot or some kind of captive portal like a hotel network, your DNS will be hijacked and the request will be redirected to an authentication server. The response will be unexpected and NetworkManager will know that you’re behind a captive portal. Clients like GNOME Shell will then indicate that you must authenticate before you can access the real Internet, and could provide an embedded web browser for this purpose.
Upstream connectivity checking is disabled by default, but some distribution variants (like Fedora Workstation) are now enabling it for desktops, laptops, and workstations. On a server or embedded system, or where traffic costs a lot of money, you probably don’t want this feature enabled. To turn it off you can either remove your distro-provided connectivity package (which just drops a file in /etc/NetworkManager/conf.d) or you can remove the options from NetworkManager.conf.
Special NetworkManager data files
In the normal course of network management sometimes non-configuration data needs to persist. NetworkManager does this in the /var/lib/NetworkManager directory, which contains a few different files of interest:
seen-bssids
This file contains the BSSIDs (MAC addresses) of WiFi access points that NetworkManager has connected to for each configured WiFi network. NetworkManager doesn’t do this to spy on you (and the file is readable only by root), but instead to automatically connect to WiFi networks that do not broadcast their SSID. You almost never need to touch this file, but if you are concerned about privacy feel free to delete this file periodically.
timestamps
Each time you connect to a network, whether wired, WiFi, etc, NetworkManager updates the timestamp in this file. This allows NetworkManager to determine which network you last used, which can be used to automatically connect you to more preferred networks. NetworkManager also uses the timestamp as an indicator that you have successfully connected to the network before, which it uses when deciding whether or not to ask for your WiFi password when you get randomly disconnected or the driver fails.
NetworkManager.state
This file stores persistent user-determined state for Airplane mode for each technology like WiFi, WWAN, and WiMAX. Normally this is controlled by hardware buttons, but some systems don’t have hardware buttons or the drivers don’t work, plus that state is not persistent across boots. So NetworkManager stores a user-defined state for each radio type and will ensure the radio stays in that state across reboots too.
DHCP lease and configuration files
When you obtain a DHCP lease, that lease may last longer than your connection to that network. To ensure that you receive a nominally stable IP address the next time you connect, or to ensure that your TCP sessions are not broken if there is a network hiccup, NetworkManager stores the DHCP lease and attempts to acquire the same lease again. These files are stored per-connection to ensure that a lease acquired on your home WiFi or ethernet network is not used for work or Starbucks. Temporary DHCP configuration files are also stored here, which are constructed based on your preferences and on generic DHCP configuration files in /etc for each supported DHCP client. If you want to wipe the DHCP slate clean, feel free to remove any of the lease or configuration files.
And that’s it for this time, stay tuned for the next part in this series!