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

nmstate/
lib.rs
