NMState: A Declarative Networking Config Tool for Linux

The Linux ecosystem provides numerous ways of configuring networking including the popular Network Manager daemon and command-line tools such as nmcli and nmtui GUI utility. This guide introduces yet another network configuration tool known as NMState

NMState is a declarative network manager for configuring networking on Linux hosts. It’s a library that provides a command-line tool that manages host network settings. It manages host networking through a northbound declarative API. At the time of writing this guide, the NetworkManager daemon is the only provider supported by NMState.

In this guide, we look at some of the example usages of the NMState tool. For this guide, we will demonstrate this using Fedora Linux.

Imperative vs Declarative Approaches

Network management can take two approaches – Imperative and declarative. In the imperative approach, you explicitly define the networking state of an interface by running commands on the terminal. The focus is on the ‘how’.

For example, to bring down a network using the imperative approach, run the command:

$ sudo ifconfig enp0s3 down

On the other hand, the declarative approach uses a YAML file to apply the changes to a configuration. Most DevOps orchestration tools such as Kubernetes use this approach to deploy pods applications using a YAML file.

This approach provides what is commonly referred to as Infrastructure as Code (IaC) in DevOps circles. This enhances the automation of network configuration on the host and provides a fast and more reliable way of making multiple changes to a network interface with minimal errors.

Now, let us switch gears and see how you can use the NMState configuration tool to configure your network interfaces in Linux.

Step 1: Install NMState Networking Config Tool

We will get the ball rolling by installing the Nmstate. First, check the availability of the package from Fedora repositories as follows:

$ sudo dnf search nmstate

From the output, we can see that the network manager is available on the official repositories.

Check NMState Package
Check NMState Package

Next, install NMstate as follows. This works on Fedora 31 and later versions.

$ sudo dnf install nmstate

The command installs the NMState network manager API alongside other Python dependencies.

Install NMState in Fedora
Install NMState in Fedora

Once the installation is complete, verify the nmstate package is installed as follows.

$ rpm -qi nmstate
Verify NMState Package
Verify NMState Package

For RHEL-based Linux, enable the copr repository first.

$ sudo dnf copr enable nmstate/nmstate-stable

Then install NMstate as follows.

$ sudo dnf install nmstate

Check out additional instructions on how to install NMState from the source.

Once installed, you can check the version of NMstate installed as follows.

$ nmstatectl version

1.0.2

Using NMState Configuration Tool in Linux

With NMstate installed, let us get down to the Knitty-gritties of how you can make the most of the Network manager API.

To view the current network configuration of your network interface, run the following command. Here, is the configuration of your enp0s3 interface.

$ nmstatectl show enp0s3
Show Network Interface Configuration
Show Network Interface Configuration

The output is divided into 4 distinct sections:

  • dns-resolver: This section contains the nameserver configuration for the particular interface.
  • route-rules: This stipulates the routing rules.
  • routes: This includes both dynamic and static routes.
  • Interfaces: This section specifies both the ipv4 and ipv6 settings.

Changing Network Configuration in Linux

You can use the NMState configuration tool to configure your hosts to the desired state using either interactive or file-based modes.

  • Interactive: This edits a network interface using the nmstatectl edit command. This command opens a text editor which is defined by the EDITOR environment variable. Once the changes are saved, NMState applies the new configuration immediately unless syntax errors were detected.
  • File-based: In file-based mode, the interface configuration is applied using a YAML or JSON file using the nmstatectl apply command.

Let us now get our hands dirty and check out how you can modify network configuration using NMState.

Our Fedora system has two active network interfaces with the following configuration:

$ ip -br -4 a
Sample Output
lo               UNKNOWN        127.0.0.1/8 
enp0s3           UP             192.168.2.104/24 
enp0s8           UP             192.168.2.103/24 

Interactive Configuration Mode Example

We will use interactive mode to change the MTU (Maximum Transmission Unit) of the enp0s3 network interface. By default, this is set to 1500 as shown.

$ ifconfig
Check Network MTU in Linux
Check Network MTU in Linux

We will change this to 4000. We will do so using the nmstatectl edit command as follows.

$ sudo nmstatectl edit enp0s3

This opens the configuration in a text editor. For our case, it opens in vim editor. Next, scroll all the way down and locate the mtu parameter. We will change the value to 4000, just as we would edit a file in vim. Then we will save the changes.

Change Network MTU in Linux
Change Network MTU in Linux

When you save and exit the file, you will see some scrambled output on the terminal as NMstate saves the changes. No intervention is required so, just sit still.

Let us now confirm that the change was made.

$ ifconfig

From the terminal output, we can see that we have successfully changed the MTU to 4000 from the default 1500 value.

Verify Network MTU in Linux
Verify Network MTU in Linux

File-based Configuration Mode Example

Let us now modify the configuration using file-based mode. In this example, we are going to disable IPv6 for the enp0s8 network interface. The first step is to create a YAML file that will specify the desired state of the enp0s8 network interface.

$ sudo nmstatectl show enp0s8 > enp0s8.yml
Create Network YAML File
Create Network YAML File

Next, we will edit the YAML file as follows.

$ sudo vim enp0s8.yml

Scroll down to the ipv6 section. To disable IPv6, set the enabled parameter to false and delete the lines that have been struck through.

Disable IPv6 in Linux
Disable IPv6 in Linux

Save the configuration and apply the new state using the YAML file as follows.

$ sudo nmstatectl apply enp0s8.yml

Now run the command shown to verify that IPv6 has been disabled. The output displayed shows that the IPv6 for the enp0s8 network interface is blank, implying that we have successfully disabled IPv6 on the interface.

$ ip -br a 
Confirm IPv6 Disabled in Linux
Confirm IPv6 Disabled in Linux

Applying Network Changes Temporarily

Another really handy functionality that NMstate provides is the ability to temporarily configure a desired networking state. Once you are satisfied with the configuration, you can proceed and make the changes permanent. Otherwise, the changes made will roll back to the initial settings once the timeout expires. The default timeout is 60 seconds.

To demonstrate this, we will temporarily set a static IP on the enp0s3 interface and disable DHCP. Once again, access the file using a text editor.

$ sudo vim enp0s3.yml

Scroll to the ipv4 section. Specify the static IP – in our case 192.168.2.150 and delete the lines that have been struck-through. In addition, be sure to set the dhcp parameter to false.

Set Static IP in Linux
Set Static IP in Linux

Save the file and temporarily commit the changes as follows.

$ sudo nmstatectl apply --no-commit --timeout 20 enp0s3.yml

The --no-commit option temporarily applies the changes for a period defined by the --timeout option which, in this example, is 20 seconds.

To verify the temporal application of the changes, we will check the IP configuration in a time interval of 20 seconds.

$ ip -br a 

From the output, you can see that the interface IP configuration reverted to DHCP after the time interval of 20 seconds. The IP address went back to 192.168.2.104 from the earlier statically configured IP which was 192.168.2.150.

Check Network Interface
Check Network Interface

Admittedly, the NMState tool is a convenient tool for configuring your network interfaces. It is a declarative tool that applies the desired configuration state of a host’s interface using the NetworkManager API.

The state is easily defined using either the interactive approach or using the file-based method that uses a pre-configured YAML file. This enhances the automation of configuration tasks and reduction of errors during configuration.

If you read this far, tweet to the author to show them you care. Tweet a thanks
James Kiarie
This is James, a certified Linux administrator and a tech enthusiast who loves keeping in touch with emerging trends in the tech world. When I'm not running commands on the terminal, I'm taking listening to some cool music. taking a casual stroll or watching a nice movie.

Each tutorial at TecMint is created by a team of experienced Linux system administrators so that it meets our high-quality standards.

Join the TecMint Weekly Newsletter (More Than 156,129 Linux Enthusiasts Have Subscribed)
Was this article helpful? Please add a comment or buy me a coffee to show your appreciation.

Got something to say? Join the discussion.

Thank you for taking the time to share your thoughts with us. We appreciate your decision to leave a comment and value your contribution to the discussion. It's important to note that we moderate all comments in accordance with our comment policy to ensure a respectful and constructive conversation.

Rest assured that your email address will remain private and will not be published or shared with anyone. We prioritize the privacy and security of our users.