Background & Why It’s Time to Rethink Your Workflow
If you have ever administered a Linux server, you are likely familiar with the tedious task of typing dozens of lengthy nmcli commands. Or even worse, digging through and manually editing keyfiles in /etc/NetworkManager/system-connections/. I have been running Fedora Server for my home lab and KVM virtual machine clusters for over two years. Every time I rebuild a 3–4 node cluster, configuring physical network interfaces and setting up bridges eats up at least 30 minutes, and a typo in an IP address is all too easy to make.
Manual network configuration follows the imperative approach (Imperative). It is like walking into a coffee shop and having to instruct the barista step-by-step: "Grab a cup, measure 30ml of condensed milk, pour the coffee, add ice, and shake it five times."
If the barista forgets a single step or the shop runs out of ice halfway through, the whole process breaks down. The same goes for servers: a single typo assigning the wrong gateway or an accidental route conflict will instantly drop your SSH session. At that point, your only rescue options are plugging in a physical console monitor or logging into your VPS provider’s web VNC console.
Nmstate takes a declarative approach (Declarative). You simply specify the desired end state: "Get me an iced milk coffee with less sugar." For your network infrastructure, you consolidate everything into a single YAML file: what IP enp1s0 should take, where the gateway points, and which DNS servers to query. Nmstate compares the current state with the declared file, calculates the diff, and applies the new configuration in a single transaction. If anything goes wrong? The system cleanly and automatically rolls back to its previous state.
Installing on Fedora
Nmstate is available directly in Fedora’s official repositories (fully compatible with Fedora 38 through 41). The accompanying command-line tool is nmstatectl.
Installing the package is straightforward with dnf:
sudo dnf install -y nmstate
Verify that the installation was successful:
nmstatectl --version
# Example output: nmstatectl 2.2.32
Nmstate does not replace NetworkManager. Under the hood, it communicates directly with the NetworkManager daemon via the D-Bus API, leaving your operating system’s underlying networking stack completely intact.
Step-by-Step Configuration with Practical Examples
A major advantage of Nmstate is that you do not need to figure out the YAML syntax from scratch. Instead, export your machine’s current configuration to use as a starting template.
1. Export Current Network State
# Export the entire network configuration to a YAML file
nmstatectl show > network-state.yaml
# Or extract information only for the primary interface
nmstatectl show enp1s0
2. Assign Static IP and DNS via YAML
Suppose your primary network interface is enp1s0, and you need to assign a static IP of 192.168.1.50/24, a gateway of 192.168.1.1, and configure Cloudflare and Google DNS servers. Create a file named static-ip.yaml:
interfaces:
- name: enp1s0
type: ethernet
state: up
ipv4:
enabled: true
address:
- ip: 192.168.1.50
prefix-length: 24
dhcp: false
ipv6:
enabled: false
routes:
config:
- destination: 0.0.0.0/0
next-hop-address: 192.168.1.1
next-hop-interface: enp1s0
dns-resolver:
config:
server:
- 1.1.1.1
- 8.8.8.8
3. Safely Apply Configuration with Rollback
Modifying network settings remotely over SSH always carries the risk of getting locked out. Nmstate protects you with a two-step validation workflow.
Step 1: Perform a dry run to check syntax
nmstatectl apply static-ip.yaml --dry-run
If the syntax is valid, the terminal displays a diff between the current and proposed configurations without touching a single byte on the physical network interface.
Step 2: Apply with a rollback timeout
sudo nmstatectl apply static-ip.yaml --rollback-timeout 60
As soon as you hit Enter, a 60-second countdown begins. Open another terminal session and test connectivity by pinging your gateway: ping -c 3 192.168.1.1. If network connectivity is working and your SSH session remains alive, commit the changes:
sudo nmstatectl commit
Conversely, if a typo in the gateway drops your SSH session, simply wait out the 60 seconds. Nmstate will automatically revert the configuration to its prior state, restoring network access without requiring support from the NOC.
4. Create a Linux Bridge for KVM Virtual Machines
When building a virtualization lab, a bridge interface like br0 is essential so guest VMs can obtain IP addresses directly from your local router. Create a file named setup-bridge.yaml:
interfaces:
- name: br0
type: linux-bridge
state: up
ipv4:
enabled: true
dhcp: true
bridge:
port:
- name: enp1s0
- name: enp1s0
type: ethernet
state: up
ipv4:
enabled: false
Apply the bridge configuration immediately:
sudo nmstatectl apply setup-bridge.yaml --rollback-timeout 60
sudo nmstatectl commit
With just 15 lines of YAML, Nmstate handles two complex operations seamlessly: attaching the physical interface enp1s0 to the br0 bridge while disabling IPv4 on the member port and delegating DHCP resolution to the bridge interface itself.
Verification & Everyday Operations
Once committed successfully, verify the setup with standard commands:
# Check the status of the newly created bridge
nmstatectl show br0
# Inspect the default routing table
ip route show
# Check active DNS status via systemd-resolved
resolvectl status br0
Integrating Network Configuration into GitOps
Your entire network architecture is now neatly packaged into a few lightweight YAML files. You can commit these files to your internal Git repository (GitLab, GitHub).
Whenever you need to update IP ranges across 20 servers, open a Pull Request, have teammates review the diff, and use Ansible to dispatch nmstatectl apply at scale. Your revision history in git log tracks exactly who modified an IP and when. You can finally say goodbye to sticky notes on your monitor and outdated Excel network spreadsheets.
