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.40 or later version installed and started.

In order to support specific capabilities, additional package is required:

• OpenvSwitch support through the NM provider requires NetworkManager-ovs.

Install from source

git clone https://github.com/nmstate/nmstate.git
cd nmstate
PREFIX=/usr make install

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 nmstatectl

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

nmstatectl show

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

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

• Use nmstatectl show > desired_state.yaml to dump the current state to a file.
• Edit the desired state with the new values.
• Run the set command: nmstatectl apply desired_state.yaml

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)