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
125pub use crate::dispatch::DispatchConfig;
126pub(crate) use crate::dns::MergedDnsState;
127pub use crate::dns::{DnsClientState, DnsState};
128pub use crate::error::{ErrorKind, NmstateError};
129pub use crate::hostname::HostNameState;
130pub(crate) use crate::hostname::MergedHostNameState;
131pub use crate::ieee8021x::Ieee8021XConfig;
132pub(crate) use crate::iface::MergedInterface;
133pub use crate::iface::{
134    Interface, InterfaceIdentifier, InterfaceState, InterfaceType,
135    UnknownInterface,
136};
137pub(crate) use crate::ifaces::MergedInterfaces;
138pub use crate::ifaces::{
139    AltNameEntry, AltNameState, BaseInterface, BondAdSelect,
140    BondAllPortsActive, BondArpAllTargets, BondArpValidate, BondConfig,
141    BondFailOverMac, BondInterface, BondLacpRate, BondMode, BondOptions,
142    BondPortConfig, BondPrimaryReselect, BondXmitHashPolicy,
143    BridgePortTrunkTag, BridgePortVlanConfig, BridgePortVlanMode,
144    BridgePortVlanRange, DummyInterface, EthernetConfig, EthernetDuplex,
145    EthernetInterface, EthtoolCoalesceConfig, EthtoolConfig,
146    EthtoolFeatureConfig, EthtoolFecConfig, EthtoolFecMode, EthtoolPauseConfig,
147    EthtoolRingConfig, HsrConfig, HsrInterface, HsrProtocol, InfiniBandConfig,
148    InfiniBandInterface, InfiniBandMode, Interfaces, IpVlanConfig,
149    IpVlanInterface, IpVlanMode, IpsecInterface, LibreswanAddressFamily,
150    LibreswanConfig, LibreswanConnectionType, LinuxBridgeConfig,
151    LinuxBridgeInterface, LinuxBridgeMulticastRouterType, LinuxBridgeOptions,
152    LinuxBridgePortConfig, LinuxBridgeStpOptions, LoopbackInterface,
153    MacSecConfig, MacSecInterface, MacSecOffload, MacSecValidate,
154    MacVlanConfig, MacVlanInterface, MacVlanMode, MacVtapConfig,
155    MacVtapInterface, MacVtapMode, OvsBridgeBondConfig, OvsBridgeBondMode,
156    OvsBridgeBondPortConfig, OvsBridgeConfig, OvsBridgeInterface,
157    OvsBridgeOptions, OvsBridgePortConfig, OvsBridgeStpOptions, OvsDpdkConfig,
158    OvsInterface, OvsPatchConfig, SrIovConfig, SrIovVfConfig, VethConfig,
159    VlanConfig, VlanInterface, VlanProtocol, VlanQosMapping,
160    VlanRegistrationProtocol, VrfConfig, VrfInterface, VxlanConfig,
161    VxlanInterface, XfrmInterface,
162};
163pub use crate::ip::{
164    AddressFamily, Dhcpv4ClientId, Dhcpv6Duid, InterfaceIpAddr, InterfaceIpv4,
165    InterfaceIpv6, Ipv6AddrGenMode, WaitIp,
166};
167pub use crate::lldp::{
168    LldpAddressFamily, LldpChassisId, LldpChassisIdType, LldpConfig,
169    LldpMacPhy, LldpMaxFrameSize, LldpMgmtAddr, LldpMgmtAddrs, LldpNeighborTlv,
170    LldpPortId, LldpPortIdType, LldpPpvids, LldpSystemCapabilities,
171    LldpSystemCapability, LldpSystemDescription, LldpSystemName, LldpVlan,
172    LldpVlans,
173};
174pub use crate::mptcp::{MptcpAddressFlag, MptcpConfig};
175pub use crate::net_state::NetworkState;
176pub(crate) use crate::net_state::{MergedNetworkState, NetworkStateMode};
177pub(crate) use crate::ovn::MergedOvnConfiguration;
178pub use crate::ovn::{
179    OvnBridgeMapping, OvnBridgeMappingState, OvnConfiguration,
180};
181pub(crate) use crate::ovs::MergedOvsDbGlobalConfig;
182pub use crate::ovs::{OvsDbGlobalConfig, OvsDbIfaceConfig};
183pub use crate::pci_address::PciAddress;
184#[cfg(feature = "query_apply")]
185pub use crate::policy::{
186    NetworkCaptureRules, NetworkPolicy, NetworkStateTemplate,
187};
188pub(crate) use crate::route::MergedRoutes;
189pub use crate::route::{RouteEntry, RouteState, RouteType, Routes};
190pub(crate) use crate::route_rule::MergedRouteRules;
191pub use crate::route_rule::{
192    RouteRuleAction, RouteRuleEntry, RouteRuleState, RouteRules,
193};
194#[cfg(feature = "query_apply")]
195pub use crate::statistic::{NmstateFeature, NmstateStatistic};
nmstate/lib.rs

nmstate/
lib.rs
