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
link-aggregation
section. The yaml
output crate::NetworkState containing an example bond interface:[crate::NetworkState]
with dummy interface:bridge
section. The yaml
output crate::NetworkState containing an example linux bridge interface:Enums
all_slaves_active
option.
Specifies that duplicate frames (received on inactive ports) should be
dropped (0) or delivered (1).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.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.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.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.xmit_hash_policy
kernel bond option: Selects the transmit hash policy
to use for port selection in balance-xor, 802.3ad, and tlb modes.