NetworkManager D-Bus API quickstart

This is a tutorial to understand the structure of the NetworkManager D-Bus API and how to use it.

Note

NetworkManager usually uses the system D-Bus, however, sdbus uses the session D-Bus by default. It is recommend to call sdbus.set_default_bus(sdbus.sd_bus_open_system()) to set the system bus as default bus.

NetworkManager main object

This is a static object that contains information about entire state of NetworkManager. The Python class NetworkManager has a predefined service name and object path.

import sdbus
from sdbus_block.networkmanager import NetworkManager

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

Devices

Every device object represents a network device. Device object has a generic methods and properties that are universal across all device types and a type specific methods. The NetworkDeviceGeneric implements generic methods and, for example, NetworkDeviceWireless adds Wi-Fi specific methods.

The device_type property and enum DeviceType can be used to determine particular type of a device.

import sdbus

from sdbus_block.networkmanager import (
    NetworkDeviceGeneric,
    NetworkDeviceWireless,
    NetworkManager,
)
from sdbus_block.networkmanager.enums import DeviceType

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

all_devices = {path: NetworkDeviceGeneric(path) for path in network_manager.devices}

wifi_devices = [
    NetworkDeviceWireless(path)
    for path, device in all_devices.items()
    if device.device_type == DeviceType.WIFI
]

Connection

Connection represents a configuration containing an IP address, Wifi password, proxy settings and etc… The main object to access connections is the NetworkManagerSettings which has predefined object path.

Each individual connection has a separate path which can be accessed with NetworkConnectionSettings class.

import sdbus

from sdbus_block.networkmanager import (
    NetworkConnectionSettings,
    NetworkManager,
    NetworkManagerSettings,
)

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

networwork_manager_settings = NetworkManagerSettings()

all_connections = [
    NetworkConnectionSettings(x) for x in networwork_manager_settings.connections
]

The actual connection settings are represented by a complex double nested dictionary of D-Bus variants. For convenience a dataclass based helper is provided.

The get_profile and update_profile are two main methods to interact with connection settings helper.

import sdbus

from sdbus_block.networkmanager import (
    NetworkConnectionSettings,
    NetworkManager,
    NetworkManagerSettings,
)

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

networwork_manager_settings = NetworkManagerSettings()


connection = NetworkConnectionSettings(networwork_manager_settings.connections[0])
setting_dataclass = connection.get_profile()
print("uuid:", setting_dataclass.connection.uuid)

Active Connection

ActiveConnection is a product of a Connection being applied to a Device.

For example, activate_connection of the main NetworkManager object will create new Active Connection (therefore configuring network on a device) and return its path. The deactivate_connection will remove the active connection and remove the device’s network configuration.