Skip to content
A declarative network manager API for hosts
Branch: master
Clone or download
EdDev tests integ: Refactor fixture setup of ethX interfaces
The ethX fixtures prepare the base interfaces per test by initializing
their configuration (performing a down-up action).

The existing flow has been initializing the interfaces before a test is
executed with no action taken when it ends. This causes leftovers when
testing bonds/bridges with slaves/ports, affecting the following tests.

In order to resolve the post test leftovers, adjust the test fixtures
to setup the interface at the test setup and to remove them
(set them `down`) at the test teardown.
In order to treat the initial state of the tests session execution,
where the interfaces may have an unknown state/configuration, use a
session-scoped fixture to initialize them (by setting them `down`).

Signed-off-by: Edward Haas <>
Latest commit aea3286 May 15, 2019

We are Nmstate!

A declarative network manager API for hosts.

Unit Test Status Coverage Status PyPI version Fedora Rawhide version

Copr build status:

  • EPEL 7 GIT master: EPEL7 GIT master Copr build status
  • Fedora GIT master: Fedora GIT master Copr build status

What is it?

Nmstate is a library with an accompanying command line tool that manages host networking settings in a declarative manner. The networking state is described by a pre-defined schema. Reporting of current state and changes to it (desired state) both conform to the schema.

Nmstate is aimed to satisfy enterprise needs to manage host networking through a northbound declarative API and multi provider support on the southbound. NetworkManager acts as the main (and currently the only) provider supported.


Nmstate uses the NetworkManager mailing list (Archives) for discussions. Emails about nmstate should be tagged with [nmstate] in the subject header to ease filtering.

Development planning (sprints and progress reporting) happens in (Jira). Access requires login.

There is also #nmstate on Freenode IRC.

Development Environment

Nmstate uses tox to run unit tests and linters. Since Nmstate uses the binary module PyGObject it also requires the build dependencies for it.

RHEL 7.6

Recommended minimum installation:

yum install -y  # install EPEL for python-pip
subscription-manager repos --enable "rhel-*-optional-rpms" --enable "rhel-*-extras-rpms"  # recommended for EPEL
yum install git python-pip
yum-builddep python-gobject  # install build dependencies for PyGObject
pip install tox  # python-tox in EPEL seems to be too old

CentOS 7.6

Recommended minimum installation:

yum -y install epel-release
yum -y install \
    NetworkManager \
    NetworkManager-libnm \
    git \
yum-builddep python-gobject  # install build dependencies for PyGObject
pip install tox  # python-tox in EPEL seems to be too old

Note: This will not run the unit tests for Python 3.6 because this Python version is not available there.

Unit tests

Run Unit Tests:


Runtime Environment

Install pre-requirements

Despite the pure python dependencies (see requirements.txt), Nmstate also needs NetworkManager to be running on the local system in order to configure the local network state. To access NetworkManager, Nmstate needs libnm and the corresponding introspection data (NM-1.0.typelib, provided by python-gobject-base). To manage OvS, Nmstate needs the packages NetworkManager-ovs and openvswitch. NetworkManager needs to be restarted in order to use the new configuration parameters (conf.d/97-nmstate.conf) and the OvS plugin. openvswitch service needs to be started.

NetworkManager requires special configuration snippets to overcome some existing limitations.

yum -y install epel-release
yum -y install \
    dbus-python \
    NetworkManager \
    NetworkManager-libnm \
    NetworkManager-ovs \
    openvswitch \
    python-gobject-base \
    python-ipaddress \
    python-jsonschema \
    python-setuptools \
    python2-pyyaml \
echo -e "[device]\nmatch-device=*\nmanaged=0\n" >> \
echo -e "[main]\nno-auto-default=*\n" >> \
systemctl restart NetworkManager
systemctl restart openvswitch
# To keep NetworkManager and openvswitch running after reboot:
systemctl enable --now NetworkManager openvswitch

Install nmstate from PyPi

yum -y install python2-pip
pip uninstall -y nmstate; pip install nmstate

Install nmstate from source

Install just for the local user:

pip install --user --upgrade .

Make sure that ~/.local/bin is in your PATH when installing as a local user. The export command can be used to add it for the current session:

export PATH="${HOME}/.local/bin:${PATH}"

Alternatively, install Nmstate system-wide:

pip uninstall -y nmstate; pip install .

Container Image

Nmstate also provides a container image based on CentOS 7 to try it:

CONTAINER_ID=$(sudo docker run --privileged -d -v /sys/fs/cgroup:/sys/fs/cgroup:ro nmstate/centos7-nmstate)
sudo docker exec -ti "${CONTAINER_ID}" /bin/bash
# now play with nmstatectl in the container
nmstatectl show
# remove the container at the end
sudo docker stop "${CONTAINER_ID}"
sudo docker rm "${CONTAINER_ID}"

Basic Operations

Show current state:

nmstatectl show

Change to desired state:

nmstatectl set desired-state.yml
nmstatectl set desired-state.json

Edit current state of eth3 in a text editor:

nmstatectl edit eth3

nmstatectl will also read from stdin when no file is specified:

nmstatectl set < desired-state.yml

Desired/Current state example (JSON):

    "interfaces": [
            "description": "Production Network",
            "ethernet": {
                "auto-negotiation": true,
                "duplex": "full",
                "speed": 1000
            "ipv4": {
                "address": [
                        "ip": "",
                        "prefix-length": 24
                "enabled": true
            "mtu": 1500,
            "name": "eth3",
            "state": "up",
            "type": "ethernet"

See nmstatectl --help for additional command-line options.

Supported Interfaces:

  • bond
  • dummy
  • ethernet
  • ovs-bridge
You can’t perform that action at this time.