NM.Connection

g GObject.GInterface GObject.GInterface NM.Connection NM.Connection GObject.GInterface->NM.Connection

Implementations:

NM.RemoteConnection, NM.SimpleConnection

Methods

add_setting (setting)

clear_secrets ()

clear_secrets_with_flags (func, *user_data)

clear_settings ()

compare (b, flags)

dump ()

for_each_setting_value (func, *user_data)

get_connection_type ()

get_id ()

get_interface_name ()

get_path ()

get_setting (setting_type)

get_setting_802_1x ()

get_setting_adsl ()

get_setting_bluetooth ()

get_setting_bond ()

get_setting_bridge ()

get_setting_bridge_port ()

get_setting_by_name (name)

get_setting_cdma ()

get_setting_connection ()

get_setting_dcb ()

get_setting_dummy ()

get_setting_generic ()

get_setting_gsm ()

get_setting_infiniband ()

get_setting_ip4_config ()

get_setting_ip6_config ()

get_setting_ip_tunnel ()

get_setting_macsec ()

get_setting_macvlan ()

get_setting_olpc_mesh ()

get_setting_ovs_bridge ()

get_setting_ovs_interface ()

get_setting_ovs_patch ()

get_setting_ovs_port ()

get_setting_ppp ()

get_setting_pppoe ()

get_setting_proxy ()

get_setting_serial ()

get_setting_tc_config ()

get_setting_team ()

get_setting_team_port ()

get_setting_tun ()

get_setting_vlan ()

get_setting_vpn ()

get_setting_vxlan ()

get_setting_wimax ()

get_setting_wired ()

get_setting_wireless ()

get_setting_wireless_security ()

get_settings ()

get_uuid ()

get_virtual_device_description ()

is_type (type)

is_virtual ()

need_secrets ()

normalize (parameters)

remove_setting (setting_type)

replace_settings (new_settings)

replace_settings_from_connection (new_connection)

set_path (path)

to_dbus (flags)

update_secrets (setting_name, secrets)

verify ()

verify_secrets ()

Virtual Methods

do_changed ()

do_secrets_cleared ()

do_secrets_updated (setting)

Properties

None

Signals

Name

Short Description

changed

The ::changed signal is emitted when any property (including secrets) of any setting of the connection is modified, or when settings are added or removed.

secrets-cleared

The ::secrets-cleared signal is emitted when the secrets of a connection are cleared.

secrets-updated

The ::secrets-updated signal is emitted when the secrets of a setting have been changed.

Fields

None

Class Details

class NM.Connection
Bases:

GObject.GInterface

Structure:

NM.ConnectionInterface

NM.Connection is the interface implemented by NM.RemoteConnection on the client side, and #NMSettingsConnection on the daemon side.

add_setting(setting)
Parameters:

setting (NM.Setting) – the NM.Setting to add to the connection object

Adds a NM.Setting to the connection, replacing any previous NM.Setting of the same name which has previously been added to the NM.Connection. The connection takes ownership of the NM.Setting object and does not increase the setting object’s reference count.

clear_secrets()

Clears and frees any secrets that may be stored in the connection, to avoid keeping secret data in memory when not needed.

clear_secrets_with_flags(func, *user_data)
Parameters:

Clears and frees secrets determined by func.

clear_settings()

Deletes all of self's settings.

compare(b, flags)
Parameters:
Returns:

True if the comparison succeeds, False if it does not

Return type:

bool

Compares two NM.Connection objects for similarity, with comparison behavior modified by a set of flags. See NM.Setting.compare() for a description of each flag’s behavior.

dump()

Print the connection (including secrets!) to stdout. For debugging purposes ONLY, should NOT be used for serialization of the setting, or machine-parsed in any way. The output format is not guaranteed to be stable and may change at any time.

for_each_setting_value(func, *user_data)
Parameters:

  • func (NM.SettingValueIterFn) – user-supplied function called for each setting’s property

  • user_data (object or None) – user data passed to func at each invocation

Iterates over the properties of each NM.Setting object in the NM.Connection, calling the supplied user function for each property.

get_connection_type()
Returns:

the type from the connection’s ‘connection’ setting

Return type:

str

A shortcut to return the type from the connection’s NM.SettingConnection.

get_id()
Returns:

the ID from the connection’s ‘connection’ setting

Return type:

str

A shortcut to return the ID from the connection’s NM.SettingConnection.

get_interface_name()
Returns:

Name of the kernel interface or None

Return type:

str

Returns the interface name as stored in NMSettingConnection:interface_name. If the connection contains no NM.SettingConnection, it will return None.

For hardware devices and software devices created outside of NetworkManager, this name is used to match the device. for software devices created by NetworkManager, this is the name of the created interface.

get_path()
Returns:

the D-Bus path of the connection, previously set by a call to NM.Connection.set_path().

Return type:

str

Returns the connection’s D-Bus path.

get_setting(setting_type)
Parameters:

setting_type (GObject.GType) – the GObject.GType of the setting object to return

Returns:

the NM.Setting, or None if no setting of that type was previously added to the NM.Connection

Return type:

NM.Setting

Gets the NM.Setting with the given GObject.GType, if one has been previously added to the NM.Connection.

get_setting_802_1x()
Returns:

an NM.Setting8021x if the connection contains one, otherwise None

Return type:

NM.Setting8021x

A shortcut to return any NM.Setting8021x the connection might contain.

get_setting_adsl()
Returns:

an NM.SettingAdsl if the connection contains one, otherwise None

Return type:

NM.SettingAdsl

A shortcut to return any NM.SettingAdsl the connection might contain.

get_setting_bluetooth()
Returns:

an NM.SettingBluetooth if the connection contains one, otherwise None

Return type:

NM.SettingBluetooth

A shortcut to return any NM.SettingBluetooth the connection might contain.

get_setting_bond()
Returns:

an NM.SettingBond if the connection contains one, otherwise None

Return type:

NM.SettingBond

A shortcut to return any NM.SettingBond the connection might contain.

get_setting_bridge()
Returns:

an NM.SettingBridge if the connection contains one, otherwise None

Return type:

NM.SettingBridge

A shortcut to return any NM.SettingBridge the connection might contain.

get_setting_bridge_port()
Returns:

an NM.SettingBridgePort if the connection contains one, otherwise None

Return type:

NM.SettingBridgePort

A shortcut to return any NM.SettingBridgePort the connection might contain.

get_setting_by_name(name)
Parameters:

name (str) – a setting name

Returns:

the NM.Setting, or None if no setting with that name was previously added to the NM.Connection

Return type:

NM.Setting

Gets the NM.Setting with the given name, if one has been previously added the NM.Connection.

get_setting_cdma()
Returns:

an NM.SettingCdma if the connection contains one, otherwise None

Return type:

NM.SettingCdma

A shortcut to return any NM.SettingCdma the connection might contain.

get_setting_connection()
Returns:

an NM.SettingConnection if the connection contains one, otherwise None

Return type:

NM.SettingConnection

A shortcut to return any NM.SettingConnection the connection might contain.

get_setting_dcb()
Returns:

an NM.SettingDcb if the connection contains one, otherwise None

Return type:

NM.SettingDcb

A shortcut to return any NM.SettingDcb the connection might contain.

get_setting_dummy()
Returns:

an NM.SettingDummy if the connection contains one, otherwise None

Return type:

NM.SettingDummy

A shortcut to return any NM.SettingDummy the connection might contain.

New in version 1.8.

get_setting_generic()
Returns:

an NM.SettingGeneric if the connection contains one, otherwise None

Return type:

NM.SettingGeneric

A shortcut to return any NM.SettingGeneric the connection might contain.

get_setting_gsm()
Returns:

an NM.SettingGsm if the connection contains one, otherwise None

Return type:

NM.SettingGsm

A shortcut to return any NM.SettingGsm the connection might contain.

get_setting_infiniband()
Returns:

an NM.SettingInfiniband if the connection contains one, otherwise None

Return type:

NM.SettingInfiniband

A shortcut to return any NM.SettingInfiniband the connection might contain.

get_setting_ip4_config()
Returns:

an NM.SettingIP4Config if the connection contains one, otherwise None

Return type:

NM.SettingIP4Config

A shortcut to return any NM.SettingIP4Config the connection might contain.

Note that it returns the value as type NM.SettingIPConfig, since the vast majority of IPv4-setting-related methods are on that type, not NM.SettingIP4Config.

get_setting_ip6_config()
Returns:

an NM.SettingIP6Config if the connection contains one, otherwise None

Return type:

NM.SettingIP6Config

A shortcut to return any NM.SettingIP6Config the connection might contain.

Note that it returns the value as type NM.SettingIPConfig, since the vast majority of IPv6-setting-related methods are on that type, not NM.SettingIP6Config.

get_setting_ip_tunnel()
Returns:

an NM.SettingIPTunnel if the connection contains one, otherwise None

Return type:

NM.SettingIPTunnel

A shortcut to return any NM.SettingIPTunnel the connection might contain.

New in version 1.2.

get_setting_macsec()
Returns:

an NM.SettingMacsec if the connection contains one, otherwise None

Return type:

NM.SettingMacsec

A shortcut to return any NM.SettingMacsec the connection might contain.

New in version 1.6.

get_setting_macvlan()
Returns:

an NM.SettingMacvlan if the connection contains one, otherwise None

Return type:

NM.SettingMacvlan

A shortcut to return any NM.SettingMacvlan the connection might contain.

New in version 1.2.

get_setting_olpc_mesh()
Returns:

an NM.SettingOlpcMesh if the connection contains one, otherwise None

Return type:

NM.SettingOlpcMesh

A shortcut to return any NM.SettingOlpcMesh the connection might contain.

get_setting_ovs_bridge()
Returns:

an NM.SettingOvsBridge if the connection contains one, otherwise None

Return type:

NM.SettingOvsBridge

A shortcut to return any NM.SettingOvsBridge the connection might contain.

New in version 1.14.

get_setting_ovs_interface()
Returns:

an NM.SettingOvsInterface if the connection contains one, otherwise None

Return type:

NM.SettingOvsInterface

A shortcut to return any NM.SettingOvsInterface the connection might contain.

New in version 1.14.

get_setting_ovs_patch()
Returns:

an NM.SettingOvsPatch if the connection contains one, otherwise None

Return type:

NM.SettingOvsPatch

A shortcut to return any NM.SettingOvsPatch the connection might contain.

New in version 1.14.

get_setting_ovs_port()
Returns:

an NM.SettingOvsPort if the connection contains one, otherwise None

Return type:

NM.SettingOvsPort

A shortcut to return any NM.SettingOvsPort the connection might contain.

New in version 1.14.

get_setting_ppp()
Returns:

an NM.SettingPpp if the connection contains one, otherwise None

Return type:

NM.SettingPpp

A shortcut to return any NM.SettingPpp the connection might contain.

get_setting_pppoe()
Returns:

an NM.SettingPppoe if the connection contains one, otherwise None

Return type:

NM.SettingPppoe

A shortcut to return any NM.SettingPppoe the connection might contain.

get_setting_proxy()
Returns:

an NM.SettingProxy if the connection contains one, otherwise None

Return type:

NM.SettingProxy

A shortcut to return any NM.SettingProxy the connection might contain.

New in version 1.6.

get_setting_serial()
Returns:

an NM.SettingSerial if the connection contains one, otherwise None

Return type:

NM.SettingSerial

A shortcut to return any NM.SettingSerial the connection might contain.

get_setting_tc_config()
Returns:

an NM.SettingTCConfig if the connection contains one, otherwise None

Return type:

NM.SettingTCConfig

A shortcut to return any NM.SettingTCConfig the connection might contain.

New in version 1.12.

get_setting_team()
Returns:

an NM.SettingTeam if the connection contains one, otherwise None

Return type:

NM.SettingTeam

A shortcut to return any NM.SettingTeam the connection might contain.

get_setting_team_port()
Returns:

an NM.SettingTeamPort if the connection contains one, otherwise None

Return type:

NM.SettingTeamPort

A shortcut to return any NM.SettingTeamPort the connection might contain.

get_setting_tun()
Returns:

an NM.SettingTun if the connection contains one, otherwise None

Return type:

NM.SettingTun

A shortcut to return any NM.SettingTun the connection might contain.

New in version 1.14.

get_setting_vlan()
Returns:

an NM.SettingVlan if the connection contains one, otherwise None

Return type:

NM.SettingVlan

A shortcut to return any NM.SettingVlan the connection might contain.

get_setting_vpn()
Returns:

an NM.SettingVpn if the connection contains one, otherwise None

Return type:

NM.SettingVpn

A shortcut to return any NM.SettingVpn the connection might contain.

get_setting_vxlan()
Returns:

an NM.SettingVxlan if the connection contains one, otherwise None

Return type:

NM.SettingVxlan

A shortcut to return any NM.SettingVxlan the connection might contain.

New in version 1.2.

get_setting_wimax()
Returns:

an NM.SettingWimax if the connection contains one, otherwise None

Return type:

NM.SettingWimax

A shortcut to return any NM.SettingWimax the connection might contain.

get_setting_wired()
Returns:

an NM.SettingWired if the connection contains one, otherwise None

Return type:

NM.SettingWired

A shortcut to return any NM.SettingWired the connection might contain.

get_setting_wireless()
Returns:

an NM.SettingWireless if the connection contains one, otherwise None

Return type:

NM.SettingWireless

A shortcut to return any NM.SettingWireless the connection might contain.

get_setting_wireless_security()
Returns:

an NM.SettingWirelessSecurity if the connection contains one, otherwise None

Return type:

NM.SettingWirelessSecurity

A shortcut to return any NM.SettingWirelessSecurity the connection might contain.

get_settings()
Returns:

a None-terminated array containing every setting of self. If the connection has no settings, None is returned.

Return type:

[NM.Setting] or None

Retrieves the settings in self.

The returned array is None-terminated.

New in version 1.10.

get_uuid()
Returns:

the UUID from the connection’s ‘connection’ setting

Return type:

str

A shortcut to return the UUID from the connection’s NM.SettingConnection.

get_virtual_device_description()
Returns:

the name of self's device, or None if self is not a virtual connection type

Return type:

str

Returns the name that NM.Device.disambiguate_names() would return for the virtual device that would be created for self. Eg, “VLAN (eth1.1)”.

is_type(type)
Parameters:

type (str) – a setting name to check the connection’s type against (like NM.SETTING_WIRELESS_SETTING_NAME or NM.SETTING_WIRED_SETTING_NAME)

Returns:

True if the connection is of the given type, False if not

Return type:

bool

A convenience function to check if the given self is a particular type (ie wired, Wi-Fi, ppp, etc). Checks the NM.SettingConnection :type property of the connection and matches that against type.

is_virtual()
Returns:

whether self refers to a virtual device

Return type:

bool

Checks if self refers to a virtual device (and thus can potentially be activated even if the device it refers to doesn’t exist).

need_secrets()
Returns:

the setting name of the NM.Setting object which has invalid or missing secrets

hints:

the address of a pointer to a GLib.PtrArray, initialized to None, which on return points to an allocated GLib.PtrArray containing the property names of secrets of the NM.Setting which may be required; the caller owns the array and must free the array itself with g_ptr_array_free(), but not free its elements

Return type:

(str or None, hints: [str])

Returns the name of the first setting object in the connection which would need secrets to make a successful connection. The returned hints are only intended as a guide to what secrets may be required, because in some circumstances, there is no way to conclusively determine exactly which secrets are needed.

normalize(parameters)
Parameters:

parameters ({str: object} or None) – a GLib.HashTable with normalization parameters to allow customization of the normalization by providing specific arguments. Unknown arguments will be ignored and the default will be used. The keys must be strings compared with GLib.str_equal() function. The values are opaque and depend on the parameter name.

Raises:

GLib.Error

Returns:

True if the connection is valid, False if it is not

modified:

outputs whether any settings were modified.

Return type:

(bool, modified: bool)

Does some basic normalization and fixup of well known inconsistencies and deprecated fields. If the connection was modified in any way, the output parameter modified is set True.

Finally the connection will be verified and True returns if the connection is valid. As this function only performs some specific normalization steps it cannot repair all connections. If the connection has errors that cannot be normalized, the connection will not be modified.

remove_setting(setting_type)
Parameters:

setting_type (GObject.GType) – the GObject.GType of the setting object to remove

Removes the NM.Setting with the given GObject.GType from the NM.Connection. This operation dereferences the NM.Setting object.

replace_settings(new_settings)
Parameters:

new_settings (GLib.Variant) – a GLib.Variant of type %NM_VARIANT_TYPE_CONNECTION, with the new settings

Raises:

GLib.Error

Returns:

True if connection was updated, False if new_settings could not be deserialized (in which case self will be unchanged).

Return type:

bool

Replaces self's settings with new_settings (which must be syntactically valid, and describe a known type of connection, but does not need to result in a connection that passes NM.Connection.verify()).

replace_settings_from_connection(new_connection)
Parameters:

new_connection (NM.Connection) – a NM.Connection to replace the settings of self with

Deep-copies the settings of new_connection and replaces the settings of self with the copied settings.

set_path(path)
Parameters:

path (str) – the D-Bus path of the connection as given by the settings service which provides the connection

Sets the D-Bus path of the connection. This property is not serialized, and is only for the reference of the caller. Sets the NM.Connection :path property.

to_dbus(flags)
Parameters:

flags (NM.ConnectionSerializationFlags) – serialization flags, e.g. NM.ConnectionSerializationFlags.ALL

Returns:

a new floating GLib.Variant describing the connection, its settings, and each setting’s properties.

Return type:

GLib.Variant

Converts the NM.Connection into a GLib.Variant of type %NM_VARIANT_TYPE_CONNECTION describing the connection, suitable for marshalling over D-Bus or otherwise serializing.

update_secrets(setting_name, secrets)
Parameters:

  • setting_name (str) – the setting object name to which the secrets apply

  • secrets (GLib.Variant) – a GLib.Variant of secrets, of type %NM_VARIANT_TYPE_CONNECTION or %NM_VARIANT_TYPE_SETTING

Raises:

GLib.Error

Returns:

True if the secrets were successfully updated, False if the update failed (tried to update secrets for a setting that doesn’t exist, etc)

Return type:

bool

Update the specified setting’s secrets, given a dictionary of secrets intended for that setting (deserialized from D-Bus for example). Will also extract the given setting’s secrets hash if given a connection dictionary. If setting_name is None, expects a fully serialized NM.Connection as returned by NM.Connection.to_dbus() and will update all secrets from all settings contained in secrets.

verify()
Raises:

GLib.Error

Returns:

True if the connection is valid, False if it is not

Return type:

bool

Validates the connection and all its settings. Each setting’s properties have allowed values, and some values are dependent on other values. For example, if a Wi-Fi connection is security enabled, the NM.SettingWireless setting object’s ‘security’ property must contain the setting name of the NM.SettingWirelessSecurity object, which must also be present in the connection for the connection to be valid. As another example, the NM.SettingWired object’s ‘mac-address’ property must be a validly formatted MAC address. The returned GLib.Error contains information about which setting and which property failed validation, and how it failed validation.

verify_secrets()
Raises:

GLib.Error

Returns:

True if the secrets are valid, False if they are not

Return type:

bool

Verifies the secrets in the connection.

New in version 1.2.

do_changed() virtual

emitted when any change to the connection’s settings occurs

do_secrets_cleared() virtual

emitted when the connection’s secrets are cleared

do_secrets_updated(setting) virtual
Parameters:

setting (str) –

emitted when the connection’s secrets are updated

Signal Details

NM.Connection.signals.changed(connection)
Signal Name:

changed

Flags:

RUN_FIRST

Parameters:

connection (NM.Connection) – The object which received the signal

The ::changed signal is emitted when any property (including secrets) of any setting of the connection is modified, or when settings are added or removed.

NM.Connection.signals.secrets_cleared(connection)
Signal Name:

secrets-cleared

Flags:

RUN_FIRST

Parameters:

connection (NM.Connection) – The object which received the signal

The ::secrets-cleared signal is emitted when the secrets of a connection are cleared.

NM.Connection.signals.secrets_updated(connection, setting_name)
Signal Name:

secrets-updated

Flags:

RUN_FIRST

Parameters:

  • connection (NM.Connection) – The object which received the signal

  • setting_name (str) – the setting name of the NM.Setting for which secrets were updated

The ::secrets-updated signal is emitted when the secrets of a setting have been changed.