nmrs 🦀

A 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.

The project is divided into the following crates:

• nmrs: The core library providing NetworkManager bindings and Wi-Fi management API.
• nmrs-gui: A Wayland-compatible GTK4 graphical interface for NetworkManager. Jump to the GUI section of this repo

Getting Started

The best way to get started with nmrs is the API documentation, which includes examples for common operations like scanning networks, connecting to Wi-Fi, and managing connection profiles.

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().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", 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", 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.

nmrs-gui

This repository also includes nmrs-gui, a Wayland-compatible NetworkManager frontend built with GTK4.

Installation

Arch Linux (AUR)

yay -S nmrs
# or
paru -S nmrs

Nix

nix-shell -p nmrs

Configuration

Waybar Integration

"network": {
    "on-click": "nmrs"
}

Tiling Window Managers (Hyprland, Sway, i3)

windowrule = float 1, match:class org.nmrs.ui

Custom Styling

Edit ~/.config/nmrs/style.css to customize the interface. There are also pre-defined themes you can pick from in the interface itself.

Roadmap / Implementation Status

Devices

• Generic
• Wireless
• Any
• Wired
• ADSL
• Bluetooth
• Bond
• Bridge
• Dummy
• HSR (NetworkManager ≥ 1.46)
• Infiniband
• IP Tunnel
• IPVLAN (NetworkManager ≥ 1.52)
• Lowpan
• Loopback
• MACsec
• MACVLAN
• Modem
• OLPC Mesh
• OVS Bridge
• OVS Interface
• OVS Port
• PPP
• Statistics
• Team
• TUN/TAP
• VETH
• VLAN
• VRF
• VXLAN
• Wi-Fi P2P
• WiMAX
• WireGuard
• WPAN

Configurations

• IPv4
• IPv6
• DHCPv4
• DHCPv6

Core Interfaces

• NetworkManager (partial)
• Device
• Access Point
• Active Connection
• Settings
• Settings Connection
• Agent Manager
• Checkpoint
• DNS Manager
• PPP
• Secret Agent
• VPN Connection (WireGuard)
• VPN Plugin
• Wi-Fi P2P
• WiMAX NSP

Contributing

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

Requirements

• Rust: 1.78.0 or later (for nmrs library)
• Rust: 1.85.1 or later (for nmrs-gui with GTK4)
• 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