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 :mod:`NetworkManager` module -------------------------------- .. module:: NetworkManager :platform: Linux systems with NetworkManager 0.9 and newer :synopsis: Talk to NetworkManager from python All the code is contained in one module: :mod:`NetworkManager`. Using it is as simple as you think it is: .. code-block:: py >>> 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. .. function:: 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 :data:`NM_STATE_CONNECTED_GLOBAL`, can all be found in the :mod:`NetworkManager` module as well. The :func:`const` function can help you translate them to text. For example: .. code-block:: py >>> NetworkManager.const('state', 40) 'connecting' >>> NetworkManager.const('device_type', 2) 'wifi' .. _`NetworkManager project website`: https://developer.gnome.org/NetworkManager/1.2/spec.html List of classes --------------- .. class:: 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:: 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 :data:`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 :data:`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 On\ *SignalName* 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:: 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 The main `NetworkManager `_ object; the `NetworkManager.Networkmanager` object is actually the singleton instance of this class. .. class:: 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:: 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:: Connection `Connection `_ objects represent network configurations configured by the user. .. class:: ActiveConnection .. class:: 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:: IP4Config .. class:: IP6Config .. class:: DHCP4Config .. class:: 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:: AccessPoint Wifi `Accesspoints `_, as visibly by any 802.11 wifi interface. .. class:: NSP Wimax `Network Service Providers `_. .. class:: 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:: 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. .. toctree:: :maxdepth: 2