NetworkManager is a program for providing detection and configuration for systems to automatically connect to networks. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the GNOME project.
After installation, you should start/enable NetworkManager.service. Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need nmcli or an applet to configure and connect.
Add connections from a front-end (e.g. nm-connection-editor) and select mobile broadband as the connection type. After selecting your ISP and billing plan, APN and other settings should be filled in automatically using information from mobile-broadband-provider-info.
To provide integration with a desktop environment, most users will want to install an applet. This not only provides easy access to network selection and configuration, but also provides the agent necessary for securely storing secrets. Various desktop environments have their own applet; otherwise, you can use #nm-applet.
Be aware that after enabling the tick-box option Make available to other users for a connection, NetworkManager stores the password in plain-text, though the respective file is accessible only to root (or other users via nm-applet). See #Encrypted Wi-Fi passwords.
The applet can show notifications for events such as connecting to or disconnecting from a WiFi network. For these notifications to display, ensure that you have a notification server installed - see Desktop notifications. If you use the applet without a notification server, you might see some messages in stdout/stderr, and the applet might hang. See [2].
Alternatively there is networkmanager-dmenu-gitAUR which is a small script to manage NetworkManager connections with dmenu or rofi instead of nm-applet. It provides all essential features such as connection to existing NetworkManager wifi or wired connections, connect to new wifi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch nm-connection-editor GUI, connect to Bluetooth networks.
Pantheon's switchboard offers a desktop environment-agnostic way to configure NetworkManager when combined with switchboard-plug-network and nm-connection-editor. It can be ran with the following command:
NetworkManager has a global configuration file at /etc/NetworkManager/NetworkManager.conf. Additional configuration files can be placed in /etc/NetworkManager/conf.d/. Usually no configuration needs to be done to the global defaults.
Enabling NetworkManager.service also enables NetworkManager-wait-online.service, which is a oneshot system service that waits for the network to be configured. The latter has WantedBy=network-online.target, so it will finish only when network-online.target itself is enabled or pulled in by some other unit. See also systemd#Running services after the network is up.
By default, NetworkManager-wait-online.service waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see nm-online(1)). If NetworkManager-wait-online.service finishes before the network is really up, resulting in failed services on boot, extend the unit to remove the -s from the ExecStart line:
By default, all users in active local sessions are allowed to change most network settings without a password. See General troubleshooting#Session permissions to check your session type. In most cases, everything should work out of the box.
Some actions (such as changing the system hostname) require an administrator password. In this case, you need to add yourself to the wheel group and run a Polkit authentication agent which will prompt for your password.
For those behind a captive portal, the desktop manager may automatically open a window asking for credentials. If your desktop does not, you can use capnet-assist package (however, it currently it has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:
By default NetworkManager uses its internal DHCP client. The internal DHCPv4 plugin is based on the nettools' n-dhcp4 library, while the internal DHCPv6 plugin is made from code based on systemd-networkd.
NetworkManager has a plugin to enable DNS caching and conditional forwarding (previously called "split DNS" in NetworkManager's documentation) using dnsmasq or systemd-resolved. The advantages of this setup is that DNS lookups will be cached, shortening resolve times, and DNS lookups of VPN hosts will be routed to the relevant VPN's DNS servers. This is especially useful if you are connected to more than one VPN.
Now run nmcli general reload as root. NetworkManager will automatically start dnsmasq and add 127.0.0.1 to /etc/resolv.conf. The original DNS servers can be found in /run/NetworkManager/no-stub-resolv.conf. You can verify dnsmasq is being used by doing the same DNS lookup twice with drill example.com and verifying the server and query times.
Enabling dnsmasq in NetworkManager may break IPv6-only DNS lookups (i.e. drill -6 [hostname]) which would otherwise work. In order to resolve this, creating the following file will configure dnsmasq to also listen to the IPv6 loopback:
In addition, dnsmasq also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this (Ubuntu Bug). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists.
The dnsmasq instance started by NetworkManager by default will not validate DNSSEC since it is started with the --proxy-dnssec option. It will trust whatever DNSSEC information it gets from the upstream DNS server.
Because NetworkManager advertises a single "interface" to resolvconf, it is not possible to implement conditional forwarding between two NetworkManager connections. See NetworkManager issue 153.
This can be partially mitigated if you set private_interfaces="*" in /etc/resolvconf.conf[6]. Any queries for domains that are not in search domain list will not get forwarded. They will be handled according to the local resolver's configuration, for example, forwarded to another DNS server or resolved recursively from the DNS root.
NetworkManager's /etc/resolv.conf management mode is configured with the main.rc-manager setting. networkmanager sets it to symlink as opposed to the upstream default auto. The setting and its values are documented in the NetworkManager.conf(5) man page.
NetworkManager also offers hooks via so called dispatcher scripts that can be used to alter the /etc/resolv.conf after network changes. See #Network services with NetworkManager dispatcher and NetworkManager(8) for more information.
There are quite a few network services that you will not want running until NetworkManager brings up an interface. NetworkManager has the ability to start services when you connect to a network and stop them when you disconnect (e.g. when using NFS, SMB and NTPd).
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. 10-portmap or 30-netfs (which ensures that the portmapper is up before NFS mounts are attempted).
If the above is working, then this section is not relevant. However, there is a general problem related to running dispatcher scripts which take longer to be executed. Initially an internal timeout of three seconds only was used. If the called script did not complete in time, it was killed. Later the timeout was extended to about 20 seconds (see the Bugtracker for more information). If the timeout still creates the problem, a work around may be to use a drop-in file for the NetworkManager-dispatcher.service to remain active after exit:
As the script is run in a very restrictive environment, you have to export SSH_AUTH_SOCK in order to connect to your SSH agent. There are different ways to accomplish this, see this message for more information. The example below works with GNOME Keyring, and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely gnome-keyring has not yet started and the export will fail (hence the sleep). The UUID to match can be found with the command nmcli connection status or nmcli connection list.
Note that there is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network.
If you would like to attempt to automatically connect to VPN for all Wi-Fi networks, you can use the following definition of the ESSID: ESSID=$(iwgetid -r). Remember to set the script's permissions accordingly.
Trying to connect with the above script may still fail with NetworkManager-dispatcher.service complaining about 'no valid VPN secrets', because of the way VPN secrets are stored. Fortunately, there are different options to give the above script access to your VPN password.
1: One of them requires editing the VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring that will be inaccessible for root: open up /etc/NetworkManager/system-connections/name of your VPN connection and change the password-flags and secret-flags from 1 to 0.