NMSettingConnection: libnm Reference Manual

## NMSettingConnection NMSettingConnection — Describes general connection properties |

## Functions

NMSetting * | nm_setting_connection_new ()
const char * | nm_setting_connection_get_id ()
const char * | nm_setting_connection_get_uuid ()
const char * | nm_setting_connection_get_stable_id ()
const char * | nm_setting_connection_get_interface_name ()
const char * | nm_setting_connection_get_connection_type ()
gboolean | nm_setting_connection_get_autoconnect ()
int | nm_setting_connection_get_autoconnect_priority ()
int | nm_setting_connection_get_autoconnect_retries ()
NMConnectionMultiConnect | nm_setting_connection_get_multi_connect ()
guint64 | nm_setting_connection_get_timestamp ()
gboolean | nm_setting_connection_get_read_only ()
guint32 | nm_setting_connection_get_num_permissions ()
gboolean | nm_setting_connection_get_permission ()
const char * | nm_setting_connection_get_zone ()
gboolean | nm_setting_connection_permissions_user_allowed ()
gboolean | nm_setting_connection_add_permission ()
void | nm_setting_connection_remove_permission ()
gboolean | nm_setting_connection_remove_permission_by_value ()
const char * | nm_setting_connection_get_master ()
gboolean | nm_setting_connection_is_slave_type ()
const char * | nm_setting_connection_get_slave_type ()
NMSettingConnectionAutoconnectSlaves | nm_setting_connection_get_autoconnect_slaves ()
guint32 | nm_setting_connection_get_num_secondaries ()
const char * | nm_setting_connection_get_secondary ()
gboolean | nm_setting_connection_add_secondary ()
void | nm_setting_connection_remove_secondary ()
gboolean | nm_setting_connection_remove_secondary_by_value ()
guint32 | nm_setting_connection_get_gateway_ping_timeout ()
NMMetered | nm_setting_connection_get_metered ()
NMSettingConnectionLldp | nm_setting_connection_get_lldp ()
int | nm_setting_connection_get_auth_retries ()
NMSettingConnectionMdns | nm_setting_connection_get_mdns ()
NMSettingConnectionLlmnr | nm_setting_connection_get_llmnr ()
gint32 | nm_setting_connection_get_wait_device_timeout ()
const char * | nm_setting_connection_get_mud_url ()

## Types and Values

#define | NM_SETTING_CONNECTION_SETTING_NAME
#define | NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MIN
#define | NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MAX
#define | NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_DEFAULT
#define | NM_SETTING_CONNECTION_ID
#define | NM_SETTING_CONNECTION_UUID
#define | NM_SETTING_CONNECTION_STABLE_ID
#define | NM_SETTING_CONNECTION_INTERFACE_NAME
#define | NM_SETTING_CONNECTION_TYPE
#define | NM_SETTING_CONNECTION_AUTOCONNECT
#define | NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY
#define | NM_SETTING_CONNECTION_AUTOCONNECT_RETRIES
#define | NM_SETTING_CONNECTION_MULTI_CONNECT
#define | NM_SETTING_CONNECTION_TIMESTAMP
#define | NM_SETTING_CONNECTION_READ_ONLY
#define | NM_SETTING_CONNECTION_PERMISSIONS
#define | NM_SETTING_CONNECTION_ZONE
#define | NM_SETTING_CONNECTION_MASTER
#define | NM_SETTING_CONNECTION_SLAVE_TYPE
#define | NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES
#define | NM_SETTING_CONNECTION_SECONDARIES
#define | NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT
#define | NM_SETTING_CONNECTION_METERED
#define | NM_SETTING_CONNECTION_LLDP
#define | NM_SETTING_CONNECTION_AUTH_RETRIES
#define | NM_SETTING_CONNECTION_MDNS
#define | NM_SETTING_CONNECTION_LLMNR
#define | NM_SETTING_CONNECTION_WAIT_DEVICE_TIMEOUT
#define | NM_SETTING_CONNECTION_MUD_URL
enum | NMSettingConnectionAutoconnectSlaves
enum | NMSettingConnectionLldp
enum | NMSettingConnectionMdns
enum | NMSettingConnectionLlmnr

## Object Hierarchy

        GEnum
        ├── NMSettingConnectionAutoconnectSlaves
        ├── NMSettingConnectionLldp
        ├── NMSettingConnectionLlmnr
        ╰── NMSettingConnectionMdns

## Description

The NMSettingConnection object is a NMSetting subclass that describes properties that apply to all NMConnection objects, regardless of what type of network connection they describe. Each NMConnection object must contain a NMSettingConnection setting.

## Functions

### nm_setting_connection_new ()

    NMSetting *
    nm_setting_connection_new (void);

Creates a new NMSettingConnection object with default values.

#### Returns

the new empty NMSettingConnection object

### nm_setting_connection_get_id ()

    const char *
    nm_setting_connection_get_id (NMSettingConnection *setting);

Returns the “id” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection ID

### nm_setting_connection_get_uuid ()

    const char *
    nm_setting_connection_get_uuid (NMSettingConnection *setting);

Returns the “uuid” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection UUID

### nm_setting_connection_get_stable_id ()

    const char *
    nm_setting_connection_get_stable_id (NMSettingConnection *setting);

Returns the “stable_id” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the stable-id for the connection

Since: 1.4

### nm_setting_connection_get_interface_name ()

    const char *
    nm_setting_connection_get_interface_name
                                   (NMSettingConnection *setting);

Returns the “interface-name” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection's interface name

### nm_setting_connection_get_connection_type ()

    const char *
    nm_setting_connection_get_connection_type
                                   (NMSettingConnection *setting);

Returns the “type” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection type

### nm_setting_connection_get_autoconnect ()

    gboolean
    nm_setting_connection_get_autoconnect (NMSettingConnection *setting);

Returns the “autoconnect” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection's autoconnect behavior

### nm_setting_connection_get_autoconnect_priority ()

    int
    nm_setting_connection_get_autoconnect_priority
                                   (NMSettingConnection *setting);

Returns the “autoconnect-priority” property of the connection. The higher number, the higher priority.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection's autoconnect priority

### nm_setting_connection_get_autoconnect_retries ()

    int
    nm_setting_connection_get_autoconnect_retries
                                   (NMSettingConnection *setting);

Returns the “autoconnect-retries” property of the connection. Zero means infinite, -1 means the global default value.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection's autoconnect retries

Since: 1.6

### nm_setting_connection_get_multi_connect ()

    NMConnectionMultiConnect
    nm_setting_connection_get_multi_connect
                                   (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the “multi-connect” property of the connection.

Since: 1.14

### nm_setting_connection_get_timestamp ()

    guint64
    nm_setting_connection_get_timestamp (NMSettingConnection *setting);

Returns the “timestamp” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the connection's timestamp

### nm_setting_connection_get_read_only ()

    gboolean
    nm_setting_connection_get_read_only (NMSettingConnection *setting);

Returns the “read-only” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

`TRUE` if the connection is read-only, `FALSE` if it is not

### nm_setting_connection_get_num_permissions ()

    guint32
    nm_setting_connection_get_num_permissions
                                   (NMSettingConnection *setting);

Returns the number of entries in the “permissions” property of this setting.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the number of permissions entries

### nm_setting_connection_get_permission ()

    gboolean
    nm_setting_connection_get_permission (NMSettingConnection *setting,
                                          guint32 idx,
                                          const char **out_ptype,
                                          const char **out_pitem,
                                          const char **out_detail);

Retrieve one of the entries of the “permissions” property of this setting.

#### Parameters

setting | the NMSettingConnection |
idx | the zero-based index of the permissions entry |
out_ptype | on return, the permission type. This is currently always "user", unless the entry is invalid, in which case it returns "invalid". |
out_pitem | on return, the permission item (formatted according to `ptype` , see “permissions” for more detail |
out_detail | on return, the permission detail (at this time, always `NULL`) |

#### Returns

`TRUE` if a permission was returned, `FALSE` if `idx` was invalid

### nm_setting_connection_get_zone ()

    const char *
    nm_setting_connection_get_zone (NMSettingConnection *setting);

Returns the “zone” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the trust level of a connection

### nm_setting_connection_permissions_user_allowed ()

    gboolean
    nm_setting_connection_permissions_user_allowed
                                   (NMSettingConnection *setting,
                                    const char *uname);

Checks whether the given username is allowed to view/access this connection.

#### Parameters

setting | the NMSettingConnection |
uname | the user name to check permissions for |

#### Returns

`TRUE` if the requested user is allowed to view this connection, `FALSE` if the given user is not allowed to view this connection

### nm_setting_connection_add_permission ()

    gboolean
    nm_setting_connection_add_permission (NMSettingConnection *setting,
                                          const char *ptype,
                                          const char *pitem,
                                          const char *detail);

Adds a permission to the connection's permission list. At this time, only the "user" permission type is supported, and `pitem` must be a username. See “permissions”: for more details.

#### Parameters

setting | the NMSettingConnection |
ptype | the permission type; at this time only "user" is supported |
pitem | the permission item formatted as required for `ptype` |
detail | unused at this time; must be `NULL`. | [allow-none]

#### Returns

`TRUE` if the permission was unique and was successfully added to the list, `FALSE` if `ptype` or `pitem` was invalid. If the permission was already present in the list, it will not be added a second time but `TRUE` will be returned. Note that before 1.28, in this case `FALSE` would be returned.

### nm_setting_connection_remove_permission ()

    void
    nm_setting_connection_remove_permission
                                   (NMSettingConnection *setting,
                                    guint32 idx);

Removes the permission at index `idx` from the connection.

#### Parameters

setting | the NMSettingConnection |
idx | the zero-based index of the permission to remove |

### nm_setting_connection_remove_permission_by_value ()

    gboolean
    nm_setting_connection_remove_permission_by_value
                                   (NMSettingConnection *setting,
                                    const char *ptype,
                                    const char *pitem,
                                    const char *detail);

Removes the permission from the connection. At this time, only the "user" permission type is supported, and `pitem` must be a username. See “permissions”: for more details.

#### Parameters

setting | the NMSettingConnection |
ptype | the permission type; at this time only "user" is supported |
pitem | the permission item formatted as required for `ptype` |
detail | unused at this time; must be `NULL`. | [allow-none]

#### Returns

`TRUE` if the permission was found and removed; `FALSE` if it was not.

### nm_setting_connection_get_master ()

    const char *
    nm_setting_connection_get_master (NMSettingConnection *setting);

Returns the “master” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

interface name of the master device or UUID of the master connection.

### nm_setting_connection_is_slave_type ()

    gboolean
    nm_setting_connection_is_slave_type (NMSettingConnection *setting,
                                         const char *type);

#### Parameters

setting | the NMSettingConnection |
type | the setting name (ie NM_SETTING_BOND_SETTING_NAME) to be matched against `setting` 's slave type |

#### Returns

`TRUE` if connection is of the given slave `type`

### nm_setting_connection_get_slave_type ()

    const char *
    nm_setting_connection_get_slave_type (NMSettingConnection *setting);

Returns the “slave-type” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the type of slave this connection is, if any

### nm_setting_connection_get_autoconnect_slaves ()

    NMSettingConnectionAutoconnectSlaves
    nm_setting_connection_get_autoconnect_slaves
                                   (NMSettingConnection *setting);

Returns the “autoconnect-slaves” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

whether slaves of the connection should be activated together with the connection.

Since: 1.2

### nm_setting_connection_get_num_secondaries ()

    guint32
    nm_setting_connection_get_num_secondaries
                                   (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the number of configured secondary connection UUIDs

### nm_setting_connection_get_secondary ()

    const char *
    nm_setting_connection_get_secondary (NMSettingConnection *setting,
                                         guint32 idx);

#### Parameters

setting | the NMSettingConnection |
idx | the zero-based index of the secondary connection UUID entry. Access one past the length of secondaries is ok and will return `NULL`. Otherwise, it is a user error. |

#### Returns

the secondary connection UUID at index `idx` or `NULL` if `idx` is the number of secondaries.

### nm_setting_connection_add_secondary ()

    gboolean
    nm_setting_connection_add_secondary (NMSettingConnection *setting,
                                         const char *sec_uuid);

Adds a new secondary connection UUID to the setting.

#### Parameters

setting | the NMSettingConnection |
sec_uuid | the secondary connection UUID to add |

#### Returns

`TRUE` if the secondary connection UUID was added; `FALSE` if the UUID was already present

### nm_setting_connection_remove_secondary ()

    void
    nm_setting_connection_remove_secondary
                                   (NMSettingConnection *setting,
                                    guint32 idx);

Removes the secondary connection UUID at index `idx` .

#### Parameters

setting | the NMSettingConnection |
idx | index number of the secondary connection UUID |

### nm_setting_connection_remove_secondary_by_value ()

    gboolean
    nm_setting_connection_remove_secondary_by_value
                                   (NMSettingConnection *setting,
                                    const char *sec_uuid);

Removes the secondary connection UUID `sec_uuid` .

#### Parameters

setting | the NMSettingConnection |
sec_uuid | the secondary connection UUID to remove |

#### Returns

`TRUE` if the secondary connection UUID was found and removed; `FALSE` if it was not.

### nm_setting_connection_get_gateway_ping_timeout ()

    guint32
    nm_setting_connection_get_gateway_ping_timeout
                                   (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the value contained in the “gateway-ping-timeout” property.

### nm_setting_connection_get_metered ()

    NMMetered
    nm_setting_connection_get_metered (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the “metered” property of the setting.

Since: 1.2

### nm_setting_connection_get_lldp ()

    NMSettingConnectionLldp
    nm_setting_connection_get_lldp (NMSettingConnection *setting);

Returns the “lldp” property of the connection.

#### Parameters

setting | the NMSettingConnection |

#### Returns

a `NMSettingConnectionLldp` which indicates whether LLDP must be enabled for the connection.

Since: 1.2

### nm_setting_connection_get_auth_retries ()

    int
    nm_setting_connection_get_auth_retries
                                   (NMSettingConnection *setting);

Returns the value contained in the “auth-retries” property.

#### Parameters

setting | the NMSettingConnection |

#### Returns

the configured authentication retries. Zero means infinity and -1 means a global default value.

Since: 1.10

### nm_setting_connection_get_mdns ()

    NMSettingConnectionMdns
    nm_setting_connection_get_mdns (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the “mdns” property of the setting.

Since: 1.12

### nm_setting_connection_get_llmnr ()

    NMSettingConnectionLlmnr
    nm_setting_connection_get_llmnr (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the “llmnr” property of the setting.

Since: 1.14

### nm_setting_connection_get_wait_device_timeout ()

    gint32
    nm_setting_connection_get_wait_device_timeout
                                   (NMSettingConnection *setting);

#### Parameters

setting | the NMSettingConnection |

#### Returns

the `NM_SETTING_CONNECTION_WAIT_DEVICE_TIMEOUT` property with the timeout in milliseconds. -1 is the default.

Since: 1.20

### nm_setting_connection_get_mud_url ()

    const char *
    nm_setting_connection_get_mud_url (NMSettingConnection *setting);

Returns the value contained in the “mud-url” property.

#### Parameters

setting | the NMSettingConnection |

Since: 1.26

## Types and Values

### NM_SETTING_CONNECTION_SETTING_NAME

    #define NM_SETTING_CONNECTION_SETTING_NAME "connection"

### NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MIN

    #define NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MIN     -999

### NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MAX

    #define NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_MAX     999

### NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_DEFAULT

    #define NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY_DEFAULT 0

### NM_SETTING_CONNECTION_ID

    #define NM_SETTING_CONNECTION_ID                   "id"

### NM_SETTING_CONNECTION_UUID

    #define NM_SETTING_CONNECTION_UUID                 "uuid"

### NM_SETTING_CONNECTION_STABLE_ID

    #define NM_SETTING_CONNECTION_STABLE_ID            "stable-id"

### NM_SETTING_CONNECTION_INTERFACE_NAME

    #define NM_SETTING_CONNECTION_INTERFACE_NAME       "interface-name"

### NM_SETTING_CONNECTION_TYPE

    #define NM_SETTING_CONNECTION_TYPE                 "type"

### NM_SETTING_CONNECTION_AUTOCONNECT

    #define NM_SETTING_CONNECTION_AUTOCONNECT          "autoconnect"

### NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY

    #define NM_SETTING_CONNECTION_AUTOCONNECT_PRIORITY "autoconnect-priority"

### NM_SETTING_CONNECTION_AUTOCONNECT_RETRIES

    #define NM_SETTING_CONNECTION_AUTOCONNECT_RETRIES  "autoconnect-retries"

### NM_SETTING_CONNECTION_MULTI_CONNECT

    #define NM_SETTING_CONNECTION_MULTI_CONNECT        "multi-connect"

### NM_SETTING_CONNECTION_TIMESTAMP

    #define NM_SETTING_CONNECTION_TIMESTAMP            "timestamp"

### NM_SETTING_CONNECTION_READ_ONLY

    #define NM_SETTING_CONNECTION_READ_ONLY            "read-only"

### NM_SETTING_CONNECTION_PERMISSIONS

    #define NM_SETTING_CONNECTION_PERMISSIONS          "permissions"

### NM_SETTING_CONNECTION_ZONE

    #define NM_SETTING_CONNECTION_ZONE                 "zone"

### NM_SETTING_CONNECTION_MASTER

    #define NM_SETTING_CONNECTION_MASTER               "master"

### NM_SETTING_CONNECTION_SLAVE_TYPE

    #define NM_SETTING_CONNECTION_SLAVE_TYPE           "slave-type"

### NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES

    #define NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES   "autoconnect-slaves"

### NM_SETTING_CONNECTION_SECONDARIES

    #define NM_SETTING_CONNECTION_SECONDARIES          "secondaries"

### NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT

    #define NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT "gateway-ping-timeout"

### NM_SETTING_CONNECTION_METERED

    #define NM_SETTING_CONNECTION_METERED              "metered"

### NM_SETTING_CONNECTION_LLDP

    #define NM_SETTING_CONNECTION_LLDP                 "lldp"

### NM_SETTING_CONNECTION_AUTH_RETRIES

    #define NM_SETTING_CONNECTION_AUTH_RETRIES         "auth-retries"

### NM_SETTING_CONNECTION_MDNS

    #define NM_SETTING_CONNECTION_MDNS                 "mdns"

### NM_SETTING_CONNECTION_LLMNR

    #define NM_SETTING_CONNECTION_LLMNR                "llmnr"

### NM_SETTING_CONNECTION_WAIT_DEVICE_TIMEOUT

    #define NM_SETTING_CONNECTION_WAIT_DEVICE_TIMEOUT  "wait-device-timeout"

### NM_SETTING_CONNECTION_MUD_URL

    #define NM_SETTING_CONNECTION_MUD_URL              "mud-url"

### enum NMSettingConnectionAutoconnectSlaves

NMSettingConnectionAutoconnectSlaves values indicate whether slave connections should be activated when master is activated.

#### Members

NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES_DEFAULT | default value |
NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES_NO | slaves are not brought up when master is activated |
NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES_YES | slaves are brought up when master is activated |

### enum NMSettingConnectionLldp

NMSettingConnectionLldp values indicate whether LLDP should be enabled.

#### Members

NM_SETTING_CONNECTION_LLDP_DEFAULT | default value |
NM_SETTING_CONNECTION_LLDP_DISABLE | disable LLDP |
NM_SETTING_CONNECTION_LLDP_ENABLE_RX | enable reception of LLDP frames |

### enum NMSettingConnectionMdns

NMSettingConnectionMdns values indicate whether mDNS should be enabled.

#### Members

NM_SETTING_CONNECTION_MDNS_DEFAULT | default value |
NM_SETTING_CONNECTION_MDNS_NO | disable mDNS |
NM_SETTING_CONNECTION_MDNS_RESOLVE | support only resolving, do not register hostname |
NM_SETTING_CONNECTION_MDNS_YES | enable mDNS |

Since: 1.12

### enum NMSettingConnectionLlmnr

NMSettingConnectionLlmnr values indicate whether LLMNR should be enabled.

#### Members

NM_SETTING_CONNECTION_LLMNR_DEFAULT | default value |
NM_SETTING_CONNECTION_LLMNR_NO | disable LLMNR |
NM_SETTING_CONNECTION_LLMNR_RESOLVE | support only resolving, do not register hostname |
NM_SETTING_CONNECTION_LLMNR_YES | enable LLMNR |

Since: 1.14