Expand description
Declarative API for Host Network Management 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 provider supported to provide persistent network configuration after reboot. Kernel mode is also provided as tech-preview to apply network configurations without NetworkManager.
The NetworkState and its subordinates are all implemented the serde
Deserialize and Serialize, instead of building up NetworkState
manually, you may deserialize it from file(e.g. JSON, YAML and etc).
Features
The nmstate crate has these cargo features:
gen_conf– Generate offline network configures.query_apply– Query and apply network state.
By default, both features are enabled.
The gen_conf feature is only supported on Linux platform.
The query_apply feature is supported and tested on both Linux and MacOS.
Examples
To retrieve current network state:
use nmstate::NetworkState;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut net_state = NetworkState::new();
// Use kernel mode
net_state.set_kernel_only(true);
net_state.retrieve()?;
println!("{}", serde_yaml::to_string(&net_state)?);
Ok(())
}To apply network configuration(e.g. Assign static IP to eth1):
use nmstate::NetworkState;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut net_state: NetworkState = serde_yaml::from_str(
r#"---
interfaces:
- name: eth1
type: ethernet
state: up
mtu: 1500
ipv4:
address:
- ip: 192.0.2.252
prefix-length: 24
- ip: 192.0.2.251
prefix-length: 24
dhcp: false
enabled: true
ipv6:
address:
- ip: 2001:db8:2::1
prefix-length: 64
- ip: 2001:db8:1::1
prefix-length: 64
autoconf: false
dhcp: false
enabled: true
"#,
)?;
net_state.set_kernel_only(true);
net_state.apply()?;
Ok(())
}Structs
Information shared among all interface types
Bond interface. When serializing or deserializing, the BaseInterface will
be flatted and BondConfig stored as
link-aggregation section. The yaml
output crate::NetworkState containing an example bond interface:Bridge VLAN filtering configuration
DNS Client state
DNS resolver state. Example partial yaml output of [NetworkState] with
static DNS config:
Dummy interface. Only contain information of BaseInterface.
Example yaml outpuf of
[crate::NetworkState] with dummy interface:Ethernet(IEEE 802.3) interface.
Besides BaseInterface, optionally could hold EthernetConfig and/or
VethConfig.
The yaml output of crate::NetworkState containing ethernet interface would
be:
The ethtool configurations.
The yaml output of crate::NetworkState containing ethtool information of
an ethernet interface would be:
The IEEE 802.1X authentication configuration. The example yaml output of
crate::NetworkState with IEEE 802.1X authentication interface:
IP over InfiniBand interface. The example yaml output of a
crate::NetworkState with an infiniband interface would be:
IPv4 configuration of interface.
Example YAML output of interface holding static IPv4:
IPv6 configurations of interface.
Example output of interface holding automatic IPv6 settings:
Represent a list of Interface with special serde::Deserializer and
serde::Serializer.
When applying complex nested interface(e.g. bridge over bond over vlan of
eth1), the supported maximum nest level is 4 like previous example.
For 5+ nested level, you need to place controller interface before its
ports.
Linux bridge specific configuration.
Bridge interface provided by linux kernel.
When serializing or deserializing, the BaseInterface will
be flatted and LinuxBridgeConfig stored as
bridge section. The yaml
output crate::NetworkState containing an example linux bridge interface:Loopback interface. Only contain information of BaseInterface.
Limitations
Linux kernel MAC VLAN interface. The example yaml output of
crate::NetworkState with a mac vlan interface would be:
Linux kernel MAC VTAP interface. The example output of crate::NetworkState
with a mac vtap interface would be:
The NetworkState represents the whole network state including both
kernel status and configurations provides by backends(NetworkManager,
OpenvSwitch databas, and etc).
The example yaml output of OVS bond:
OpenvSwitch bridge interface. Example yaml output of crate::NetworkState
with an OVS bridge:
OpenvSwitch internal interface. Example yaml output of crate::NetworkState
with an DPDK enabled OVS interface:
Route entry
Routing rules
IP routing status
Single Root I/O Virtualization(SRIOV) configuration. The example yaml output
of crate::NetworkState with SR-IOV enabled ethernet interface would be:
Holder for interface with known interface type defined.
During apply action, nmstate can resolve unknown interface to first
found interface type.
Linux kernel VLAN interface. The example yaml output of
crate::NetworkState with a VLAN interface would be:
Linux kernel Virtual Routing and Forwarding(VRF) interface. The example
yaml output of a crate::NetworkState with a VRF interface would be:
Linux kernel VxLAN interface. The example yaml output of
crate::NetworkState with a VxLAN interface would be:
Enums
Specifies the 802.3ad aggregation selection logic to use.
Equal to kernel
all_slaves_active option.
Specifies that duplicate frames (received on inactive ports) should be
dropped (0) or delivered (1).The
arp_all_targets kernel bond option: Specifies the quantity of
arp_ip_targets that must be reachable in order for the ARP monitor to
consider a port as being up. This option affects only active-backup mode
for ports with arp_validation enabled.The
arp_validate kernel bond option: Specifies whether or not ARP probes
and replies should be validated in any mode that supports arp monitoring, or
whether non-ARP traffic should be filtered (disregarded) for link monitoring
purposes.The
fail_over_mac kernel bond option: Specifies whether active-backup mode
should set all ports to the same MAC address at port attachment (the
traditional behavior), or, when enabled, perform special handling of the
bond’s MAC address in accordance with the selected policy.Option specifying the rate in which we’ll ask our link partner to transmit
LACPDU packets in 802.3ad mode
Bond mode
The
primary_reselect kernel bond option: Specifies the reselection policy
for the primary port. This affects how the primary port is chosen to
become the active port when failure of the active port or recovery of the
primary port occurs. This option is designed to prevent flip-flopping
between the primary port and other ports.The
xmit_hash_policy kernel bond option: Selects the transmit hash policy
to use for port selection in balance-xor, 802.3ad, and tlb modes.DHCPv4 client ID
DHCPv6 Unique Identifier
Represent a kernel or user space network interface.
The state of interface
Interface type
IPv6 address generation mode
Which IP stack should network backend wait before considering the interface
activation finished.