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, Ip6TunnelFlag, IpTunnelConfig, IpTunnelInterface,
153        IpTunnelMode, IpVlanConfig, IpVlanInterface, IpVlanMode,
154        IpsecInterface, LibreswanAddressFamily, LibreswanConfig,
155        LibreswanConnectionType, LinuxBridgeConfig, LinuxBridgeInterface,
156        LinuxBridgeMulticastRouterType, LinuxBridgeOptions,
157        LinuxBridgePortConfig, LinuxBridgeStpOptions, LoopbackInterface,
158        MacSecConfig, MacSecInterface, MacSecOffload, MacSecValidate,
159        MacVlanConfig, MacVlanInterface, MacVlanMode, MacVtapConfig,
160        MacVtapInterface, MacVtapMode, OvsBridgeBondConfig, OvsBridgeBondMode,
161        OvsBridgeBondPortConfig, OvsBridgeConfig, OvsBridgeInterface,
162        OvsBridgeOptions, OvsBridgePortConfig, OvsBridgeStpOptions,
163        OvsDpdkConfig, OvsInterface, OvsPatchConfig, SrIovConfig,
164        SrIovVfConfig, VethConfig, VlanConfig, VlanInterface, VlanProtocol,
165        VlanQosMapping, VlanRegistrationProtocol, VrfConfig, VrfInterface,
166        VxlanConfig, VxlanInterface, XfrmInterface,
167    },
168    ip::{
169        AddressFamily, Dhcpv4ClientId, Dhcpv6Duid, InterfaceIpAddr,
170        InterfaceIpv4, InterfaceIpv6, Ipv6AddrGenMode, WaitIp,
171    },
172    lldp::{
173        LldpAddressFamily, LldpChassisId, LldpChassisIdType, LldpConfig,
174        LldpMacPhy, LldpMaxFrameSize, LldpMgmtAddr, LldpMgmtAddrs,
175        LldpNeighborTlv, LldpPortId, LldpPortIdType, LldpPpvids,
176        LldpSystemCapabilities, LldpSystemCapability, LldpSystemDescription,
177        LldpSystemName, LldpVlan, LldpVlans,
178    },
179    mptcp::{MptcpAddressFlag, MptcpConfig},
180    net_state::NetworkState,
181    ovn::{OvnBridgeMapping, OvnBridgeMappingState, OvnConfiguration},
182    ovs::{OvsDbGlobalConfig, OvsDbIfaceConfig},
183    pci_address::PciAddress,
184    route::{RouteEntry, RouteState, RouteType, Routes},
185    route_rule::{RouteRuleAction, RouteRuleEntry, RouteRuleState, RouteRules},
186};
187pub(crate) use crate::{
188    dns::MergedDnsState,
189    hostname::MergedHostNameState,
190    iface::MergedInterface,
191    ifaces::MergedInterfaces,
192    net_state::{MergedNetworkState, NetworkStateMode},
193    ovn::MergedOvnConfiguration,
194    ovs::MergedOvsDbGlobalConfig,
195    route::MergedRoutes,
196    route_rule::MergedRouteRules,
197};
nmstate/lib.rs

nmstate/
lib.rs
