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:

• MIT License
• Apache License 2.0

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