NetworkManager (nmcli)

Quick Reference

# Show all connections
nmcli connection show

# Show active connections
nmcli connection show --active

# Show device status
nmcli device status

# Connect to WiFi
nmcli device wifi connect "SSID" password "password"

# Bring connection up/down
nmcli connection up "Connection Name"
nmcli connection down "Connection Name"

# Show IP addresses
nmcli -g IP4.ADDRESS device show eth0

Core Concepts

Connections vs Devices

Concept Description Example

Device

Physical or virtual network interface

eth0, wlan0, enp0s3

Connection

Configuration profile for a device

Wired connection 1, Home WiFi

Active Connection

Connection currently applied to device

Listed in nmcli con show --active

A device can have multiple connection profiles, but only one active at a time.

Device Management

Viewing Devices

# List all devices with status
nmcli device status

# Detailed info for specific device
nmcli device show eth0

# Show WiFi access points
nmcli device wifi list

# Rescan WiFi networks
nmcli device wifi rescan

Device Control

# Disconnect device
nmcli device disconnect eth0

# Connect device (uses best available connection)
nmcli device connect eth0

# Set device managed/unmanaged by NetworkManager
nmcli device set eth0 managed yes
nmcli device set eth0 managed no

Connection Management

Viewing Connections

# List all connections
nmcli connection show

# List active connections only
nmcli connection show --active

# Show connection details
nmcli connection show "Connection Name"

# Show specific fields
nmcli -f NAME,UUID,TYPE,DEVICE connection show

Creating Connections

Wired (Ethernet)

# DHCP (automatic)
nmcli connection add type ethernet \
    con-name "Office Wired" \
    ifname eth0

# Static IP
nmcli connection add type ethernet \
    con-name "Server Static" \
    ifname eth0 \
    ipv4.method manual \
    ipv4.addresses "192.168.1.100/24" \
    ipv4.gateway "192.168.1.1" \
    ipv4.dns "8.8.8.8,8.8.4.4"

# With VLAN
nmcli connection add type vlan \
    con-name "VLAN10" \
    ifname vlan10 \
    dev eth0 \
    id 10

WiFi

# Connect to open network
nmcli device wifi connect "CoffeeShop"

# Connect to WPA/WPA2 network
nmcli device wifi connect "HomeNetwork" password "secretpass"

# Connect to hidden network
nmcli device wifi connect "HiddenSSID" password "pass" hidden yes

# Create WiFi connection profile
nmcli connection add type wifi \
    con-name "Work WiFi" \
    ssid "CorpNetwork" \
    wifi-sec.key-mgmt wpa-psk \
    wifi-sec.psk "password123"

# WPA2-Enterprise (EAP-TLS)
nmcli connection add type wifi \
    con-name "802.1X WiFi" \
    ssid "SecureNet" \
    wifi-sec.key-mgmt wpa-eap \
    802-1x.eap tls \
    802-1x.identity "user@domain.com" \
    802-1x.ca-cert /etc/ssl/certs/ca.pem \
    802-1x.client-cert /etc/ssl/certs/client.pem \
    802-1x.private-key /etc/ssl/private/client.key \
    802-1x.private-key-password "keypass"

Bridge

# Create bridge
nmcli connection add type bridge \
    con-name "br0" \
    ifname br0

# Add interface to bridge
nmcli connection add type ethernet \
    con-name "br0-port1" \
    ifname eth0 \
    master br0

# Bridge with static IP
nmcli connection add type bridge \
    con-name "br0" \
    ifname br0 \
    ipv4.method manual \
    ipv4.addresses "192.168.1.10/24" \
    ipv4.gateway "192.168.1.1"

Bond

# Create bond
nmcli connection add type bond \
    con-name "bond0" \
    ifname bond0 \
    bond.options "mode=802.3ad,miimon=100"

# Add slaves
nmcli connection add type ethernet \
    con-name "bond0-slave1" \
    ifname eth0 \
    master bond0

nmcli connection add type ethernet \
    con-name "bond0-slave2" \
    ifname eth1 \
    master bond0

Modifying Connections

# Change to static IP
nmcli connection modify "Wired connection 1" \
    ipv4.method manual \
    ipv4.addresses "192.168.1.50/24" \
    ipv4.gateway "192.168.1.1" \
    ipv4.dns "8.8.8.8"

# Change back to DHCP
nmcli connection modify "Wired connection 1" \
    ipv4.method auto \
    ipv4.addresses "" \
    ipv4.gateway "" \
    ipv4.dns ""

# Add secondary DNS
nmcli connection modify "Wired connection 1" \
    +ipv4.dns "1.1.1.1"

# Remove DNS entry
nmcli connection modify "Wired connection 1" \
    -ipv4.dns "1.1.1.1"

# Set connection to autoconnect
nmcli connection modify "Wired connection 1" \
    connection.autoconnect yes

# Set connection priority (higher = preferred)
nmcli connection modify "Wired connection 1" \
    connection.autoconnect-priority 100

# Restrict to specific interface
nmcli connection modify "Wired connection 1" \
    connection.interface-name eth0

Activating/Deactivating

# Activate connection
nmcli connection up "Connection Name"

# Activate on specific device
nmcli connection up "Connection Name" ifname eth0

# Deactivate connection
nmcli connection down "Connection Name"

# Reload connection files from disk
nmcli connection reload

# Re-apply connection (without down/up)
nmcli connection reload "Connection Name"
nmcli device reapply eth0

Deleting Connections

# Delete by name
nmcli connection delete "Connection Name"

# Delete by UUID
nmcli connection delete uuid 12345678-1234-1234-1234-123456789abc

# Delete multiple
nmcli connection delete "Conn1" "Conn2"

802.1X Wired Authentication

EAP-TLS (Certificate-based)

# Create 802.1X wired connection
nmcli connection add type ethernet \
    con-name "802.1X Wired" \
    ifname eth0 \
    802-1x.eap tls \
    802-1x.identity "user@domain.com" \
    802-1x.ca-cert /etc/ssl/certs/ca.pem \
    802-1x.client-cert /etc/ssl/certs/client.pem \
    802-1x.private-key /etc/ssl/private/client.key \
    802-1x.private-key-password "keypassword"

# With system certificate paths
nmcli connection add type ethernet \
    con-name "802.1X Wired" \
    ifname eth0 \
    802-1x.eap tls \
    802-1x.identity "host/workstation.domain.com" \
    802-1x.ca-cert /etc/pki/tls/certs/HOME-ROOT-CA.pem \
    802-1x.client-cert /etc/pki/tls/certs/workstation.pem \
    802-1x.private-key /etc/pki/tls/private/workstation.key

EAP-PEAP (Username/Password)

nmcli connection add type ethernet \
    con-name "PEAP Wired" \
    ifname eth0 \
    802-1x.eap peap \
    802-1x.phase2-auth mschapv2 \
    802-1x.identity "username" \
    802-1x.password "password" \
    802-1x.ca-cert /etc/ssl/certs/ca.pem

Verify 802.1X Status

# Check connection details
nmcli connection show "802.1X Wired" | grep 802-1x

# Monitor authentication
journalctl -u NetworkManager -f | grep -i "802.1x\|eap\|supplicant"

# Check wpa_supplicant status
wpa_cli -i eth0 status

IPv6 Configuration

# Disable IPv6
nmcli connection modify "Connection" ipv6.method disabled

# Enable IPv6 auto (SLAAC)
nmcli connection modify "Connection" ipv6.method auto

# Static IPv6
nmcli connection modify "Connection" \
    ipv6.method manual \
    ipv6.addresses "2001:db8::1/64" \
    ipv6.gateway "2001:db8::ffff"

# IPv6 with privacy extensions
nmcli connection modify "Connection" \
    ipv6.ip6-privacy 2

DNS Configuration

# Set DNS servers
nmcli connection modify "Connection" \
    ipv4.dns "8.8.8.8 8.8.4.4"

# Set DNS search domains
nmcli connection modify "Connection" \
    ipv4.dns-search "example.com internal.example.com"

# Ignore DHCP-provided DNS
nmcli connection modify "Connection" \
    ipv4.ignore-auto-dns yes

# DNS priority (lower = preferred, default 100)
nmcli connection modify "Connection" \
    ipv4.dns-priority 10

Routing

Static Routes

# Add static route
nmcli connection modify "Connection" \
    +ipv4.routes "10.0.0.0/8 192.168.1.254"

# Add route with metric
nmcli connection modify "Connection" \
    +ipv4.routes "10.0.0.0/8 192.168.1.254 100"

# Multiple routes
nmcli connection modify "Connection" \
    ipv4.routes "10.0.0.0/8 192.168.1.254, 172.16.0.0/12 192.168.1.254"

# Remove route
nmcli connection modify "Connection" \
    -ipv4.routes "10.0.0.0/8 192.168.1.254"

# View routes
nmcli connection show "Connection" | grep route

Default Gateway

# Set gateway
nmcli connection modify "Connection" \
    ipv4.gateway "192.168.1.1"

# Never use as default route
nmcli connection modify "Connection" \
    ipv4.never-default yes

# Route metric (lower = preferred)
nmcli connection modify "Connection" \
    ipv4.route-metric 50

Output Formatting

Terse Mode (Scripting)

# Terse output (colon-separated)
nmcli -t connection show

# Terse with specific fields
nmcli -t -f NAME,UUID,TYPE connection show

# Get single value
nmcli -t -f IP4.ADDRESS device show eth0

# Example: Get IP address for scripting
IP=$(nmcli -t -f IP4.ADDRESS device show eth0 | cut -d: -f2 | cut -d/ -f1)
echo "IP is: $IP"

Field Selection

# Specific fields
nmcli -f NAME,TYPE,DEVICE connection show

# All fields
nmcli -f ALL connection show "Connection Name"

# Common useful fields
nmcli -f NAME,UUID,TYPE,DEVICE,STATE connection show
nmcli -f GENERAL,IP4,IP6 device show eth0

Colors and Formatting

# Disable colors (for scripts)
nmcli -c no connection show

# Pretty output
nmcli -p connection show

# Multiline output
nmcli -m multiline connection show "Connection Name"

Monitoring and Events

# Monitor all changes
nmcli monitor

# Watch connection state
watch -n1 'nmcli connection show --active'

# Monitor specific device
nmcli device monitor eth0

NetworkManager Service

# Check service status
systemctl status NetworkManager

# Restart NetworkManager
sudo systemctl restart NetworkManager

# View logs
journalctl -u NetworkManager -f

# Debug logging
sudo nmcli general logging level DEBUG domains ALL
# Reset to normal
sudo nmcli general logging level INFO domains DEFAULT

Troubleshooting

Connection Won’t Activate

# 1. Check device status
nmcli device status

# 2. Check connection config
nmcli connection show "Connection Name"

# 3. Try manual activation with verbose
nmcli --show-secrets connection up "Connection Name"

# 4. Check logs
journalctl -u NetworkManager --since "5 minutes ago"

# 5. Check if device is managed
nmcli device show eth0 | grep GENERAL.STATE

WiFi Issues

# Rescan for networks
nmcli device wifi rescan

# List available networks with signal strength
nmcli -f SSID,SIGNAL,SECURITY device wifi list

# Check WiFi radio status
nmcli radio wifi

# Enable/disable WiFi
nmcli radio wifi on
nmcli radio wifi off

# Forget saved network
nmcli connection delete "WiFi Network Name"

DNS Not Working

# Check DNS settings
nmcli device show eth0 | grep DNS

# Check resolv.conf
cat /etc/resolv.conf

# If using systemd-resolved
resolvectl status

# Force DNS servers
nmcli connection modify "Connection" \
    ipv4.dns "8.8.8.8" \
    ipv4.ignore-auto-dns yes
nmcli connection up "Connection"

DHCP Not Working

# Check DHCP client
journalctl -u NetworkManager | grep -i dhcp

# Force DHCP renewal
nmcli connection down "Connection"
nmcli connection up "Connection"

# Check lease file
ls -la /var/lib/NetworkManager/

# Manual DHCP request (debugging)
sudo dhclient -v eth0

Connection Files

NetworkManager stores connections in:

# System connections (require root)
/etc/NetworkManager/system-connections/

# View connection file
sudo cat /etc/NetworkManager/system-connections/"Connection Name.nmconnection"

# After manual edit, reload
sudo nmcli connection reload

Connection File Format

[connection]
id=My Connection
uuid=12345678-1234-1234-1234-123456789abc
type=ethernet
interface-name=eth0

[ethernet]

[ipv4]
method=manual
addresses=192.168.1.100/24
gateway=192.168.1.1
dns=8.8.8.8;8.8.4.4;

[ipv6]
method=auto

Dispatcher Scripts

Scripts that run on network events:

# Location
/etc/NetworkManager/dispatcher.d/

# Script receives: interface action
# Actions: up, down, pre-up, pre-down, dhcp4-change, etc.
Example dispatcher script
#!/bin/bash
# /etc/NetworkManager/dispatcher.d/10-update-etc-hosts

INTERFACE=$1
ACTION=$2

if [ "$ACTION" = "up" ]; then
    # Do something when interface comes up
    logger "Interface $INTERFACE is up"
fi

Advanced Scripting & Data Extraction

Valid Field Names

Different nmcli subcommands accept different fields.
Command Valid Fields

device show

GENERAL, CAPABILITIES, INTERFACE-FLAGS, IP4, DHCP4, IP6, DHCP6, CONNECTIONS

connection show

NAME, UUID, TYPE, TIMESTAMP, AUTOCONNECT, DEVICE, STATE, FILENAME

device status

DEVICE, TYPE, STATE, CONNECTION

Extracting IP Addresses

# Get IP for specific device (cleanest)
nmcli -g IP4.ADDRESS device show eno1
# Output: 192.168.1.225/24

# Get IP without CIDR prefix
nmcli -g IP4.ADDRESS device show eno1 | cut -d/ -f1
# Output: 192.168.1.225

# Get all IPs with device names using awk
nmcli -p device show | awk '/GENERAL.DEVICE:/{dev=$2} /IP4.ADDRESS\[1\]:/{print dev": "$2}'
# Output:
# eno1: 192.168.1.225/24
# virbr0: 10.50.1.99/24

# Get IP for scripting (into variable)
MY_IP=$(nmcli -g IP4.ADDRESS device show eno1 | cut -d/ -f1)
echo "My IP is: $MY_IP"

Listing Connections with Devices

# Active connections with their devices (terse, script-friendly)
nmcli -t -f NAME,DEVICE connection show --active
# Output:
# Wired connection 1:eno1
# virbr0:virbr0

# Parse with awk - show only ethernet connections
nmcli -t -f NAME,DEVICE,TYPE connection show --active | awk -F: '$3=="ethernet"{print $1" -> "$2}'
# Output: Wired connection 1 -> eno1

# Get connection name for a device
nmcli -t -f NAME,DEVICE connection show --active | awk -F: -v dev="eno1" '$2==dev{print $1}'
# Output: Wired connection 1

Device Status with awk

# List only connected devices
nmcli -t device status | awk -F: '$3=="connected"{print $1}'

# Show device + connection pairs
nmcli -t device status | awk -F: '$3=="connected" && $4!=""{printf "%-12s %s\n", $1, $4}'

# Count connected devices
nmcli -t device status | awk -F: '$3=="connected"{count++} END{print "Connected devices:", count}'

# Find devices without connections
nmcli -t device status | awk -F: '$3=="disconnected"{print $1" is disconnected"}'

Comprehensive IP Report

# All devices with IPs (combining commands)
echo "=== Network Interfaces ===" && \
nmcli -p device show | grep -E "GENERAL.DEVICE:|IP4.ADDRESS" | \
awk '/DEVICE:/{dev=$2} /ADDRESS/{print dev": "$2}'

# One-liner for all IPs in CIDR format
for dev in $(nmcli -t device status | cut -d: -f1); do
    ip=$(nmcli -g IP4.ADDRESS device show "$dev" 2>/dev/null)
    [ -n "$ip" ] && echo "$dev: $ip"
done

# Using awk for cleaner output
nmcli device show | awk '
    /^GENERAL.DEVICE:/ {device=$2}
    /^IP4.ADDRESS\[1\]:/ {print device ": " $2}
'

Connection Details with jq-style Output

# Get connection UUID by name
nmcli -t -f UUID connection show "Wired connection 1"

# Get all connection settings as key=value
nmcli -t connection show "Wired connection 1" | head -20

# Extract specific 802.1X settings
nmcli -t connection show "802.1X Wired" 2>/dev/null | grep "^802-1x"

# Parse MAC address from device
nmcli -g GENERAL.HWADDR device show eno1

Monitoring with awk

# Real-time IP changes
nmcli monitor | awk '/Connectivity/{print strftime("%H:%M:%S"), $0}'

# Watch for connection state changes
while true; do
    nmcli -t -f DEVICE,STATE device status | \
        awk -F: '{printf "%s: %s\n", $1, $2}'
    sleep 5
    echo "---"
done

Practical One-Liners

# Get default gateway
ip route | awk '/default/{print $3}'

# Get primary interface IP (the one with default route)
DEV=$(ip route | awk '/default/{print $5}')
nmcli -g IP4.ADDRESS device show "$DEV" | cut -d/ -f1

# Check if interface has IP
nmcli -g IP4.ADDRESS device show eno1 | grep -q . && echo "Has IP" || echo "No IP"

# Export all IPs as environment variables
eval $(nmcli device show | awk '
    /GENERAL.DEVICE:/ {dev=$2; gsub(/-/,"_",dev)}
    /IP4.ADDRESS\[1\]:/ {split($2,a,"/"); print "IP_"toupper(dev)"="a[1]}
')
echo $IP_ENO1  # Access like this

# Generate /etc/hosts entries from nmcli
nmcli -p device show | awk '
    /GENERAL.DEVICE:/ {dev=$2}
    /IP4.ADDRESS\[1\]:/ {split($2,a,"/"); if(a[1]!="127.0.0.1") print a[1], dev}
'

Quick Command Reference

# Status
nmcli general status              # Overall status
nmcli device status               # Device list
nmcli connection show             # All connections
nmcli connection show --active    # Active only

# WiFi
nmcli device wifi list            # Scan networks
nmcli device wifi connect SSID password PASS

# Connections
nmcli connection up NAME          # Activate
nmcli connection down NAME        # Deactivate
nmcli connection delete NAME      # Remove
nmcli connection reload           # Reload from disk

# Modify
nmcli connection modify NAME ipv4.addresses "IP/PREFIX"
nmcli connection modify NAME ipv4.gateway "GATEWAY"
nmcli connection modify NAME ipv4.dns "DNS1 DNS2"
nmcli connection modify NAME ipv4.method manual|auto

# Create
nmcli connection add type ethernet con-name NAME ifname DEVICE
nmcli connection add type wifi con-name NAME ssid SSID

# Scripting
nmcli -t -f FIELD device show DEVICE   # Terse output
nmcli -g IP4.ADDRESS device show eth0  # Get value

See Also