~/ linuxnetwork.net

Mastering nmcli: The Ultimate Guide to NetworkManager Command-Line Tool

In today's networked world, managing connections efficiently is crucial for system administrators and developers alike. While graphical tools provide user-friendly interfaces, command-line tools offer unparalleled power, scripting capabilities, and remote management options. Enter nmcli - NetworkManager's command-line interface that brings robust network management capabilities to your terminal.

nmcli is not just another network configuration tool; it's a comprehensive solution that allows you to control every aspect of NetworkManager without leaving your command line. Whether you're managing servers headlessly, automating network configurations, or troubleshooting connectivity issues, nmcli provides the tools you need.

Table of Contents#

  1. Introduction
  2. Understanding NetworkManager
  3. nmcli Basics
  4. Network Connection Management
  5. Device Management
  6. Monitoring and Status
  7. Advanced Configuration
  8. Troubleshooting and Common Scenarios
  9. Best Practices
  10. Conclusion
  11. References

Understanding NetworkManager#

Before diving into nmcli, it's essential to understand what NetworkManager is:

NetworkManager is a dynamic network control and configuration system that:

  • Manages network interfaces and connections
  • Handles both wired and wireless connections
  • Provides automatic network detection and selection
  • Supports VPN connections and mobile broadband
  • Offers D-Bus interface for programmatic control

Key Components:

  • Devices: Physical or virtual network interfaces (eth0, wlan0, etc.)
  • Connections: Configuration profiles that define how to connect to networks
  • Settings: Specific parameters within connections (IP addresses, DNS, etc.)

nmcli Basics#

Installation and Verification#

Most modern Linux distributions come with nmcli pre-installed. To verify:

# Check if nmcli is available
nmcli --version
 
# Check NetworkManager status
systemctl status NetworkManager
 
# Ensure NetworkManager is running
sudo systemctl start NetworkManager
sudo systemctl enable NetworkManager

Basic Syntax#

nmcli [OPTIONS] OBJECT { COMMAND | help }

Common OBJECT types:

  • general - General NetworkManager status
  • networking - Overall networking control
  • radio - WiFi radio switches
  • connection - Network connections
  • device - Network devices
  • monitor - Monitor changes
  • agent - Secret and polkit agent

Useful global options:

  • --pretty (-p) - Human-readable aligned output
  • --terse (-t) - Machine-parseable output (for scripts)
  • --mode {tabular|multiline} - Output format
  • --show-secrets (-s) - Display passwords and secrets
  • --ask (-a) - Prompt for missing input (not for scripts)
  • --fields (-f) - Specify which fields to display
  • --version (-v) - Show nmcli version

Network Connection Management#

Listing Connections#

# List all connections
nmcli connection show
 
# Show active connections only
nmcli connection show --active
 
# Show detailed information for a specific connection
nmcli connection show "MyConnection"
 
# Show connection secrets (passwords)
nmcli connection show "MyConnection" --show-secrets

Creating Connections#

Wired Connection:

# Create a simple wired connection with DHCP
nmcli connection add type ethernet ifname eth0 con-name "MyWired"
 
# Create wired connection with static IP
nmcli connection add type ethernet ifname eth0 con-name "StaticLAN" \
    ip4 192.168.1.100/24 gw4 192.168.1.1

WiFi Connection:

# Scan for available networks
nmcli device wifi list
 
# Connect to open WiFi
nmcli device wifi connect "MyOpenNetwork"
 
# Connect to secured WiFi
nmcli device wifi connect "MySecureNetwork" password "mypassword"
 
# Create a WiFi connection profile
nmcli connection add type wifi ifname wlan0 con-name "HomeWiFi" \
    ssid "HomeNetwork" wifi-sec.psk "mypassword"

WiFi Hotspot:

# Create a WiFi hotspot (auto-generates password)
nmcli device wifi hotspot ifname wlan0 con-name "MyHotspot"
 
# Create a hotspot with specific settings
nmcli device wifi hotspot ifname wlan0 con-name "MyHotspot" \
    ssid "MyHotspotSSID" band bg channel 6 password "mypassword"
 
# Show the hotspot password
nmcli --show-secrets connection show "MyHotspot" | grep wifi-sec.psk
 
# Stop the hotspot
nmcli connection down "MyHotspot"

Modifying Connections#

# Modify IP address
nmcli connection modify "MyConnection" ipv4.addresses "192.168.1.50/24"
 
# Add secondary IP address
nmcli connection modify "MyConnection" +ipv4.addresses "10.0.0.10/24"
 
# Change gateway
nmcli connection modify "MyConnection" ipv4.gateway "192.168.1.1"
 
# Set DNS servers
nmcli connection modify "MyConnection" ipv4.dns "8.8.8.8,8.8.4.4"
 
# Set DNS search domain
nmcli connection modify "MyConnection" ipv4.dns-search "example.com"
 
# Configure method (manual, auto, disabled)
nmcli connection modify "MyConnection" ipv4.method manual

Connection Control#

# Activate a connection
nmcli connection up "MyConnection"
 
# Deactivate a connection
nmcli connection down "MyConnection"
 
# Delete a connection
nmcli connection delete "MyConnection"
 
# Edit a connection interactively
nmcli connection edit "MyConnection"
 
# Reload connection profiles from disk (after manual edits to config files)
nmcli connection reload
 
# Reload NetworkManager configuration and flush caches
sudo nmcli general reload

Device Management#

Listing Devices#

# Show all devices
nmcli device status
 
# Show detailed device information
nmcli device show
 
# Show specific device details
nmcli device show eth0

Device Control#

# Connect a device using available connections
nmcli device connect eth0
 
# Disconnect a device
nmcli device disconnect wlan0
 
# Check device WiFi capabilities
nmcli device wifi
 
# List available WiFi access points
nmcli device wifi list
 
# Rescan for WiFi networks
nmcli device wifi rescan
 
# Set device properties
nmcli device set eth0 managed yes
nmcli device set eth0 autoconnect yes

Monitoring and Status#

Real-time Monitoring#

# Monitor NetworkManager changes in real-time
nmcli monitor
 
# Monitor specific connection
nmcli connection monitor "MyConnection"
 
# Monitor specific device
nmcli device monitor wlan0

Status Information#

# General NetworkManager status
nmcli general status
 
# Get or set the system hostname
nmcli general hostname
nmcli general hostname "myserver"
 
# Networking overall status
nmcli networking connectivity
nmcli networking on/off
 
# Radio status (WiFi, WWAN, etc.)
nmcli radio
nmcli radio wifi on/off
nmcli radio wwan on/off

Secret and Polkit Agent#

On headless or remote systems without a desktop environment, you can run nmcli as a secret agent to handle password prompts or polkit authorization requests:

# Run nmcli as a NetworkManager secret agent (handles password prompts)
nmcli agent secret
 
# Run nmcli as a polkit agent (handles authorization requests)
nmcli agent polkit
 
# Run as both secret and polkit agent
nmcli agent all

Advanced Configuration#

Bonding Interfaces#

# Create a bond interface
nmcli connection add type bond ifname bond0 con-name mybond \
    bond.options "mode=active-backup" ipv4.method manual \
    ipv4.addresses 192.168.1.100/24
 
# Add ports to the bond (use ethernet type with controller property)
nmcli connection add type ethernet ifname eth0 con-name bond-port-eth0 \
    controller mybond
nmcli connection add type ethernet ifname eth1 con-name bond-port-eth1 \
    controller mybond

VLAN Configuration#

# Create VLAN interface
nmcli connection add type vlan con-name myvlan dev eth0 id 100 \
    ip4 192.168.100.10/24

Bridge Configuration#

# Create bridge interface
nmcli connection add type bridge con-name mybridge ifname br0
 
# Add interface to bridge
nmcli connection add type bridge-slave con-name bridge-slave-eth0 \
    ifname eth0 master mybridge

VPN Connections#

NetworkManager supports multiple VPN types through plugins, including OpenVPN and WireGuard (native support since NetworkManager 1.16).

OpenVPN:

# Add OpenVPN connection
nmcli connection add type vpn con-name myvpn vpn-type openvpn \
    ifname "" vpn.data "remote=vpns.example.com, username=myuser" \
    vpn.secrets "password=mypass"
 
# Import an existing OpenVPN configuration file
nmcli connection import type openvpn file ~/myvpn.ovpn
 
# Connect to VPN
nmcli connection up myvpn

WireGuard:

# Import an existing WireGuard configuration file
nmcli connection import type wireguard file /etc/wireguard/wg0.conf
 
# Or create a WireGuard connection manually
nmcli connection add type wireguard con-name mywg \
    wireguard.private-key "YOUR_PRIVATE_KEY" \
    wireguard.listen-port 51820 \
    ipv4.method manual ipv4.addresses 10.0.0.2/24 \
    ipv4.dns "10.0.0.1" \
    +wireguard.peer.public-key "PEER_PUBLIC_KEY" \
    +wireguard.peer.endpoint "vpn.example.com:51820" \
    +wireguard.peer.allowed-ips "0.0.0.0/0"
 
# Connect to WireGuard VPN
nmcli connection up mywg

Troubleshooting and Common Scenarios#

Connection Issues#

# Check if device is managed by NetworkManager
nmcli device status
 
# If device is unmanaged, set it to managed
nmcli device set eth0 managed yes
 
# Check connection ordering (higher number = higher priority)
nmcli connection show --order
 
# Change connection priority
nmcli connection modify "MyConnection" connection.autoconnect-priority 10

DNS Issues#

# Check current DNS configuration
nmcli connection show --active | grep dns
 
# Flush DNS cache (systemd-resolved)
sudo resolvectl flush-caches
 
# Set DNS per connection
nmcli connection modify "MyConnection" ipv4.ignore-auto-dns yes
nmcli connection modify "MyConnection" ipv4.dns "8.8.8.8"

Common Troubleshooting Commands#

# Restart NetworkManager
sudo systemctl restart NetworkManager
 
# Check NetworkManager logs
journalctl -u NetworkManager
 
# Reload all connections from disk
nmcli connection reload
 
# Reload NetworkManager configuration
sudo nmcli general reload
 
# Check connectivity
nmcli networking connectivity
 
# Test connection without activating
nmcli connection up "MyConnection" --ask

Best Practices#

1. Naming Conventions#

# Use descriptive connection names
nmcli connection add type ethernet ifname eth0 con-name "Office-LAN"
nmcli connection add type wifi ifname wlan0 con-name "Home-WiFi-5GHz"

2. Backup Configurations#

# Backup all connections
mkdir ~/network-backups
nmcli connection show > ~/network-backups/connections-list.txt
sudo cp -r /etc/NetworkManager/system-connections/ ~/network-backups/

3. Scripting and Automation#

#!/bin/bash
# Example: Script to setup work network
 
CONNECTION_NAME="Work-LAN"
INTERFACE="eth0"
 
if ! nmcli connection show "$CONNECTION_NAME" &> /dev/null; then
    nmcli connection add type ethernet ifname $INTERFACE \
        con-name "$CONNECTION_NAME" \
        ip4 10.0.0.50/24 \
        gw4 10.0.0.1 \
        ipv4.dns "10.0.0.2" \
        ipv4.dns-search "company.local"
    echo "Connection $CONNECTION_NAME created"
fi
 
nmcli connection up "$CONNECTION_NAME"

4. Security Practices#

# Use secure permissions for connection files
sudo chmod 600 /etc/NetworkManager/system-connections/*
 
# Avoid storing passwords in plain text when possible
nmcli connection modify "SecureWiFi" wifi-sec.psk-flags 1

5. Profile Management#

# Export a VPN connection profile (export is only supported for VPN connections)
nmcli connection export "MyVPN" > myvpn.ovpn
 
# Import a VPN connection profile
nmcli connection import type openvpn file myvpn.ovpn
 
# Import a WireGuard configuration
nmcli connection import type wireguard file /etc/wireguard/wg0.conf
 
# Clone connection with different settings
nmcli connection clone "Template-Connection" "New-Connection"
nmcli connection modify "New-Connection" ipv4.addresses "192.168.1.75/24"

Note: nmcli connection export and import currently only support VPN connection types (OpenVPN, WireGuard, etc.). For non-VPN connections, back up the configuration files directly from /etc/NetworkManager/system-connections/.

Conclusion#

nmcli is a powerful, versatile tool that brings enterprise-grade network management capabilities to the command line. Its comprehensive feature set, combined with excellent scripting support, makes it indispensable for system administrators, DevOps engineers, and power users.

By mastering nmcli, you gain:

  • Efficiency: Manage networks faster than with GUI tools
  • Automation: Script complex network configurations
  • Remote Management: Control networks over SSH
  • Consistency: Ensure uniform configurations across systems
  • Troubleshooting: Quickly diagnose and resolve network issues

Remember that while nmcli might have a learning curve, the investment pays off in increased productivity and network reliability. Start with basic commands, practice common scenarios, and gradually incorporate advanced features into your workflow.

References#

  1. Official Documentation:

  2. Useful Resources:

  3. Cheat Sheets:

    • nmcli --help
    • nmcli connection --help
    • nmcli device --help

  4. Related Tools:

    • nmtui - Text-based UI for NetworkManager
    • nm-connection-editor - GUI connection editor
    • nmtui-connect - Interactive connection manager

Remember to always test network changes in a non-production environment first, and keep backups of your important connection configurations!

2026-03