nmrs 🦀

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.

Some cool projects using nmrs

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
• WPA3-Personal SAE
• WPA-EAP PEAP/MSCHAPv2
• WPA-EAP TTLS/PAP
• EAP-TLS with certificate/key paths or blobs
• WPA3-Enterprise 192-bit mode
• Hidden-network profiles via WifiConnectionBuilder::hidden
• BSSID-specific connection
• Race-free try_connect / try_connect_to_bssid
• Hotspot (AP) and ad-hoc modes with shared IPv4
• Hidden networks in connect() (directed scan for a non-broadcast SSID)
• Wi-Fi P2P connection management

Wired, Bluetooth, And VLAN

• Ethernet DHCP connections
• Wired device details with MAC, link speed, and assigned addresses
• 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
• Activate/deactivate any saved profile by UUID with connect_by_uuid / disconnect_by_uuid
• Secret agent for NetworkManager credential prompts
• Real-time network and device monitoring
• Typed network_events() / settings_events() streams and point-in-time snapshot()
• Per-device autoconnect and managed controls
• Wi-Fi, WWAN, Bluetooth, and aggregate airplane-mode radio state
• Connectivity state, forced connectivity checks, and captive-portal URL detection
• IPv4 and IPv6 method, addresses, DNS, gateway, and routes
• DHCP client options and lease details (DHCP4Config / DHCP6Config)

Device And D-Bus Surface

• NetworkManager facade
• Generic ConnectionBuilder, add_connection / add_and_activate_connection, and raw zbus access
• Device enumeration and typed device models for Ethernet, Wi-Fi, Bluetooth, VLAN, Loopback, and Wi-Fi P2P
• Device metadata registry for Bond, Bridge, TUN, Veth, WireGuard, and other known NetworkManager type codes
• Access Point
• Active Connection
• Settings
• Settings Connection
• Agent Manager
• Device.Wireless, Device.Wired, and Device.Bluetooth
• BlueZ Adapter1 / Device1
• VPN Connection (VPN state is currently read through Active Connection)
• Checkpoint
• DNS Manager
• PPP
• Modem / WWAN connection management
• WiMAX NSP

Contributing

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

Environmental tests are opt-in and ignored by a normal cargo test, so local test runs never probe the host NetworkManager implicitly. Use docker compose run --build --rm test-integration for isolated settings, NetworkManager-routed secrets, native WireGuard activation, and veth-backed wired DHCP lifecycles, or test-wifi-integration with two mac80211_hwsim radios for the deterministic WPA/DHCP and callback-monitor lifecycle. See the contributing guide for the exact commands.

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.