We are Nmstate!

A declarative network manager API for hosts.

Copr build status, all repos are built for Fedora Linux and RHEL/CentOS Stream/EPEL 8+:

• Latest release:
• Git base:

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.

State example:

Desired/Current state example (YAML):

interfaces:
- name: eth1
  type: ethernet
  state: up
  ipv4:
    enabled: true
    address:
    - ip: 192.0.2.10
      prefix-length: 24
    dhcp: false
  ipv6:
    enabled: true
    address:
    - ip: 2001:db8:1::a
      prefix-length: 64
    autoconf: false
    dhcp: false
dns-resolver:
  config:
    search:
    - example.com
    - example.org
    server:
    - 2001:4860:4860::8888
    - 8.8.8.8
routes:
  config:
  - destination: 0.0.0.0/0
    next-hop-address: 192.0.2.1
    next-hop-interface: eth1
  - destination: ::/0
    next-hop-address: 2001:db8:1::1
    next-hop-interface: eth1

Basic Operations

Show eth0 current state (python/shell):

import libnmstate

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

# Here is the MAC address
eth0_mac = eth0_state['mac-address']

nmstatectl show eth0

Change to desired state (python/shell):

import libnmstate

# Specify a Linux bridge (created if it does not exist).
state = {'interfaces': [{'name': 'br0', 'type': 'linux-bridge', 'state': 'up'}]}
libnmstate.apply(state)

# use yaml or json formats
nmstatectl set desired-state.yml
nmstatectl set desired-state.json

Edit the current state(python/shell):

import libnmstate

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

# take eth0 down
eth0_state['state'] = 'down'
libnmstate.apply(state)

# open current state in a text editor, change and save to apply
nmstatectl edit eth3

Contact

Nmstate uses the [email protected] for discussions. To subscribe you can send an email with 'subscribe' in the subject to [email protected] or visit the mailing list page.

Sprint tracking happens in (Github projects).

There is also #nmstate on Libera IRC.

Contributing

Yay! We are happy to accept new contributors to the Nmstate project. Please follow these instructions to contribute.

Installation

For Fedora 29+, sudo dnf install nmstate.

For others distribution, please see the install guide.

Documentation

• libnmstate API
• Code examples
• State examples
• nmstatectl user guide
• nmstatectl man page: man nmstatectl

Limitations

• Maximum supported number of interfaces in a single desire state is 1000.

Changelog

Please refer to CHANGELOG