~/ 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

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"

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"
 
# Reload NetworkManager configuration
nmcli connection 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
 
# Rescan for WiFi networks
nmcli device wifi rescan

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
 
# 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

Advanced Configuration#

Bonding Interfaces#

# Create a bond interface
nmcli connection add type bond ifname bond0 con-name mybond \
    mode active-backup ip4 192.168.1.100/24
 
# Add slaves to the bond
nmcli connection add type bond-slave ifname eth0 con-name bond-slave-eth0 master mybond
nmcli connection add type bond-slave ifname eth1 con-name bond-slave-eth1 master 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#

# 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"
 
# Connect to VPN
nmcli connection up myvpn

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 systemd-resolve --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
nmcli connection 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 connection profile
nmcli connection export "MyConnection" > myconnection.nmconnection
 
# Import connection profile
nmcli connection import type ethernet file myconnection.nmconnection
 
# Clone connection with different settings
nmcli connection clone "Template-Connection" "New-Connection"
nmcli connection modify "New-Connection" ipv4.addresses "192.168.1.75/24"

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