Dynamic network management daemon for Linux that automatically configures and manages wired, wireless, VPN, and mobile broadband connections through nmcli, nmtui, and graphical interfaces.

Addresses below are RFC 5737 documentation ranges or placeholders - swap in your own.

Table of Contents#

  1. Overview
  2. Installation and Setup
  3. Core Concepts
  4. Basic Commands
  5. Ethernet Connections
  6. WiFi Connections
  7. Bonding Interfaces
  8. Bridge Connections
  9. VLAN Configuration
  10. VPN Connections
  11. Modifying Connections
  12. Connection Profiles and Autoconnect
  13. Dispatcher Scripts
  14. Tips and Tricks
  15. Troubleshooting
  16. See Also
  17. Sources

1. Overview#

NetworkManager is a daemon that manages network connections on Linux systems, providing automatic detection and configuration of network interfaces. It handles wired, wireless, mobile broadband, VPN, DSL, and virtual (bridge, bond, VLAN, team) connections. NetworkManager tracks network state, selects the best available connection, and provides seamless connectivity switching.

Key features:

  • Automatic connection management - detects hardware changes, connects/reconnects automatically
  • Multiple interfaces - manages all network devices on a system simultaneously
  • Connection profiles - stores named configurations that can be switched between
  • VPN integration - native support for OpenVPN, WireGuard, IPsec, OpenConnect, and more
  • D-Bus API - applications can query and control networking programmatically
  • Multiple frontends - nmcli (CLI), nmtui (TUI), GNOME Settings, KDE Plasma, etc.

2. Installation and Setup#

# Debian/Ubuntu
sudo apt install network-manager

# RHEL/CentOS/Fedora
sudo dnf install NetworkManager

# Arch Linux
sudo pacman -S networkmanager

Start and enable the service:

sudo systemctl enable --now NetworkManager
systemctl status NetworkManager

Note: If another network management tool is active (e.g., systemd-networkd, netplan, ifupdown), disable it first to avoid conflicts. On Ubuntu, netplan can be configured to use NetworkManager as its renderer.

3. Core Concepts#

3.1. Connection Profiles#

A connection profile is a named configuration that describes how to connect using a specific device. Profiles are stored in:

  • /etc/NetworkManager/system-connections/ (keyfile format, default on most distros)
  • /etc/sysconfig/network-scripts/ (ifcfg format, RHEL/CentOS legacy)

Each profile contains settings for the connection type, IP addresses, DNS, routes, security, and more. A single device can have multiple profiles (e.g., "Office" and "Home" for the same WiFi adapter), but only one can be active at a time.

3.2. Devices vs. Connections#

  • Device - a physical or virtual network interface (e.g., eth0, wlan0, br0)
  • Connection - a configuration profile that can be applied to a device

List both:

# Show devices and their states
nmcli device status

# Show connection profiles
nmcli connection show

# Show active connections only
nmcli connection show --active

4. Basic Commands#

CommandDescription
nmcli general statusShow overall NetworkManager status
nmcli device statusList all devices and their states
nmcli connection showList all connection profiles
nmcli connection show --activeList active connections
nmcli connection up <name>Activate a connection
nmcli connection down <name>Deactivate a connection
nmcli connection delete <name>Delete a connection profile
nmcli connection reloadReload connection files from disk
nmcli device wifi listScan and list WiFi networks
nmcli networking offDisable all networking
nmcli networking onEnable all networking
nmcli radio wifi offDisable WiFi radio
nmcli radio wifi onEnable WiFi radio

Interactive editor for detailed configuration:

nmcli connection edit <name>

Curses-based TUI (useful over SSH):

nmtui

5. Ethernet Connections#

5.1. Creating Connections#

# Create a new Ethernet connection with DHCP (default)
nmcli connection add type ethernet ifname eth0 con-name "Wired Office"

# Create and immediately activate
nmcli connection add type ethernet ifname eth0 con-name "Wired Office" autoconnect yes
nmcli connection up "Wired Office"

5.2. Static IP Configuration#

# Create with static IP
nmcli connection add type ethernet ifname eth0 con-name "Static LAN" \
  ipv4.addresses 192.0.2.100/24 \
  ipv4.gateway 192.0.2.1 \
  ipv4.dns "8.8.8.8,8.8.4.4" \
  ipv4.method manual

# Activate
nmcli connection up "Static LAN"

5.3. DHCP Configuration#

# Create with DHCP (explicit)
nmcli connection add type ethernet ifname eth0 con-name "DHCP LAN" \
  ipv4.method auto

# Switch an existing connection to DHCP
nmcli connection modify "Static LAN" ipv4.method auto
nmcli connection modify "Static LAN" ipv4.addresses ""
nmcli connection modify "Static LAN" ipv4.gateway ""
nmcli connection up "Static LAN"
# Set MTU
nmcli connection modify "Wired Office" 802-3-ethernet.mtu 9000

# Set speed and duplex (disables auto-negotiation)
nmcli connection modify "Wired Office" 802-3-ethernet.speed 1000
nmcli connection modify "Wired Office" 802-3-ethernet.duplex full

# Re-enable auto-negotiation
nmcli connection modify "Wired Office" 802-3-ethernet.auto-negotiate yes

# Set Wake-on-LAN
nmcli connection modify "Wired Office" 802-3-ethernet.wake-on-lan magic

# Apply changes
nmcli connection up "Wired Office"

6. WiFi Connections#

6.1. Scanning and Listing Networks#

# List available WiFi networks
nmcli device wifi list

# Force a rescan
nmcli device wifi rescan
nmcli device wifi list

# Show specific fields
nmcli -f SSID,BSSID,SIGNAL,SECURITY device wifi list

6.2. Connecting to WiFi#

# Quick connect (creates a profile automatically)
nmcli device wifi connect "MyNetwork" password "mypassword"

# Connect using a specific interface
nmcli device wifi connect "MyNetwork" password "mypassword" ifname wlan0

# Create a named connection profile
nmcli connection add type wifi ifname wlan0 con-name "Home WiFi" \
  ssid "MyNetwork" \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "mypassword"

6.3. WiFi Security (WPA2/WPA3)#

# WPA2 Personal (most common)
nmcli connection add type wifi ifname wlan0 con-name "WPA2 Network" \
  ssid "SecureNet" \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "mypassword"

# WPA3 Personal (SAE)
nmcli connection add type wifi ifname wlan0 con-name "WPA3 Network" \
  ssid "SecureNet3" \
  wifi-sec.key-mgmt sae \
  wifi-sec.psk "mypassword"

# WPA2 Enterprise (802.1X, PEAP/MSCHAPv2)
nmcli connection add type wifi ifname wlan0 con-name "Enterprise WiFi" \
  ssid "CorpNet" \
  wifi-sec.key-mgmt wpa-eap \
  802-1x.eap peap \
  802-1x.phase2-auth mschapv2 \
  802-1x.identity "user@corp.com" \
  802-1x.password "password"

# WPA2 Enterprise with certificate
nmcli connection add type wifi ifname wlan0 con-name "Enterprise WiFi Cert" \
  ssid "CorpNet" \
  wifi-sec.key-mgmt wpa-eap \
  802-1x.eap tls \
  802-1x.identity "user@corp.com" \
  802-1x.ca-cert /etc/pki/tls/ca.pem \
  802-1x.client-cert /etc/pki/tls/client.pem \
  802-1x.private-key /etc/pki/tls/client-key.pem \
  802-1x.private-key-password "keypassword"

6.4. Hidden Networks#

nmcli connection add type wifi ifname wlan0 con-name "Hidden Net" \
  ssid "HiddenSSID" \
  wifi.hidden yes \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "mypassword"

6.5. WiFi Hotspot#

# Create a hotspot
nmcli device wifi hotspot ifname wlan0 ssid "MyHotspot" password "hotspotpass"

# Create with specific band and channel
nmcli connection add type wifi ifname wlan0 con-name "Hotspot" \
  ssid "MyHotspot" \
  wifi.mode ap \
  wifi.band bg \
  wifi.channel 6 \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "hotspotpass" \
  ipv4.method shared

7. Bonding Interfaces#

# Create a bond interface (LACP)
nmcli connection add type bond ifname bond0 con-name "Bond LACP" \
  bond.options "mode=802.3ad,miimon=100"

# Add physical interfaces as slaves
nmcli connection add type ethernet slave-type bond ifname eth0 master bond0
nmcli connection add type ethernet slave-type bond ifname eth1 master bond0

# Activate
nmcli connection up "Bond LACP"

Common bonding modes:

ModeNameDescription
0balance-rrRound-robin for load balancing
1active-backupOne active, others standby
2balance-xorXOR-based load balancing
4802.3adLACP (requires switch support)
5balance-tlbAdaptive transmit load balancing
6balance-albAdaptive load balancing

8. Bridge Connections#

# Create a bridge
nmcli connection add type bridge ifname br0 con-name "Bridge" stp no

# Add an interface to the bridge
nmcli connection add type bridge-slave ifname eth0 master br0

# Set bridge IP
nmcli connection modify "Bridge" ipv4.addresses 192.0.2.1/24 ipv4.method manual

# Activate
nmcli connection up bridge-slave-eth0
nmcli connection up "Bridge"

Bridge options:

# Enable STP with specific settings
nmcli connection modify "Bridge" bridge.stp yes
nmcli connection modify "Bridge" bridge.priority 32768
nmcli connection modify "Bridge" bridge.forward-delay 15
nmcli connection modify "Bridge" bridge.hello-time 2
nmcli connection modify "Bridge" bridge.max-age 20

9. VLAN Configuration#

# Create VLAN 100 on eth0
nmcli connection add type vlan ifname eth0.100 con-name "VLAN 100" \
  dev eth0 id 100 \
  ipv4.addresses 198.51.100.10/24 \
  ipv4.method manual

# Activate
nmcli connection up "VLAN 100"

10. VPN Connections#

Warning: PPTP is considered insecure (MS-CHAPv2 is broken). Use WireGuard or OpenVPN instead.

10.1. OpenVPN#

Requires: NetworkManager-openvpn (RHEL/Fedora) or network-manager-openvpn (Debian/Ubuntu)

# Install the plugin
sudo apt install network-manager-openvpn    # Debian/Ubuntu
sudo dnf install NetworkManager-openvpn      # Fedora/RHEL

# Import an existing .ovpn file (easiest method)
nmcli connection import type openvpn file /path/to/config.ovpn

# Manual setup
nmcli connection add type vpn con-name "Office VPN" ifname "*" \
  vpn-type openvpn \
  vpn.data "remote=vpn.example.com, connection-type=tls, \
    ca=/etc/openvpn/ca.crt, \
    cert=/etc/openvpn/client.crt, \
    key=/etc/openvpn/client.key"

# Connect
nmcli connection up "Office VPN"

# Set username/password for password-based auth
nmcli connection modify "Office VPN" vpn.data "remote=vpn.example.com, connection-type=password"
nmcli connection modify "Office VPN" vpn.secrets "password=mypassword"

10.2. WireGuard#

NetworkManager 1.16+ has native WireGuard support.

# Import a WireGuard config file
nmcli connection import type wireguard file /path/to/wg0.conf

# Manual setup
nmcli connection add type wireguard con-name "wg0" ifname wg0 autoconnect no
nmcli connection modify wg0 wireguard.private-key "<PRIVATE_KEY>"
nmcli connection modify wg0 +wireguard.peer \
  "<PUBLIC_KEY>, endpoint=<SERVER_IP>:51820, allowed-ips=0.0.0.0/0;::/0, persistent-keepalive=25"
nmcli connection modify wg0 ipv4.addresses "192.0.2.2/24"
nmcli connection modify wg0 ipv4.method manual

# Optional: route only VPN subnet (split tunnel)
nmcli connection modify wg0 ipv4.never-default yes
nmcli connection modify wg0 ipv4.routes "192.0.2.0/24"

# Connect
nmcli connection up wg0

10.3. AnyConnect (OpenConnect)#

Requires: NetworkManager-openconnect or network-manager-openconnect

# Install the plugin
sudo apt install network-manager-openconnect    # Debian/Ubuntu
sudo dnf install NetworkManager-openconnect      # Fedora/RHEL

# Create the connection
nmcli connection add type vpn con-name "AnyConnect VPN" ifname "*" \
  vpn-type openconnect \
  vpn.data "gateway=vpn.example.com, protocol=anyconnect"

# Connect (will prompt for credentials)
nmcli connection up "AnyConnect VPN"

# For GlobalProtect protocol
nmcli connection add type vpn con-name "GlobalProtect" ifname "*" \
  vpn-type openconnect \
  vpn.data "gateway=vpn.example.com, protocol=gp"

Note: AnyConnect/OpenConnect VPNs typically require interactive authentication (SAML, MFA). The nmcli connection up command may prompt for credentials, or you may need to use openconnect directly and hand off to NetworkManager.

10.4. IPsec (StrongSwan)#

Requires: NetworkManager-strongswan or network-manager-strongswan

# Install the plugin
sudo apt install network-manager-strongswan    # Debian/Ubuntu
sudo dnf install NetworkManager-strongswan      # Fedora/RHEL

# Pre-shared key setup
nmcli connection add type vpn vpn-type strongswan con-name "IPsec VPN" \
  ifname "*" autoconnect no \
  ipv4.method auto \
  vpn.data "address=<gateway>, method=psk"
nmcli connection modify "IPsec VPN" vpn.secrets "pskvalue=<your-psk>"

# IKEv2 with certificate
nmcli connection modify "IPsec VPN" +vpn.data \
  "leftid=<your-id>, rightid=<gateway-id>, keyexchange=ikev2, \
   certificate=/path/to/client.pem"

# Connect
nmcli connection up "IPsec VPN"

10.5. PPTP (Deprecated)#

Warning: PPTP is cryptographically broken. Use only if no alternative exists.

Requires: NetworkManager-pptp or network-manager-pptp

nmcli connection add type vpn con-name "PPTP Legacy" ifname "*" \
  vpn-type pptp \
  vpn.data "gateway=<pptp-server>" \
  vpn.secrets "password=<password>"
nmcli connection modify "PPTP Legacy" vpn.data "user=<username>"

11. Modifying Connections#

11.1. Static IPv4#

nmcli connection modify <name> ipv4.addresses "192.0.2.100/24"
nmcli connection modify <name> ipv4.gateway "192.0.2.1"
nmcli connection modify <name> ipv4.dns "8.8.8.8,1.1.1.1"
nmcli connection modify <name> ipv4.method manual

# Add a secondary IP address
nmcli connection modify <name> +ipv4.addresses "192.0.2.101/24"

# Add static routes
nmcli connection modify <name> +ipv4.routes "10.0.0.0/8 192.0.2.254"
nmcli connection modify <name> +ipv4.routes "172.16.0.0/12 192.0.2.254 100"

# Apply changes
nmcli connection up <name>

11.2. DNS Configuration#

# Set DNS servers
nmcli connection modify <name> ipv4.dns "8.8.8.8,8.8.4.4"

# Set DNS search domains
nmcli connection modify <name> ipv4.dns-search "example.com,corp.local"

# Prevent DHCP from overwriting DNS settings
nmcli connection modify <name> ipv4.ignore-auto-dns yes

# Set DNS priority (lower = higher priority; negative values = exclusive)
nmcli connection modify <name> ipv4.dns-priority -100

11.3. Disabling IPv6#

# Disable IPv6 entirely
nmcli connection modify <name> ipv6.method disabled

# Ignore IPv6 (legacy method)
nmcli connection modify <name> ipv6.method ignore

# Link-local only (no global IPv6, but fe80:: works)
nmcli connection modify <name> ipv6.method link-local

11.4. MAC Address Randomization#

# Randomize MAC on each connection (WiFi)
nmcli connection modify <name> wifi.cloned-mac-address random

# Randomize MAC on each scan (WiFi)
nmcli connection modify <name> wifi.mac-address-randomization always

# Set a specific MAC
nmcli connection modify <name> wifi.cloned-mac-address "AA:BB:CC:DD:EE:FF"

# Restore permanent MAC
nmcli connection modify <name> wifi.cloned-mac-address permanent

# For Ethernet
nmcli connection modify <name> 802-3-ethernet.cloned-mac-address random

12. Connection Profiles and Autoconnect#

# Enable autoconnect
nmcli connection modify <name> connection.autoconnect yes

# Disable autoconnect
nmcli connection modify <name> connection.autoconnect no

# Set autoconnect priority (higher = preferred)
nmcli connection modify <name> connection.autoconnect-priority 100

# Set connection to specific zone (for firewalld integration)
nmcli connection modify <name> connection.zone internal

# Rename a connection
nmcli connection modify <name> connection.id "New Name"

# Clone a connection profile
nmcli connection clone <name> "Cloned Profile"

# Export connection details
nmcli connection show <name>

13. Dispatcher Scripts#

NetworkManager runs scripts in /etc/NetworkManager/dispatcher.d/ when connection states change. Scripts receive the interface name and action as arguments.

#!/bin/bash
# /etc/NetworkManager/dispatcher.d/99-custom
# Arguments: $1 = interface, $2 = action

INTERFACE=$1
ACTION=$2

case "$ACTION" in
    up)
        logger "NM: $INTERFACE came up"
        # Add custom routes, start services, etc.
        ;;
    down)
        logger "NM: $INTERFACE went down"
        ;;
    vpn-up)
        logger "NM: VPN on $INTERFACE connected"
        ;;
    vpn-down)
        logger "NM: VPN on $INTERFACE disconnected"
        ;;
esac

Make the script executable:

sudo chmod 755 /etc/NetworkManager/dispatcher.d/99-custom

Available actions: pre-up, up, pre-down, down, vpn-pre-up, vpn-up, vpn-pre-down, vpn-down, hostname, dhcp4-change, dhcp6-change, connectivity-change.

14. Tips and Tricks#

# Quick connect/disconnect
nmcli connection up <name>
nmcli connection down <name>

# Quick WiFi connect
nmcli device wifi connect <SSID> password <password>

# Show full connection details in a parseable format
nmcli -t -f all connection show <name>

# Monitor connection changes in real time
nmcli monitor

# Show device details including IP, DNS, routes
nmcli device show <interface>

# Generate a QR code for WiFi sharing (requires qrencode)
nmcli device wifi show-password

# Temporarily disable NetworkManager management of a device
nmcli device set <interface> managed no

# Re-enable management
nmcli device set <interface> managed yes

# Ignore specific interfaces globally in /etc/NetworkManager/conf.d/unmanaged.conf:
# [keyfile]
# unmanaged-devices=interface-name:docker0;interface-name:veth*

Troubleshooting#

IssueCauseSolution
Connection profile not applyingProfile exists but is not activatedRun nmcli connection up <name>
WiFi not showing networksRadio disabled or driver issueCheck nmcli radio wifi; run nmcli device wifi rescan
DNS not resolvingDHCP overwriting custom DNSSet ipv4.ignore-auto-dns yes
VPN plugin not availablePlugin package not installedInstall NetworkManager-<vpn-type> package
Interface "unmanaged"Listed in unmanaged-devices or managed by another toolCheck /etc/NetworkManager/conf.d/ and remove unmanaged entries
Changes lost after rebootModified runtime only, not the profileUse nmcli connection modify (writes to disk) instead of nmcli device modify (runtime only)
Multiple connections activatingAutoconnect enabled on several profiles for the same deviceSet autoconnect-priority or disable autoconnect on unwanted profiles
Slow WiFi reconnectionMAC randomization causing reauthenticationSet wifi.cloned-mac-address stable for consistent but private MAC
Bridge or bond not workingSlave interfaces not properly assignedVerify with nmcli connection show; ensure slave-type and master are set
NetworkManager conflicts with systemd-networkdBoth managing the same interfacesDisable one: systemctl disable systemd-networkd

See Also#

Sources#