Skip to content

Instantly share code, notes, and snippets.

@cathay4t

cathay4t/nmstate_api_doc.md

Created July 1, 2019 05:47
Show Gist options
  • Save cathay4t/98ba4269feb4c6fff06f866da94ccb78 to your computer and use it in GitHub Desktop.
Save cathay4t/98ba4269feb4c6fff06f866da94ccb78 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
nmstate_api_doc.md

Introduction

This document holds all the API detail of the libnmstate Python module. For quick start, you may refer to Python code examples

The libnmstate contains:

Query network state

Example of querying network state:

import json
import libnmstate

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

Apply network state

Nmstate support partial editing, you only need to specified the data you want to change, the undefined changes will not be touched.

Example of changing eth1 MTU to 1460:

import libnmstate

libnmstate.apply({
    'interfaces': [
        {
            'name': 'eth1',
            'type': 'ethernet',
            'mtu': 1460
        }
    ]
})

Manual Transaction Control

Error handling

TODO

Schema

The YAML schema file is placed at libnmstate/schemas/operational-state.yaml.

In stead of using hard coded string, please use classes and constants in libnmstate.schmea.

Network State Main layout

The network state is stored in a dictionary:

from libnmstate.schema import Interface
from libnmstate.schema import Route
from libnmstate.schema import DNS

network_state = {
    DNS.KEY: {},            # Check section of 'DNS'
    Route.KEY: {},          # Check section of 'Route'
    Interface.KEY: [],      # Check section of 'Interface -- Basic'
}

Basic Interface

A interface represents a hardware of software network interface. Each interface will have these basic properties stored as a dictionary. The dictionary key string are stored as constant in libnmstate.schema module.

Limitations

  • The libnmstate does not differentiate InterfaceState.DOWN and InterfaceState.ABSENT. They both remove the on-disk Network Manager connection profile of specified interface.

  • The libnmstate does not support disable IPv6 yet.

Basic Interface: Example

{
    Interface.NAME: 'eth1',
    Interface.STATE: InterfaceState.UP,
    Interface.TYPE: InterfaceType.ETHERNET,
    Interface.IPV4: {
        InterfaceIPv4.ENABLED: True
        InterfaceIPv4.DHCP: False,
        InterfaceIPv4.ADDRESS: [
            {
                InterfaceIPv4.ADDRESS_IP: '192.0.2.251',
                InterfaceIPv4.ADDRESS_PREFIX_LENGTH: 24,
            }
        ],
    },
    Interface.IPV6: {
        InterfaceIPv6.ENABLED: True
        InterfaceIPv6.DHCP: True,
        InterfaceIPv6.AUTOCONF: True,
        InterfaceIPv6.AUTO_DNS: True,
        InterfaceIPv6.AUTO_GATEWAY: True,
        InterfaceIPv6.AUTO_ROUTES: True,
        InterfaceIPv6.ADDRESS: [],
    }
}

Interface.NAME

The kernel name of interface.

Vale type: string

Interface.TYPE

The interface type.

Value type: string

Possible values:

  • InterfaceType.ETHERNET
  • InterfaceType.BOND
  • InterfaceType.LINUX_BRIDGE
  • InterfaceType.OVS_BRIDGE
  • InterfaceType.OVS_PORT
  • InterfaceType.OVS_INTERFACE
  • InterfaceType.VLAN

Interface.STATE

The interface state.

Value type: string

Possible values:

  • InterfaceState.UP

    Bring interface link up.

  • InterfaceState.DOWN

    Remove interface. Might change to bring interface link down in future release.

  • InterfaceState.ABSENT

    Remove interface.

Interface.MTU

The maximum transmission unit of interface.

Value type: interger

Interface.MAC_ADDRESS

The MAC address of interface.

Value type: String in the format of EA:60:E4:08:17:F1.

InterfaceIP

The InterfaceIP class is holding the share constants between InterfaceIPv4 and InterfaceIPv6:

  • InterfaceIP.ENABLED
  • InterfaceIP.DHCP
  • InterfaceIP.AUTO_DNS
  • InterfaceIP.AUTO_GATEWAY
  • InterfaceIP.AUTO_ROUTES
  • InterfaceIP.ADDRESS
  • InterfaceIP.ADDRESS_IP
  • InterfaceIP.ADDRESS_PREFIX_LENGTH

Interface.IPV4

The Interface.IPV4 property holds the IPv4 stack information in a dictionary.

Example:

{
    Interface.IPV4: {
        InterfaceIPv4.ENABLED: True
        InterfaceIPv4.DHCP: TRUE,
        InterfaceIPv4.ADDRESS: [],
        InterfaceIPv4.AUTO_DNS: True,
        InterfaceIPv4.AUTO_GATEWAY: True,
        InterfaceIPv4.AUTO_ROUTES: True,
    }
}

InterfaceIPv4.ENABLED

Value type: bool

Possible values:

  • True - IPv4 stack is enabled.

  • False - IPv4 stack is disabled.

When applying network state with IPv4 disabled, all the remaining IPv4 configurations will be ignored.

When showing network state, if IPv4 is disabled, all the remaining properties will not be included in returned network state.

InterfaceIPv4.DHCP

Value type: bool

Possible values:

  • True - DHCPv4 is enabled.

  • False - DHCPv4 is disabled.

InterfaceIPv4.AUTO_ROUTES

Value type: bool

Possible values:

This property only show when Interface.IPV4[InterfaceIPv4.DHCP] is True when querying.

This property will be ignored when Interface.IPV4[InterfaceIPv4.DHCP] is False when applying.

InterfaceIPv4.AUTO_GATEWAY

Value type: bool

Possible values:

  • True - Apply gateway retried from DHCPv4.

  • False - Ignore gateway retried from DHCPv4.

This property only show when Interface.IPV4[InterfaceIPv4.DHCP] is True when querying.

This property will be ignored when Interface.IPV4[InterfaceIPv4.DHCP] is False when applying.

InterfaceIPv4.AUTO_DNS

Value type: bool

Possible values:

  • True

    Apply gateway retried from DHCPv4.

  • False

    Ignore gateway retried from DHCPv4.

This property only show when Interface.IPV4[InterfaceIPv4.DHCP] is True when querying.

This property will be ignored when Interface.IPV4[InterfaceIPv4.DHCP] is False when applying.

InterfaceIPv4.ADDRESS

The static IPv4 addresses.

Value type: array of dictionary.

When Interface.IPV4[InterfaceIPv4.DHCP] set to True, the address defined in this property will also be ignored.

Example:

InterfaceIPv4.ADDRESS: [
    {
        InterfaceIPv4.ADDRESS_IP: '192.0.2.251',
        InterfaceIPv4.ADDRESS_PREFIX_LENGTH: 24,
    }
]

InterfaceIPv4.ADDRESS_IP

The static IPv4 address.

Value type: string.

Only support string in the format of 192.0.2.251.

InterfaceIPv4.ADDRESS_PREFIX_LENGTH

The prefix length of static IPv4 address.

Value type: interger.

Interface.IPV6

The Interface.IPV6 property holds the IPv6 stack information in a dictionary.

Example:

{
    Interface.IPV6: {
        InterfaceIPv6.ENABLED: True
        InterfaceIPv6.DHCP: TRUE,
        InterfaceIPv6.ADDRESS: [],
        InterfaceIPv6.AUTO_DNS: True,
        InterfaceIPv6.AUTO_GATEWAY: True,
        InterfaceIPv6.AUTO_ROUTES: True,
    }
}

InterfaceIPv6.ENABLED

Value type: bool

Possible values:

  • True - IPv6 stack is enabled.

  • False - IPv6 stack is disabled.

When applying network state with IPv6 disabled, all the remaining IPv6 configurations will be ignored.

When showing network state, if IPv6 is disabled, all the remaining properties will not be included in returned network state.

Due to the limitation of NetworkManager, Nmstate dose not support disabling IPv6 on up/active interface yet. Even with Interface.IPV6[InterfaceIPv6.DHCP] and Interface.IPV6[InterfaceIPv6.AUTOCONF] both been set to False, interface will still get the kernel auto assigned IPv6 link local address.

InterfaceIPv6.DHCP

Value type: bool

Possible values:

  • True - DHCPv6 is enabled.
  • False - DHCPv6 is disabled.

InterfaceIPv6.AUTOCONF

Value type: bool

Possible values:

  • True - Auto configuration(IPv6 router advertisement) is enabled.
  • False - Auto configuration(IPv6 router advertisement) is disabled.

Due to the limitation of NetworkManager, Nmstate does not support disabling DHCPv6 while enabling autoconf yet.

InterfaceIPv6.AUTO_ROUTES

Value type: bool

Possible values:

  • True

    Apply routes(including gateway) retrieved from IPv6 router advertisement.

  • False

    Ignore routes(including gateway) retrieved from IPv6 router advertisement.

InterfaceIPv6.IGNORE_GATEWAY

Value type: bool

Possible values:

  • True - Apply gateway retrieved from IPv6 router advertisement.

  • False - Ignore gateway retrieved from IPv6 router advertisement.

InterfaceIPv6.IGNORE_DNS

Value type: bool

Possible values:

  • True

    Apply DNS client configuration retrieved from IPv6 router advertisement and DHCPv6.

  • False

    Ignore DNS client configuration retrieved from IPv6 router advertisement and DHCPv6.

InterfaceIPv6.ADDRESS

The static IPv6 addresses.

Value type: array of dictionary.

When Interface.IPV6[InterfaceIPv6.DHCP] or Interface.IPV6[InterfaceIPv6.AUTOCONF] is set to True, the address defined in this property will also be ignored.

Example:

InterfaceIPv6.ADDRESS: [
    {
        InterfaceIPv6.ADDRESS_IP: '2001:db8:1::f',
        InterfaceIPv6.ADDRESS_PREFIX_LENGTH: 64,
    }
]

Ethernet

Beside basic interface properties, each Ethernet interface state also contains a dictionary saved in key Ethernet.CONFIG_SUBTREE.

Example:

{
    Interface.KEY: [
        Interface.NAME: "eth1",
        Interface.TYPE: InterfaceType.ETHERNET,
        Interface.STATE: InterfaceState.UP
        Ethernet.CONFIG_SUBTREE: {
            Ethernet.AUTO_NEGOTIATION: True,
            Ethernet.DUPLEX: Ethernet.FULL_DUPLEX,
            Ethernet.SPEED: 1000
        }
    ]
}

Ethernet.AUTO_NEGOTIATION

Ethernet.DUPLEX

Ethernet.SPEED

Interface -- VLAN

Interface -- Linux Bridge

Interface -- Bond

Interface -- OVS(Open vSwitch)

Route

DNS client configuration

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment