NMConnection: libnm Reference Manual

+ + +

NMConnection

NMConnection — Describes a connection to specific network or provider

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+void +	+nm_connection_add_setting () +
+void +	+nm_connection_remove_setting () +
+NMSetting * +	+nm_connection_get_setting () +
+NMSetting * +	+nm_connection_get_setting_by_name () +
+GVariant * +	+nm_connection_to_dbus () +
+gboolean +	+nm_connection_replace_settings () +
+void +	+nm_connection_replace_settings_from_connection () +
+void +	+nm_connection_clear_settings () +
+gboolean +	+nm_connection_compare () +
+gboolean +	+nm_connection_diff () +
+gboolean +	+nm_connection_verify () +
+gboolean +	+nm_connection_verify_secrets () +
+gboolean +	+nm_connection_normalize () +
const char * +	+nm_connection_need_secrets () +
+void +	+nm_connection_clear_secrets () +
+void +	+nm_connection_clear_secrets_with_flags () +
+gboolean +	+nm_connection_update_secrets () +
+void +	+nm_connection_set_path () +
const char * +	+nm_connection_get_path () +
const char * +	+nm_connection_get_interface_name () +
+gboolean +	+nm_connection_is_type () +
+void +	+nm_connection_for_each_setting_value () +
+NMSetting ** +	+nm_connection_get_settings () +
+void +	+nm_connection_dump () +
const char * +	+nm_connection_get_uuid () +
const char * +	+nm_connection_get_id () +
const char * +	+nm_connection_get_connection_type () +
+gboolean +	+nm_connection_is_virtual () +
+char * +	+nm_connection_get_virtual_device_description () +
+NMSetting8021x * +	+nm_connection_get_setting_802_1x () +
+NMSettingBluetooth * +	+nm_connection_get_setting_bluetooth () +
+NMSettingBond * +	+nm_connection_get_setting_bond () +
+NMSettingTeam * +	+nm_connection_get_setting_team () +
+NMSettingTeamPort * +	+nm_connection_get_setting_team_port () +
+NMSettingBridge * +	+nm_connection_get_setting_bridge () +
+NMSettingBridgePort * +	+nm_connection_get_setting_bridge_port () +
+NMSettingCdma * +	+nm_connection_get_setting_cdma () +
+NMSettingConnection * +	+nm_connection_get_setting_connection () +
+NMSettingDcb * +	+nm_connection_get_setting_dcb () +
+NMSettingDummy * +	+nm_connection_get_setting_dummy () +
+NMSettingGeneric * +	+nm_connection_get_setting_generic () +
+NMSettingGsm * +	+nm_connection_get_setting_gsm () +
+NMSettingInfiniband * +	+nm_connection_get_setting_infiniband () +
+NMSettingIPTunnel * +	+nm_connection_get_setting_ip_tunnel () +
+NMSettingIPConfig * +	+nm_connection_get_setting_ip4_config () +
+NMSettingIPConfig * +	+nm_connection_get_setting_ip6_config () +
+NMSettingMacsec * +	+nm_connection_get_setting_macsec () +
+NMSettingMacvlan * +	+nm_connection_get_setting_macvlan () +
+NMSettingOlpcMesh * +	+nm_connection_get_setting_olpc_mesh () +
+NMSettingOvsBridge * +	+nm_connection_get_setting_ovs_bridge () +
+NMSettingOvsInterface * +	+nm_connection_get_setting_ovs_interface () +
+NMSettingOvsPatch * +	+nm_connection_get_setting_ovs_patch () +
+NMSettingOvsPort * +	+nm_connection_get_setting_ovs_port () +
+NMSettingPpp * +	+nm_connection_get_setting_ppp () +
+NMSettingPppoe * +	+nm_connection_get_setting_pppoe () +
+NMSettingProxy * +	+nm_connection_get_setting_proxy () +
+NMSettingSerial * +	+nm_connection_get_setting_serial () +
+NMSettingTCConfig * +	+nm_connection_get_setting_tc_config () +
+NMSettingTun * +	+nm_connection_get_setting_tun () +
+NMSettingVpn * +	+nm_connection_get_setting_vpn () +
+NMSettingWimax * +	+nm_connection_get_setting_wimax () +
+NMSettingAdsl * +	+nm_connection_get_setting_adsl () +
+NMSettingWired * +	+nm_connection_get_setting_wired () +
+NMSettingWireless * +	+nm_connection_get_setting_wireless () +
+NMSettingWirelessSecurity * +	+nm_connection_get_setting_wireless_security () +
+NMSettingVlan * +	+nm_connection_get_setting_vlan () +
+NMSettingVxlan * +	+nm_connection_get_setting_vxlan () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

#define	NM_CONNECTION_SECRETS_UPDATED
#define	NM_CONNECTION_SECRETS_CLEARED
#define	NM_CONNECTION_CHANGED
#define	NM_CONNECTION_NORMALIZE_PARAM_IP4_CONFIG_METHOD
#define	NM_CONNECTION_NORMALIZE_PARAM_IP6_CONFIG_METHOD
	NMConnectionInterface
#define	NM_VARIANT_TYPE_SETTING
enum	NMConnectionSerializationFlags

Object Hierarchy

    GFlags
+    ╰── NMConnectionSerializationFlags
+

Description

An NMConnection describes all the settings and configuration values that +are necessary to configure network devices for operation on a specific +network. Connections are the fundamental operating object for +NetworkManager; no device is connected without a NMConnection, or +disconnected without having been connected with a NMConnection.

Each NMConnection contains a list of NMSetting objects usually referenced +by name (using nm_connection_get_setting_by_name()) or by type (with +nm_connection_get_setting()). The settings describe the actual parameters +with which the network devices are configured, including device-specific +parameters (MTU, SSID, APN, channel, rate, etc) and IP-level parameters +(addresses, routes, addressing methods, etc).

Functions

nm_connection_add_setting ()

void
+nm_connection_add_setting (NMConnection *connection,
+                           NMSetting *setting);

Adds a NMSetting to the connection, replacing any previous NMSetting of the +same name which has previously been added to the NMConnection. The +connection takes ownership of the NMSetting object and does not increase +the setting object's reference count.

Parameters

+++++ + + + + + + + + + + + + +

connection	a NMConnection
setting	the NMSetting to add to the connection object.	[transfer full]

nm_connection_remove_setting ()

void
+nm_connection_remove_setting (NMConnection *connection,
+                              GType setting_type);

Removes the NMSetting with the given GType from the NMConnection. This +operation dereferences the NMSetting object.

Parameters

+++++ + + + + + + + + + + + + +

connection	a NMConnection
setting_type	the GType of the setting object to remove

nm_connection_get_setting ()

NMSetting *
+nm_connection_get_setting (NMConnection *connection,
+                           GType setting_type);

Gets the NMSetting with the given GType, if one has been previously added +to the NMConnection.

Parameters

+++++ + + + + + + + + + + + + +

connection	a NMConnection
setting_type	the GType of the setting object to return

Returns

the NMSetting, or NULL if no setting of that type was previously +added to the NMConnection.

[transfer none]

nm_connection_get_setting_by_name ()

NMSetting *
+nm_connection_get_setting_by_name (NMConnection *connection,
+                                   const char *name);

Gets the NMSetting with the given name, if one has been previously added +the NMConnection.

Parameters

+++++ + + + + + + + + + + + + +

connection	a NMConnection
name	a setting name

Returns

the NMSetting, or NULL if no setting with that name was previously +added to the NMConnection.

[transfer none]

nm_connection_to_dbus ()

GVariant *
+nm_connection_to_dbus (NMConnection *connection,
+                       NMConnectionSerializationFlags flags);

Converts the NMConnection into a GVariant of type +NM_VARIANT_TYPE_CONNECTION describing the connection, suitable for +marshalling over D-Bus or otherwise serializing.

Parameters

+++++ + + + + + + + + + + + + +

connection	the NMConnection
flags	serialization flags, e.g. `NM_CONNECTION_SERIALIZE_ALL`

Returns

a new floating GVariant describing the connection, +its settings, and each setting's properties.

[transfer none]

nm_connection_replace_settings ()

gboolean
+nm_connection_replace_settings (NMConnection *connection,
+                                GVariant *new_settings,
+                                GError **error);

Replaces connection +'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()).

Parameters

+++++ + + + + + + + + + + + + + + + + + +

connection	a NMConnection
new_settings	a GVariant of type `NM_VARIANT_TYPE_CONNECTION`, with the new settings
error	location to store error, or `NULL`

Returns

TRUE if connection was updated, FALSE if new_settings +could not +be deserialized (in which case connection +will be unchanged).

nm_connection_replace_settings_from_connection ()

void
+nm_connection_replace_settings_from_connection
+                               (NMConnection *connection,
+                                NMConnection *new_connection);

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

Parameters

+++++ + + + + + + + + + + + + +

connection	a NMConnection
new_connection	a NMConnection to replace the settings of `connection` +with

nm_connection_clear_settings ()

void
+nm_connection_clear_settings (NMConnection *connection);

Deletes all of connection +'s settings.

Parameters

+++++ + + + + + +

connection

a NMConnection

nm_connection_compare ()

gboolean
+nm_connection_compare (NMConnection *a,
+                       NMConnection *b,
+                       NMSettingCompareFlags flags);

Compares two NMConnection objects for similarity, with comparison behavior +modified by a set of flags. See nm_setting_compare() for a description of +each flag's behavior.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

a	a NMConnection
b	a second NMConnection to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`

Returns

TRUE if the comparison succeeds, FALSE if it does not

nm_connection_diff ()

gboolean
+nm_connection_diff (NMConnection *a,
+                    NMConnection *b,
+                    NMSettingCompareFlags flags,
+                    GHashTable **out_settings);

Compares two NMConnection objects for similarity, with comparison behavior +modified by a set of flags. See nm_setting_compare() for a description of +each flag's behavior. If the connections differ, settings and keys within +each setting that differ are added to the returned out_settings + hash table. +No values are returned, only key names.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

a	a NMConnection
b	a second NMConnection to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`
out_settings	if the +connections differ, on return a hash table mapping setting names to +second-level GHashTable (utf8 to guint32), which contains the key names that +differ mapped to one or more of `NMSettingDiffResult` as a bitfield.	[element-type utf8 GLib.HashTable]

Returns

TRUE if the connections contain the same values, FALSE if they do +not

nm_connection_verify ()

gboolean
+nm_connection_verify (NMConnection *connection,
+                      GError **error);

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 NMSettingWireless +setting object's 'security' property must contain the setting name of the +NMSettingWirelessSecurity object, which must also be present in the +connection for the connection to be valid. As another example, the +NMSettingWired object's 'mac-address' property must be a validly formatted +MAC address. The returned GError contains information about which +setting and which property failed validation, and how it failed validation.

Parameters

+++++ + + + + + + + + + + + + +

connection	the NMConnection to verify
error	location to store error, or `NULL`

Returns

TRUE if the connection is valid, FALSE if it is not

nm_connection_verify_secrets ()

gboolean
+nm_connection_verify_secrets (NMConnection *connection,
+                              GError **error);

Verifies the secrets in the connection.

Parameters

+++++ + + + + + + + + + + + + +

connection	the NMConnection to verify in
error	location to store error, or `NULL`

Returns

TRUE if the secrets are valid, FALSE if they are not

Since: 1.2

nm_connection_normalize ()

gboolean
+nm_connection_normalize (NMConnection *connection,
+                         GHashTable *parameters,
+                         gboolean *modified,
+                         GError **error);

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

connection	the NMConnection to normalize
parameters	a GHashTable 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 `g_str_equal()` function. +The values are opaque and depend on the parameter name.	[allow-none][element-type utf8 gpointer]
modified	outputs whether any settings were modified.	[out][allow-none]
error	location to store error, or `NULL`. Contains the reason, +why the connection is invalid, if the function returns an error.

Returns

TRUE if the connection is valid, FALSE if it is not

nm_connection_need_secrets ()

const char *
+nm_connection_need_secrets (NMConnection *connection,
+                            GPtrArray **hints);

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.

Parameters

+++++ + + + + + + + + + + + + +

connection	the NMConnection
hints	the address of a pointer to a GPtrArray, initialized to `NULL`, which on +return points to an allocated GPtrArray containing the property names of +secrets of the NMSetting 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.	[out][element-type utf8][allow-none][transfer container]

Returns

the setting name of the NMSetting object which has invalid or +missing secrets

nm_connection_clear_secrets ()

void
+nm_connection_clear_secrets (NMConnection *connection);

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

Parameters

+++++ + + + + + +

connection

connection	the NMConnection
func	function to be called to determine whether a +specific secret should be cleared or not. If `NULL`, all secrets are cleared.	[scope call][allow-none]
user_data	caller-supplied data passed to `func` +

connection	the NMConnection
setting_name	the setting object name to which the secrets apply
secrets	a GVariant of secrets, of type `NM_VARIANT_TYPE_CONNECTION` +or `NM_VARIANT_TYPE_SETTING`
error	location to store error, or `NULL`

connection	the NMConnection
path	the D-Bus path of the connection as given by the settings service +which provides the connection

connection	the NMConnection
type	a setting name to check the connection's type against (like +`NM_SETTING_WIRELESS_SETTING_NAME` or `NM_SETTING_WIRED_SETTING_NAME`)

connection	the NMConnection instance
out_length	the length of the returned array.	[allow-none][out]

GTypeInterface `parent`;	the parent interface struct
`secrets_updated` ()	emitted when the connection's secrets are updated
`secrets_cleared` ()	emitted when the connection's secrets are cleared
`changed` ()	emitted when any change to the connection's settings occurs

NM_CONNECTION_SERIALIZE_ALL	+ serialize all properties (including secrets) +
NM_CONNECTION_SERIALIZE_WITH_NON_SECRET	+ serialize properties that are +not secrets. Since 1.32. +
NM_CONNECTION_SERIALIZE_NO_SECRETS	+ this is a deprecated alias for +`NM_CONNECTION_SERIALIZE_WITH_NON_SECRET` +. +
NM_CONNECTION_SERIALIZE_WITH_SECRETS	+ serialize all secrets. This flag is +ignored if any of `NM_CONNECTION_SERIALIZE_WITH_SECRETS_AGENT_OWNED` +, +`NM_CONNECTION_SERIALIZE_WITH_SECRETS_SYSTEM_OWNED` + or +`NM_CONNECTION_SERIALIZE_WITH_SECRETS_NOT_SAVED` + is set. Since 1.32. +
NM_CONNECTION_SERIALIZE_ONLY_SECRETS	+ a deprecated alias for +`NM_CONNECTION_SERIALIZE_WITH_SECRETS` +. +
NM_CONNECTION_SERIALIZE_WITH_SECRETS_AGENT_OWNED	+ serialize agent-owned +secrets. Since: 1.20. +
NM_CONNECTION_SERIALIZE_WITH_SECRETS_SYSTEM_OWNED	+ serialize system-owned +secrets. Since: 1.32. +
NM_CONNECTION_SERIALIZE_WITH_SECRETS_NOT_SAVED	+ serialize secrets that +are marked as never saved. Since: 1.32. +

NMConnection

Functions

Types and Values

Object Hierarchy

Description

Functions

nm_connection_add_setting ()

Parameters

nm_connection_remove_setting ()

Parameters

nm_connection_get_setting ()

Parameters

Returns

nm_connection_get_setting_by_name ()

Parameters

Returns

nm_connection_to_dbus ()

Parameters

Returns

nm_connection_replace_settings ()

Parameters

Returns

nm_connection_replace_settings_from_connection ()

Parameters

nm_connection_clear_settings ()

Parameters

nm_connection_compare ()

Parameters

Returns

nm_connection_diff ()

Parameters

Returns

nm_connection_verify ()

Parameters

Returns

nm_connection_verify_secrets ()

Parameters

Returns

nm_connection_normalize ()

Parameters

Returns

nm_connection_need_secrets ()

Parameters

Returns

nm_connection_clear_secrets ()

Parameters

nm_connection_clear_secrets_with_flags ()

Parameters

nm_connection_update_secrets ()

Parameters

Returns

nm_connection_set_path ()

Parameters

nm_connection_get_path ()

Parameters

Returns

nm_connection_get_interface_name ()

Parameters

Returns

nm_connection_is_type ()

Parameters

Returns

nm_connection_for_each_setting_value ()

Parameters

nm_connection_get_settings ()

Parameters

Returns

nm_connection_dump ()

Parameters

nm_connection_get_uuid ()

Parameters

Returns

nm_connection_get_id ()

Parameters

Returns

nm_connection_get_connection_type ()

Parameters

Returns

nm_connection_is_virtual ()

Parameters