Crate nmstate

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§

BaseInterface: Information shared among all interface types
BondConfig
BondInterface: Bond interface.
BondOptions
BondPortConfig
BridgePortVlanConfig: Bridge VLAN filtering configuration
BridgePortVlanRange
DispatchConfig
DnsClientState: DNS Client state
DnsState: DNS resolver state. Example partial yaml output of [NetworkState] with static DNS config:
DummyInterface: Dummy interface. Only contain information of BaseInterface. Example yaml outpuf of [crate::NetworkState] with dummy interface:
EthernetConfig
EthernetInterface: 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:
EthtoolCoalesceConfig
EthtoolConfig: The ethtool configurations. The yaml output of crate::NetworkState containing ethtool information of an ethernet interface would be:
EthtoolFeatureConfig
EthtoolFecConfig
EthtoolPauseConfig
EthtoolRingConfig
HostNameState
HsrConfig
HsrInterface: HSR interface. The example YAML output of a crate::NetworkState with an HSR interface would be:
Ieee8021XConfig: The IEEE 802.1X authentication configuration. The example yaml output of crate::NetworkState with IEEE 802.1X authentication interface:
InfiniBandConfig
InfiniBandInterface: IP over InfiniBand interface. The example yaml output of a crate::NetworkState with an infiniband interface would be:
InterfaceIpAddr
InterfaceIpv4: IPv4 configuration of interface. Example YAML output of interface holding static IPv4:
InterfaceIpv6: IPv6 configurations of interface. Example output of interface holding automatic IPv6 settings:
Interfaces: Represent a list of Interface.
IpVlanConfig
IpVlanInterface: Linux kernel IPVLAN interface. The example YAML output of crate::NetworkState with an IPVLAN interface would be:
IpsecInterface: The libreswan Ipsec interface.
LibreswanConfig
LinuxBridgeConfig: Linux bridge specific configuration.
LinuxBridgeInterface: Bridge interface provided by linux kernel.
LinuxBridgeOptions
LinuxBridgePortConfig
LinuxBridgeStpOptions
LldpChassisId
LldpConfig
LldpMacPhy
LldpMaxFrameSize
LldpMgmtAddr
LldpMgmtAddrs
LldpPortId
LldpPpvids
LldpSystemCapabilities
LldpSystemDescription
LldpSystemName
LldpVlan
LldpVlans
LoopbackInterface: Loopback interface. Only contain information of BaseInterface. Limitations
MacSecConfig
MacSecInterface: MACsec interface. The example YAML output of a crate::NetworkState with an MACsec interface would be:
MacVlanConfig
MacVlanInterface: Linux kernel MAC VLAN interface. The example yaml output of crate::NetworkState with a mac vlan interface would be:
MacVtapConfig
MacVtapInterface: Linux kernel MAC VTAP interface. The example output of crate::NetworkState with a mac vtap interface would be:
MptcpConfig
NetworkCaptureRules
NetworkPolicy
NetworkState: The NetworkState represents the whole network state including both kernel status and configurations provides by backends(NetworkManager, OpenvSwitch databas, and etc).
NetworkStateTemplate
NmstateError
NmstateStatistic
OvnBridgeMapping
OvnConfiguration: Global OVN bridge mapping configuration. Example yaml output of crate::NetworkState:
OvsBridgeBondConfig: The example yaml output of OVS bond:
OvsBridgeBondPortConfig
OvsBridgeConfig
OvsBridgeInterface: OpenvSwitch bridge interface. Example yaml output of crate::NetworkState with an OVS bridge:
OvsBridgeOptions
OvsBridgePortConfig
OvsDbGlobalConfig
OvsDbIfaceConfig
OvsDpdkConfig
OvsInterface: OpenvSwitch internal interface. Example yaml output of crate::NetworkState with an DPDK enabled OVS interface:
OvsPatchConfig
PciAddress
RouteEntry: Route entry
RouteRuleEntry
RouteRules: Routing rules
Routes: IP routing status
SrIovConfig: Single Root I/O Virtualization(SRIOV) configuration. The example yaml output of crate::NetworkState with SR-IOV enabled ethernet interface would be:
SrIovVfConfig
UnknownInterface: Holder for interface with known interface type defined. During apply action, nmstate can resolve unknown interface to first found interface type.
VethConfig
VlanConfig
VlanInterface: Linux kernel VLAN interface. The example yaml output of crate::NetworkState with a VLAN interface would be:
VlanQosMapping: VLAN QoS Mapping Mapping between linux internal packet priority and VLAN header priority for incoming or outgoing packet.
VrfConfig
VrfInterface: Linux kernel Virtual Routing and Forwarding(VRF) interface. The example yaml output of a crate::NetworkState with a VRF interface would be:
VxlanConfig
VxlanInterface: Linux kernel VxLAN interface. The example yaml output of crate::NetworkState with a VxLAN interface would be:
XfrmInterface

Enums§

AddressFamily
BondAdSelect: Specifies the 802.3ad aggregation selection logic to use.
BondAllPortsActive: Equal to kernel all_slaves_active option. Specifies that duplicate frames (received on inactive ports) should be dropped (0) or delivered (1).
BondArpAllTargets: The arp_all_targets kernel bond option.
BondArpValidate: The arp_validate kernel bond option.
BondFailOverMac: The fail_over_mac kernel bond option.
BondLacpRate: Option specifying the rate in which we’ll ask our link partner to transmit LACPDU packets in 802.3ad mode
BondMode: Bond mode
BondPrimaryReselect: The primary_reselect kernel bond option.
BondXmitHashPolicy: The xmit_hash_policy kernel bond option.
BridgePortTrunkTag
BridgePortVlanMode
Dhcpv4ClientId: DHCPv4 client ID
Dhcpv6Duid: DHCPv6 Unique Identifier
ErrorKind
EthernetDuplex
EthtoolFecMode
HsrProtocol
InfiniBandMode
Interface: Represent a kernel or user space network interface.
InterfaceIdentifier: Interface Identifier defines the method for network backend on matching network interface
InterfaceState: The state of interface
InterfaceType: Interface type
IpVlanMode
Ipv6AddrGenMode: IPv6 address generation mode
LibreswanAddressFamily
LibreswanConnectionType
LinuxBridgeMulticastRouterType
LldpAddressFamily
LldpChassisIdType
LldpNeighborTlv
LldpPortIdType
LldpSystemCapability
MacSecOffload
MacSecValidate
MacVlanMode
MacVtapMode
MptcpAddressFlag
NmstateFeature
OvnBridgeMappingState
OvsBridgeBondMode
RouteRuleAction
RouteRuleState
RouteState
RouteType
VlanProtocol
VlanRegistrationProtocol
WaitIp: Which IP stack should network backend wait before considering the interface activation finished.

Type Aliases§

OvsBridgeStpOptions