Python API to talk to NetworkManager

NetworkManager provides a detailed and capable D-Bus interface on the system bus. You can use this interface to query NetworkManager about the overall state of the network and details of network devices like current IP addresses or DHCP options, and to configure, activate and deactivate network connections.

python-networkmanager takes this D-Bus interface and wraps D-Bus interfaces in classes and D-Bus methods and properties in their python equivalents.

The NetworkManager module

All the code is contained in one module: NetworkManager. Using it is as simple as you think it is:

>>> import NetworkManager
>>> NetworkManager.NetworkManager.Version
'1.2.0'

NetworkManager exposes a lot of information via D-Bus and also allows full control of network settings. The full D-Bus interface can be found on NetworkManager project website. All interfaces listed there have been wrapped in classes as listed below.

NetworkManager.const(prefix, value)

Many of NetworkManagers D-Bus methods expect or return numeric constants, for which there are enums in the C source code. These constants, such as NM_STATE_CONNECTED_GLOBAL, can all be found in the NetworkManager module as well. The const() function can help you translate them to text. For example:

>>> NetworkManager.const('state', 40)
'connecting'
>>> NetworkManager.const('device_type', 2)
'wifi'

List of classes

class NetworkManager.ObjectVanished

This Exception will be raised when you try to call a method or access a property on a dbus object that no longer exists. Objects can go missing if devices are removed, connections are disabled or NetworkManager is restarted.

class NetworkManager.NMDbusInterface

This is the base class of all classes below. It handles the marshalling of data and the automatic creation of properties and methods.

Each property, method and signal exposed via the D-Bus interface is automatically mirrored as an attribute of the actual classes. Moreover, the data is made slightly more usable by performing the following transformations on received and sent data.

• IP addresses are returned as strings of the form 1.2.3.4 instead of network byte ordered integers.
• Route metrics are returned in host byte order, so you can use them as integers.
• Mac addresses and BSSIDs are always returned as strings of the form 00:11:22:33:44:55 instead of byte sequences.
• Wireless SSID’s are returned as strings instead of byte sequences. They will be decoded as UTF-8 data, so using any other encoding for your SSID will result in errors.
• DHCP options are turned into integers or booleans as appropriate
• Signals can be connected to using calls to OnSignalName functions.

Here’s a short example to illustrate:

>>> NetworkManager.NetworkManager.Version
'1.4.4'
>>> NetworkManager.NetworkManager.GetPermissions()
{'org.freedesktop.NetworkManager.checkpoint-rollback': 'auth',
 'org.freedesktop.NetworkManager.enable-disable-network': 'yes',
 ...}
# Must have a mainloop to use signals
>>> import dbus.mainloop.glib
>>> dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
>>> NetworkManager.Networkmanager.OnStateChanged(handle_state_change)

class NetworkManager.TransientNMDbusInterface

Subclasses of this class, which are ActiveConnection, NSP, IP[46]Config and DHCP[46]Config never survive a NetworkManager restart. Other objects may survive a restart, but get a different object path.

class NetworkManager.NetworkManager

The main NetworkManager object; the NetworkManager.Networkmanager object is actually the singleton instance of this class.

class NetworkManager.Settings

The Settings object, which can be used to add connections, list connections or update your hostname; the NetworkManager.Settings object is actually the singleton instance of this class.

class NetworkManager.AgentManager

The AgentManager object, whose methods you’ll need to call when implementing a secrets agent; the NetworkManager.AgentManager object is actually the singleton instance of this class.

class NetworkManager.Connection

Connection objects represent network configurations configured by the user.

class NetworkManager.ActiveConnection

class NetworkManager.VPNConnection

Active connections are represented by ActiveConnection objects. VPNConnection is a subclass for active VPN connection that implements both the Connection.Active and VPN.Connection interfaces.

class NetworkManager.IP4Config

class NetworkManager.IP6Config

class NetworkManager.DHCP4Config

class NetworkManager.DHCP6Config

Active network connections and devices can all have IPv4, IPv6, IPv4 DHCP and IPv6 DHCP information attached to them, which is represented by instances of these classes.

class NetworkManager.AccessPoint

Wifi Accesspoints, as visibly by any 802.11 wifi interface.

class NetworkManager.NSP

Wimax Network Service Providers.

class NetworkManager.Device

All device classes implement the Device interface, which gives you access to basic device properties. Note that you will never see instances of this class, only of its devicetype-specific subclasses which impletemnt not only the Device interface but also their own specific interface. Supported device types are Adsl, Bluetooth, Bond, Bridge, Generic, Infiniband, IPTunnel, Macvlan, Modem, OlpcMesh, Team, Tun, Veth, Vlan, Vxlan, Wimax, Wired and Wireless

class NetworkManager.SecretAgent

The NetworkManager daemon can ask separate programs, called agents, for secrets if it needs them. The NetworkManager applet and the nmcli command-line tool are examples of such agents. You can also write such agents by subclassing the SecretAgent class and providing a GetSecrets method as in the following example, which returns a static password for each secret:

import dbus.mainloop.glib
import GObject
import NetworkManager

class MyAgent(NetworkManager.SecretAgent):
    def GetSecrets(self, settings, connection, setting_name, hints, flags):
        return {setting_name: {'secrets': {'password': 'TopSecret!'}}}

agent = MyAgent()
dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
Gobject.MainLoop().run()

Beware that NetworkManager will ask each agent in turn in what is in essence random order. Except it will prioritize the program that activated the connection. So if you want to make sure your agent is called first, activate the connection from the same application.