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, EthtoolPauseConfig, EthtoolRingConfig, HsrConfig,
143    HsrInterface, HsrProtocol, InfiniBandConfig, InfiniBandInterface,
144    InfiniBandMode, Interfaces, IpVlanConfig, IpVlanInterface, IpVlanMode,
145    IpsecInterface, LibreswanAddressFamily, LibreswanConfig,
146    LibreswanConnectionType, LinuxBridgeConfig, LinuxBridgeInterface,
147    LinuxBridgeMulticastRouterType, LinuxBridgeOptions, LinuxBridgePortConfig,
148    LinuxBridgeStpOptions, LoopbackInterface, MacSecConfig, MacSecInterface,
149    MacSecOffload, MacSecValidate, MacVlanConfig, MacVlanInterface,
150    MacVlanMode, MacVtapConfig, MacVtapInterface, MacVtapMode,
151    OvsBridgeBondConfig, OvsBridgeBondMode, OvsBridgeBondPortConfig,
152    OvsBridgeConfig, OvsBridgeInterface, OvsBridgeOptions, OvsBridgePortConfig,
153    OvsBridgeStpOptions, OvsDpdkConfig, OvsInterface, OvsPatchConfig,
154    SrIovConfig, SrIovVfConfig, VethConfig, VlanConfig, VlanInterface,
155    VlanProtocol, VlanRegistrationProtocol, VrfConfig, VrfInterface,
156    VxlanConfig, VxlanInterface, XfrmInterface,
157};
158pub use crate::ip::{
159    AddressFamily, Dhcpv4ClientId, Dhcpv6Duid, InterfaceIpAddr, InterfaceIpv4,
160    InterfaceIpv6, Ipv6AddrGenMode, WaitIp,
161};
162pub use crate::lldp::{
163    LldpAddressFamily, LldpChassisId, LldpChassisIdType, LldpConfig,
164    LldpMacPhy, LldpMaxFrameSize, LldpMgmtAddr, LldpMgmtAddrs, LldpNeighborTlv,
165    LldpPortId, LldpPortIdType, LldpPpvids, LldpSystemCapabilities,
166    LldpSystemCapability, LldpSystemDescription, LldpSystemName, LldpVlan,
167    LldpVlans,
168};
169pub use crate::mptcp::{MptcpAddressFlag, MptcpConfig};
170pub(crate) use crate::net_state::MergedNetworkState;
171pub use crate::net_state::NetworkState;
172pub(crate) use crate::ovn::MergedOvnConfiguration;
173pub use crate::ovn::{
174    OvnBridgeMapping, OvnBridgeMappingState, OvnConfiguration,
175};
176pub(crate) use crate::ovs::MergedOvsDbGlobalConfig;
177pub use crate::ovs::{OvsDbGlobalConfig, OvsDbIfaceConfig};
178#[cfg(feature = "query_apply")]
179pub use crate::policy::{
180    NetworkCaptureRules, NetworkPolicy, NetworkStateTemplate,
181};
182pub(crate) use crate::route::MergedRoutes;
183pub use crate::route::{RouteEntry, RouteState, RouteType, Routes};
184pub(crate) use crate::route_rule::MergedRouteRules;
185pub use crate::route_rule::{
186    RouteRuleAction, RouteRuleEntry, RouteRuleState, RouteRules,
187};
188#[cfg(feature = "query_apply")]
189pub use crate::statistic::{NmstateFeature, NmstateStatistic};
nmstate/lib.rs

nmstate/
lib.rs
