nmstate

A Declarative API for Host Network Management

View on GitHub

Quick start guide

Install

This guide is helpful to install Nmstate from source, for installing stable release or other installation methods, pleaser refer to Nmstate installation guide

Dependencies

Nmstate requires NetworkManager 1.26 or later version installed and started.

In order to support specific capabilities, additional packages are required:

Install from source

git clone https://github.com/nmstate/nmstate.git
cd nmstate
pip install --user --upgrade

Note: In order to report current state, installing Nmstate as a non-root user should be enough. For change support, install the package as root.

View state

There are two ways of using Nmstate. The first one is using nmstatectl command line tool and the other one is using the libnmstate python library.

Using nmstatecl

The following command will dump the current networking state in yaml format:

nmstatectl show

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

To dump the state in json format, use ‘–json’ flag:

nmstatectl show --json

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

Using libnmstate

The following script prints the current networking state:

import libnmstate
import json

current_state = libnmstate.show()
print(json.dumps(current_state, indent=4))

And generates the following output:

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

Set a state

Using nmstatectl

Using libnmstate

The following script modifies the state of the eth3 interface.

import libnmstate

state = libnmstate.show()
eth3_state = next(ifstate for ifstate in state['interfaces'] if ifstate['name'] == 'eth3')

# take eth3 down
eth3_state['state'] = 'down'
libnmstate.apply(state)