nmstate/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2
3#![doc(html_favicon_url = "https://nmstate.io/favicon.png")]
4#![doc(html_logo_url = "https://nmstate.io/favicon.png")]
5
6//! Declarative API for Host Network Management
7//! Nmstate is a library with an accompanying command line tool that manages
8//! host networking settings in a declarative manner. The networking state is
9//! described by a pre-defined schema. Reporting of current state and changes to
10//! it (desired state) both conform to the schema.
11//!
12//! Nmstate is aimed to satisfy enterprise needs to manage host networking
13//! through a northbound declarative API and multi provider support on the
14//! southbound. NetworkManager acts as the main provider supported to provide
15//! persistent network configuration after reboot. Kernel mode is also provided
16//! as tech-preview to apply network configurations without NetworkManager.
17//!
18//! The [NetworkState] and its subordinates are all implemented the serde
19//! `Deserialize` and  `Serialize`, instead of building up [NetworkState]
20//! manually, you may deserialize it from file(e.g. JSON, YAML and etc).
21//!
22//! ## Features
23//! The `nmstate` crate has these cargo features:
24//!  * `gen_conf` -- Generate offline network configures.
25//!  * `query_apply` -- Query and apply network state.
26//!
27//! By default, both features are enabled.
28//! The `gen_conf` feature is only supported on Linux platform.
29//! The `query_apply` feature is supported and tested on both Linux and MacOS.
30//!
31//! ## Examples
32//!
33//! To retrieve current network state:
34//!
35//! ```no_run
36//! use nmstate::NetworkState;
37//!
38//! fn main() -> Result<(), Box<dyn std::error::Error>> {
39//!     let mut net_state = NetworkState::new();
40//!     // Use kernel mode
41//!     net_state.set_kernel_only(true);
42//!     net_state.retrieve()?;
43//!     println!("{}", serde_yaml::to_string(&net_state)?);
44//!     Ok(())
45//! }
46//! ```
47//!
48//! To apply network configuration(e.g. Assign static IP to eth1):
49//!
50//! ```no_run
51//! use nmstate::NetworkState;
52//!
53//! fn main() -> Result<(), Box<dyn std::error::Error>> {
54//!     let mut net_state: NetworkState = serde_yaml::from_str(
55//!         r#"---
56//!         interfaces:
57//!           - name: eth1
58//!             type: ethernet
59//!             state: up
60//!             mtu: 1500
61//!             ipv4:
62//!               address:
63//!               - ip: 192.0.2.252
64//!                 prefix-length: 24
65//!               - ip: 192.0.2.251
66//!                 prefix-length: 24
67//!               dhcp: false
68//!               enabled: true
69//!             ipv6:
70//!               address:
71//!                 - ip: 2001:db8:2::1
72//!                   prefix-length: 64
73//!                 - ip: 2001:db8:1::1
74//!                   prefix-length: 64
75//!               autoconf: false
76//!               dhcp: false
77//!               enabled: true
78//!         "#,
79//!     )?;
80//!     net_state.set_kernel_only(true);
81//!     net_state.apply()?;
82//!     Ok(())
83//! }
84//! ```
85
86mod deserializer;
87mod dispatch;
88mod dns;
89mod error;
90#[cfg(feature = "gen_conf")]
91mod gen_conf;
92mod hostname;
93mod ieee8021x;
94mod iface;
95mod ifaces;
96mod ip;
97mod lldp;
98mod mptcp;
99mod net_state;
100#[cfg(feature = "query_apply")]
101mod nispor;
102mod nm;
103#[allow(deprecated)]
104mod ovn;
105mod ovs;
106#[cfg(feature = "query_apply")]
107mod ovsdb;
108mod pci_address;
109#[cfg(feature = "query_apply")]
110mod policy;
111#[cfg(feature = "query_apply")]
112mod query_apply;
113#[cfg(feature = "gen_revert")]
114mod revert;
115mod route;
116mod route_rule;
117mod serializer;
118mod state;
119#[cfg(feature = "query_apply")]
120mod statistic;
121mod unit_tests;
122#[cfg(feature = "query_apply")]
123mod validate;
124
125#[cfg(feature = "query_apply")]
126pub use crate::policy::{
127    NetworkCaptureRules, NetworkPolicy, NetworkStateTemplate,
128};
129#[cfg(feature = "query_apply")]
130pub use crate::statistic::{NmstateFeature, NmstateStatistic};
131pub use crate::{
132    dispatch::DispatchConfig,
133    dns::{DnsClientState, DnsState},
134    error::{ErrorKind, NmstateError},
135    hostname::HostNameState,
136    ieee8021x::Ieee8021XConfig,
137    iface::{
138        Interface, InterfaceIdentifier, InterfaceState, InterfaceType,
139        UnknownInterface,
140    },
141    ifaces::{
142        AltNameEntry, AltNameState, BaseInterface, BondAdSelect,
143        BondAllPortsActive, BondArpAllTargets, BondArpValidate, BondConfig,
144        BondFailOverMac, BondInterface, BondLacpRate, BondMode, BondOptions,
145        BondPortConfig, BondPrimaryReselect, BondXmitHashPolicy,
146        BridgePortTrunkTag, BridgePortVlanConfig, BridgePortVlanMode,
147        BridgePortVlanRange, DummyInterface, EthernetConfig, EthernetDuplex,
148        EthernetInterface, EthtoolCoalesceConfig, EthtoolConfig,
149        EthtoolFeatureConfig, EthtoolFecConfig, EthtoolFecMode,
150        EthtoolPauseConfig, EthtoolRingConfig, HsrConfig, HsrInterface,
151        HsrProtocol, InfiniBandConfig, InfiniBandInterface, InfiniBandMode,
152        Interfaces, IpVlanConfig, IpVlanInterface, IpVlanMode, IpsecInterface,
153        LibreswanAddressFamily, LibreswanConfig, LibreswanConnectionType,
154        LinuxBridgeConfig, LinuxBridgeInterface,
155        LinuxBridgeMulticastRouterType, LinuxBridgeOptions,
156        LinuxBridgePortConfig, LinuxBridgeStpOptions, LoopbackInterface,
157        MacSecConfig, MacSecInterface, MacSecOffload, MacSecValidate,
158        MacVlanConfig, MacVlanInterface, MacVlanMode, MacVtapConfig,
159        MacVtapInterface, MacVtapMode, OvsBridgeBondConfig, OvsBridgeBondMode,
160        OvsBridgeBondPortConfig, OvsBridgeConfig, OvsBridgeInterface,
161        OvsBridgeOptions, OvsBridgePortConfig, OvsBridgeStpOptions,
162        OvsDpdkConfig, OvsInterface, OvsPatchConfig, SrIovConfig,
163        SrIovVfConfig, VethConfig, VlanConfig, VlanInterface, VlanProtocol,
164        VlanQosMapping, VlanRegistrationProtocol, VrfConfig, VrfInterface,
165        VxlanConfig, VxlanInterface, XfrmInterface,
166    },
167    ip::{
168        AddressFamily, Dhcpv4ClientId, Dhcpv6Duid, InterfaceIpAddr,
169        InterfaceIpv4, InterfaceIpv6, Ipv6AddrGenMode, WaitIp,
170    },
171    lldp::{
172        LldpAddressFamily, LldpChassisId, LldpChassisIdType, LldpConfig,
173        LldpMacPhy, LldpMaxFrameSize, LldpMgmtAddr, LldpMgmtAddrs,
174        LldpNeighborTlv, LldpPortId, LldpPortIdType, LldpPpvids,
175        LldpSystemCapabilities, LldpSystemCapability, LldpSystemDescription,
176        LldpSystemName, LldpVlan, LldpVlans,
177    },
178    mptcp::{MptcpAddressFlag, MptcpConfig},
179    net_state::NetworkState,
180    ovn::{OvnBridgeMapping, OvnBridgeMappingState, OvnConfiguration},
181    ovs::{OvsDbGlobalConfig, OvsDbIfaceConfig},
182    pci_address::PciAddress,
183    route::{RouteEntry, RouteState, RouteType, Routes},
184    route_rule::{RouteRuleAction, RouteRuleEntry, RouteRuleState, RouteRules},
185};
186pub(crate) use crate::{
187    dns::MergedDnsState,
188    hostname::MergedHostNameState,
189    iface::MergedInterface,
190    ifaces::MergedInterfaces,
191    net_state::{MergedNetworkState, NetworkStateMode},
192    ovn::MergedOvnConfiguration,
193    ovs::MergedOvsDbGlobalConfig,
194    route::MergedRoutes,
195    route_rule::MergedRouteRules,
196};
nmstate/lib.rs

nmstate/
lib.rs
