Crate nmrs

Expand description

A Rust library for managing network connections via NetworkManager.

This crate provides a high-level async API for NetworkManager over D-Bus, enabling easy management of WiFi, Ethernet, and VPN connections on Linux.

§Quick Start

§WiFi Connection

use nmrs::{NetworkManager, WifiSecurity};

let nm = NetworkManager::new().await?;

// List visible networks (None = all Wi-Fi devices)
let networks = nm.list_networks(None).await?;
for net in &networks {
    println!("{} - Signal: {}%", net.ssid, net.strength.unwrap_or(0));
}

// Connect to a network on the first Wi-Fi device
nm.connect("MyNetwork", None, WifiSecurity::WpaPsk {
    psk: "password123".into()
}).await?;

// Check current connection
if let Some(ssid) = nm.current_ssid().await {
    println!("Connected to: {}", ssid);
}

§VPN Connection (WireGuard)

use nmrs::{NetworkManager, WireGuardConfig, WireGuardPeer};

let nm = NetworkManager::new().await?;

let peer = WireGuardPeer::new(
    "peer_public_key",
    "vpn.example.com:51820",
    vec!["0.0.0.0/0".into()],
).with_persistent_keepalive(25);

let config = WireGuardConfig::new(
    "MyVPN",
    "vpn.example.com:51820",
    "your_private_key",
    "10.0.0.2/24",
    vec![peer],
).with_dns(vec!["1.1.1.1".into(), "8.8.8.8".into()]);

nm.connect_vpn(config).await?;

§VPN Connection (OpenVPN)

use nmrs::{NetworkManager, OpenVpnConfig, OpenVpnAuthType};

let nm = NetworkManager::new().await?;

let config = OpenVpnConfig::new("CorpVPN", "vpn.example.com", 1194, false)
    .with_auth_type(OpenVpnAuthType::PasswordTls)
    .with_username("user")
    .with_password("secret")
    .with_ca_cert("/etc/openvpn/ca.crt")
    .with_client_cert("/etc/openvpn/client.crt")
    .with_client_key("/etc/openvpn/client.key");

nm.connect_vpn(config).await?;

// Or import an .ovpn file directly:
nm.import_ovpn("corp.ovpn", Some("user"), Some("secret")).await?;

// List VPN connections
let vpns = nm.list_vpn_connections().await?;
for vpn in vpns {
    println!("{}: {:?} - {:?}", vpn.name, vpn.vpn_type, vpn.state);
}

nm.disconnect_vpn("CorpVPN").await?;

§Core Concepts

§NetworkManager

The main entry point is NetworkManager, which provides methods for:

Listing and managing network devices
Scanning for available WiFi networks
Connecting to networks (WiFi, Ethernet, VPN)
Managing saved connection profiles
Real-time monitoring of network changes

§Models

The models module contains all types, enums, and errors:

Device - Represents a network device (WiFi, Ethernet, etc.)
Network - Represents a discovered WiFi network
WifiSecurity - Security types (Open, WPA-PSK, WPA-EAP)
VpnCredentials - Legacy VPN connection credentials
VpnType - Protocol-specific VPN metadata (WireGuard, OpenVPN, strongSwan, etc.)
VpnKind - Plugin-based vs kernel WireGuard distinction
VpnConnection - VPN connection information
VpnDetails - Protocol-specific VPN details (WireGuard / OpenVPN)
WireGuardConfig - WireGuard connection configuration
WireGuardPeer - WireGuard peer configuration
OpenVpnConfig - OpenVPN connection configuration
OpenVpnAuthType - OpenVPN authentication types
ConnectionError - Comprehensive error types

§Connection Builders

The builders module provides functions to construct connection settings for different network types. These are typically used internally but exposed for advanced use cases.

§Examples

§Connecting to Different Network Types

use nmrs::{NetworkManager, WifiSecurity, EapOptions, EapMethod, Phase2};

let nm = NetworkManager::new().await?;

// Open network
nm.connect("OpenWiFi", None, WifiSecurity::Open).await?;

// WPA-PSK (password-protected)
nm.connect("HomeWiFi", None, WifiSecurity::WpaPsk {
    psk: "my_password".into()
}).await?;

// WPA-EAP (Enterprise)
let eap_opts = EapOptions::new("user@company.com", "password")
    .with_domain_suffix_match("company.com")
    .with_system_ca_certs(true)
    .with_method(EapMethod::Peap)
    .with_phase2(Phase2::Mschapv2);

nm.connect("CorpWiFi", None, WifiSecurity::WpaEap {
    opts: eap_opts
}).await?;

// Ethernet (auto-connects when cable is plugged in)
nm.connect_wired().await?;

§Error Handling

All operations return Result<T>, which is an alias for Result<T, ConnectionError>. The ConnectionError type provides specific variants for different failure modes:

use nmrs::{NetworkManager, WifiSecurity, ConnectionError};

let nm = NetworkManager::new().await?;

match nm.connect("MyNetwork", None, WifiSecurity::WpaPsk {
    psk: "wrong_password".into()
}).await {
    Ok(_) => println!("Connected successfully"),
    Err(ConnectionError::AuthFailed) => {
        eprintln!("Wrong password!");
    }
    Err(ConnectionError::NotFound) => {
        eprintln!("Network not found or out of range");
    }
    Err(ConnectionError::Timeout) => {
        eprintln!("Connection timed out");
    }
    Err(ConnectionError::DhcpFailed) => {
        eprintln!("Failed to obtain IP address");
    }
    Err(e) => eprintln!("Error: {}", e),
}

§Device Management

use nmrs::NetworkManager;

let nm = NetworkManager::new().await?;

// List all devices
let devices = nm.list_devices().await?;
for device in devices {
    println!("{}: {} ({})",
        device.interface,
        device.device_type,
        device.state
    );
}

// Enable/disable WiFi
nm.set_wireless_enabled(false).await?;
nm.set_wireless_enabled(true).await?;

§Real-Time Monitoring

Monitor network and device changes in real-time using D-Bus signals:

use nmrs::NetworkManager;

let nm = NetworkManager::new().await?;

// Monitor network changes (new networks, signal changes, etc.)
nm.monitor_network_changes(|| {
    println!("Networks changed! Refresh your UI.");
}).await?;

// Monitor device state changes (cable plugged in, device activated, etc.)
nm.monitor_device_changes(|| {
    println!("Device state changed!");
}).await?;

§Architecture

This crate uses D-Bus signals for efficient state monitoring instead of polling. When connecting to a network, it subscribes to NetworkManager’s StateChanged signals to detect connection success or failure immediately. This provides:

Faster response times - Immediate notification vs polling delay
Lower CPU usage - No spinning loops
Better error messages - Specific failure reasons from NetworkManager

§Logging

This crate uses the log facade. To see log output, add a logging implementation like env_logger:

env_logger::init();

§Feature Flags

This crate currently has no optional features. All functionality is enabled by default.

§Platform Support

This crate is Linux-only and requires:

NetworkManager running and accessible via D-Bus
Appropriate permissions to manage network connections

Modules§

agent: NetworkManager secret agent for credential prompting over D-Bus.
builders: Connection builders for WiFi, Ethernet, and VPN connections.
models: Types, enums, and errors for NetworkManager operations.

Macros§

try_log: Macro to convert Result to Option with error logging. Usage: try_log!(result, "context message")?

Structs§

AccessPoint: A single Wi-Fi access point reported by NetworkManager.
AirplaneModeState: Aggregated radio state for all radios that nmrs can control.
BluetoothDevice: Bluetooth device with friendly name from BlueZ.
BluetoothIdentity: Bluetooth device identity information.
ConnectionOptions: Connection options for saved NetworkManager connections.
ConnectivityReport: Snapshot of NM’s connectivity subsystem.
Device: Represents a network device managed by NetworkManager.
EapOptions: EAP options for WPA-EAP (Enterprise) Wi-Fi connections.
Network: Represents a Wi-Fi network discovered during a scan.
NetworkInfo: Detailed information about a Wi-Fi network.
NetworkManager: High-level interface to NetworkManager over D-Bus.
OpenVpnConfig: OpenVPN connection configuration.
RadioState: Software and hardware enabled state for a single radio.
SavedConnection: Full saved profile with a structured SettingsSummary.
SavedConnectionBrief: Cheap listing: path plus connection identity fields only (still one GetSettings per profile).
SecurityFeatures: Decoded security capabilities of an access point.
SettingsPatch: Partial update merged via crate::NetworkManager::update_saved_connection.
TimeoutConfig: Timeout configuration for NetworkManager operations.
VlanConfig: VLAN connection configuration.
VpnConnection: A saved or active VPN connection with rich metadata.
VpnConnectionInfo: Detailed VPN connection information and statistics.
VpnCredentialsDeprecated: Legacy VPN credentials for establishing a VPN connection.
VpnRoute: A static IPv4 route for OpenVPN split tunneling.
VpnSecretFlags: NM password-flags / psk-flags style bitmask (subset used for summaries).
WifiDevice: A Wi-Fi device summary returned by list_wifi_devices.
WifiScope: Operations scoped to a single Wi-Fi interface.
WifiSecuritySummary: Non-secret Wi-Fi security hints for UI / filtering.
WireGuardConfig: WireGuard configuration for establishing a VPN connection.
WireGuardPeer: WireGuard peer configuration.

Enums§

ActiveConnectionState: NetworkManager active connection state.
ApMode: Wi-Fi access point operating mode.
BluetoothNetworkRole: Bluetooth network role.
ConnectType: Preferred connection type derived from SecurityFeatures.
ConnectionError: Errors that can occur during network operations.
ConnectionStateReason: NetworkManager active connection state reason codes.
ConnectivityState: NM’s NMConnectivityState enum.
DeviceState: NetworkManager device states.
DeviceType: NetworkManager device types.
EapMethod: EAP (Extensible Authentication Protocol) method for WPA-Enterprise Wi-Fi.
OpenVpnAuthType: OpenVPN authentication type.
OpenVpnCompression: Compression algorithm for OpenVPN connections.
OpenVpnConnectionType: OpenVPN authentication/connection type.
OpenVpnProxy: Proxy configuration for OpenVPN connections.
Phase2: Phase 2 (inner) authentication methods for EAP connections.
SettingsSummary: Decoded summary for the connection type (and related sections).
StateReason: NetworkManager device state reason codes.
VpnConfiguration: VPN connection configuration
VpnDetails: Protocol-specific details for an active VPN connection.
VpnKind: Whether a VPN connection is a NM-plugin VPN or kernel WireGuard.
VpnType: Protocol-specific VPN metadata decoded from NM saved settings.
WifiKeyMgmt: Wi-Fi key management style from 802-11-wireless-security.key-mgmt.
WifiSecurity: Wi-Fi connection security types.

Traits§

VpnConfig: Common metadata shared by VPN connection configurations.

Functions§

connection_state_reason_to_error: Converts a connection state reason code to a specific ConnectionError.
reason_to_error: Converts a NetworkManager state reason code to a specific ConnectionError.

Type Aliases§

Result: A specialized Result type for network operations.

Crate nmrs

Crate nmrs Copy item path

§Quick Start

§WiFi Connection

§VPN Connection (WireGuard)

§VPN Connection (OpenVPN)

§Core Concepts

§NetworkManager

§Models

§Connection Builders

§Examples

§Connecting to Different Network Types

§Error Handling

§Device Management

§Real-Time Monitoring

§Architecture

§Logging

§Feature Flags

§Platform Support

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate nmrs