Skip to main content

Declarative network manager API

Project description

We are Nmstate!

A declarative network manager API for hosts.

Test Status Coverage Status PyPI version Fedora Rawhide version Code Style Language grade: Python

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

  • Latest release: Latest release Copr build status
  • Git master: Git master Copr build status
  • Latest 0.2 release: Latest 0.2 release Copr build status
  • Git nmstate-0.2: Git nmstate-0.2 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.

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 nmstate-devel@lists.fedorahosted.org for discussions. To subscribe you can send an email with 'subscribe' in the subject to nmstate-devel-join@lists.fedorahosted.org or visit the mailing list page.

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

There is also #nmstate on Freenode 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 instructions.

Documentation

Limitations

Please refer to jira page for details.

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

Changelog

Please refer to CHANGELOG

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nmstate-0.3.6.tar.gz (90.1 kB view hashes)

Uploaded Source

Built Distribution

nmstate-0.3.6-py3-none-any.whl (132.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page