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:
-
OpenVSwitch support through the NM provider requires
NetworkManager-ovs
. -
Extended ovsdb support requires
openvswitch-2.11
andpython3-openvswitch2.11
or greater. -
Team interface support through the NM provider requires
NetworkManager-team
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 nmstatectl
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
- 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)