Chapter 40. Introduction to Nmstate
Chapter 40. Introduction to Nmstate Nmstate is a declarative network manager API. When you use Nmstate, you describe the expected networking state by using YAML or JSON-formatted instructions. Nmstate has many benefits. For example, it: Provides a stable and extensible interface to manage RHEL network capabilities Supports atomic and transactional operations at the host and cluster level Supports partial editing of most properties and preserves existing settings that are not specified in the instructions Nmstate consists of the following packages: Packages Contents nmstate The nmstatectl command-line utility python3-libnmstate The libnmstate Python library nmstate-libs The Nmstate C library nmstate-devel The Nmstate C library headers 40.1. Using the libnmstate library in a Python application The libnmstate Python library enables developers to use Nmstate in their own application To use the library, import it in your source code: Note that you must install the nmstate and python3-libnmstate packages to use this library. Example 40.1. Querying the network state by using the libnmstate library The following Python code imports the libnmstate library and displays the available network interfaces and their state: import libnmstate from libnmstate.schema import Interface net_state = libnmstate.show() for iface_state in net_state[Interface.KEY]: print(iface_state[Interface.NAME] + ": " + iface_state[Interface.STATE]) 40.2. Updating the current network configuration by using nmstatectl You can use the nmstatectl utility to store the current network configuration of one or all interfaces in a file. You can then use this file to: Modify the configuration and apply it to the same system. Copy the file to a different host and configure the host with the same or modified settings. For example, you can export the settings of the enp1s0 interface to a file, modify the configuration, and apply the settings to the host. Prerequisites The nmstate package is installed. Procedure Export the settings of the enp1s0 interface to the ~/network-config.yml file: This command stores the configuration of enp1s0 in YAML format. To store the output in JSON format, pass the --json option to the command. If you do not specify an interface name, nmstatectl exports the configuration of all interfaces. Modify the ~/network-config.yml file using a text editor to update the configuration. Apply the settings from the ~/network-config.yml file: If you exported the settings in JSON format, pass the --json option to the command. 40.3. The nmstate systemd service With the nmstate package installed, you can automatically apply new network settings when the Red Hat Enterprise Linux system boots by configuring the nmstate systemd service. This service is a oneshot systemd service. Consequently, systemd executes it only when the system boots and when you manually restart the service. Note By default, the nmstate service is disabled. Use the systemctl enable nmstate command to enable it. Afterwards, systemd executes this service each time when the system starts. To use this service, store *.yml files with Nmstate instructions in the /etc/nmstate/ directory. The nmstate service then automatically applies the files on the reboot or when you manually restart the service. By default, after Nmstate successfully applies a file, it renames the file's .yml suffix to .applied to prevent the service from processing the same file again. You can configure the nmstate service in the /etc/nmstate/nmstate.conf file. For example, to preserve the original *.yml file after it was applied and to create only a copy with the .applied suffix, add the following lines to /etc/nmstate/nmstate.conf : For further details and other configuration options, see the nmstate.service(8) man page on your system. 40.4. Network states for the network RHEL system role The network RHEL system role supports state configurations in playbooks to configure the devices. For this, use the network_state variable followed by the state configurations. Benefits of using the network_state variable in a playbook: Using the declarative method with the state configurations, you can configure interfaces, and the NetworkManager creates a profile for these interfaces in the background. With the network_state variable, you can specify the options that you require to change, and all the other options will remain the same as they are. However, with the network_connections variable, you must specify all settings to change the network connection profile. Important You can set only Nmstate YAML instructions in network_state . These instructions differ from the variables you can set in network_connections . For example, to create an Ethernet connection with dynamic IP address settings, use the following vars block in your playbook: Playbook with state configurations Regular playbook vars: network_state: interfaces: - name: enp7s0 type: ethernet state: up ipv4: enabled: true auto-dns: true auto-gateway: true auto-routes: true dhcp: true ipv6: enabled: true auto-dns: true auto-gateway: true auto-routes: true autoconf: true dhcp: true vars: network_connections: - name: enp7s0 interface_name: enp7s0 type: ethernet autoconnect: yes ip: dhcp4: yes auto6: yes state: up For example, to only change the connection status of dynamic IP address settings that you created as above, use the following vars block in your playbook: Playbook with state configurations Regular playbook vars: network_state: interfaces: - name: enp7s0 type: ethernet state: down vars: network_connections: - name: enp7s0 interface_name: enp7s0 type: ethernet autoconnect: yes ip: dhcp4: yes auto6: yes state: down Additional resources /usr/share/ansible/roles/rhel-system-roles.network/README.md file /usr/share/doc/rhel-system-roles/network/ directory
import libnmstate import libnmstate from libnmstate.schema import Interface net_state = libnmstate.show() for iface_state in net_state[Interface.KEY]: print(iface_state[Interface.NAME] + ": " + iface_state[Interface.STATE]) nmstatectl show enp1s0 > ~/network-config.yml nmstatectl apply ~/network-config.yml [service] keep_state_file_after_apply = false vars: network_state: interfaces: - name: enp7s0 type: ethernet state: up ipv4: enabled: true auto-dns: true auto-gateway: true auto-routes: true dhcp: true ipv6: enabled: true auto-dns: true auto-gateway: true auto-routes: true autoconf: true dhcp: true vars: network_connections: - name: enp7s0 interface_name: enp7s0 type: ethernet autoconnect: yes ip: dhcp4: yes auto6: yes state: up vars: network_state: interfaces: - name: enp7s0 type: ethernet state: down vars: network_connections: - name: enp7s0 interface_name: enp7s0 type: ethernet autoconnect: yes ip: dhcp4: yes auto6: yes state: down