GitHub - networkmanager-rs/nmrs: Rust bindings for Networ...

An async-first Rust API for NetworkManager over D-Bus. The goal is to provide a safe and simple high-level API for managing Wi-Fi connections on Linux systems, built on zbus for reliable D-Bus communication.

Documentation

User Guide - Comprehensive guide with tutorials and examples
API Documentation - Complete API reference on docs.rs
Discord - Join our community for help and discussion

Getting Started

Please consider joining the Discord. It's a welcoming community to both developers who want to contribute and/or learn about and discuss nmrs as well as users that would like to be engaged with the development process.

The best way to get started with nmrs is the User Guide, which includes comprehensive tutorials and examples. For detailed API information, see the API documentation.

Sample usage

We'll create a simple example that scans for available networks and connects to one. Note that these examples require NetworkManager to be running on your Linux system with D-Bus access, obviously.

Listing Networks

Scan for and display available Wi-Fi networks:

use nmrs::NetworkManager;

#[tokio::main]
async fn main() -> nmrs::Result<()> {
    let nm = NetworkManager::new().await?;
    
    // Scan for networks
    let networks = nm.list_networks(None).await?;
    
    for net in networks {
        println!(
            "{} - Signal: {}%, Security: {:?}",
            net.ssid,
            net.strength.unwrap_or(0),
            net.security
        );
    }
    
    Ok(())
}

Now let's connect to a network...

Connect to a WPA-PSK protected network:

use nmrs::{NetworkManager, WifiSecurity};

#[tokio::main]
async fn main() -> nmrs::Result<()> {
    let nm = NetworkManager::new().await?;
    
    // Connect to a network
    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);
    }
    
    Ok(())
}

Error Handling

All operations return Result<T, ConnectionError> with specific error variants:

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

#[tokio::main]
async fn main() -> nmrs::Result<()> {
    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!("Authentication failed - wrong password"),
        Err(ConnectionError::NotFound) => eprintln!("Network not found or out of range"),
        Err(ConnectionError::Timeout) => eprintln!("Connection timed out"),
        Err(e) => eprintln!("Error: {}", e),
    }
    
    Ok(())
}

To follow and/or discuss the development of nmrs, you can join the public Discord channel.

Roadmap / Implementation Status

If something is missing that you'd like to see, please file a PR or issue, adding it to this roadmap.

Wi-Fi

Scan and list Wi-Fi networks
List individual access points with BSSID, frequency, signal, and security flags
Per-interface Wi-Fi scoping with nm.wifi("wlan0")
Open networks
WPA-PSK personal networks
WPA-EAP PEAP/MSCHAPv2
WPA-EAP TTLS/PAP
EAP-TLS with certificate/key paths or blobs
WPA3-Enterprise 192-bit mode
Hidden networks
BSSID-specific connection
Race-free try_connect / try_connect_to_bssid
Wi-Fi P2P connection management

Wired, Bluetooth, And VLAN

Ethernet DHCP connections
Bluetooth PAN/DUN device discovery and connection
VLAN profile builder and validation
Loopback device detection
Bond profile builder
Bridge profile builder
TUN/TAP profile builder
MACVLAN / MACsec / VRF / VXLAN profile builders

VPN

WireGuard profile builder and connection support
OpenVPN profile builder
.ovpn import support
Saved VPN discovery for WireGuard and plugin VPNs
Connect/disconnect saved VPNs by UUID or name
Active VPN listing and connection details
Generic plugin VPN detection (OpenConnect, strongSwan, PPTP, L2TP, etc.)
Builders/importers for non-OpenVPN plugin VPN profiles

Profiles, Radio, And Connectivity

Saved connection listing, raw access, decoded summaries, update, delete, and reload
Profile reuse for saved Wi-Fi and Ethernet connections
Secret agent for NetworkManager credential prompts
Real-time network and device monitoring
Wi-Fi, WWAN, Bluetooth, and aggregate airplane-mode radio state
Connectivity state, forced connectivity checks, and captive-portal URL detection
IPv4, IPv6, DHCPv4, and DHCPv6 settings

Device And D-Bus Surface

NetworkManager facade
Device enumeration and typed device models for Ethernet, Wi-Fi, Bluetooth, VLAN, Loopback, and Wi-Fi P2P
Device metadata registry for Bond, Bridge, TUN, WireGuard, and other known NetworkManager type codes
Access Point
Active Connection
Settings
Settings Connection
Agent Manager
VPN Connection
Checkpoint
DNS Manager
PPP
Modem / WWAN connection management
WiMAX NSP

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

Requirements

Rust: 1.90.0+
NetworkManager: Running and accessible via D-Bus
Linux: This library is Linux-specific

License

This project is dual-licensed under either of the following licenses, at your option:

MIT License
Apache License, Version 2.0

You may use, copy, modify, and distribute this software under the terms of either license.

See the following files for full license texts:

Contributors

Thank you to everyone who has helped build, test, document, and review nmrs.

_cachebag	_stoutes	_pluiee	_JonnieCache	_tristanmsct	_Rifat-R
_of-the-stars	_okhsunrog	_ruthwik-01	_joncorv	_AK78gz	_pwsandoval
_ritiek	_{shubhsingh5901}	_cinnamonstic	_tuned-willow	_dandiggas