Top |
Functions
Properties
gint | auth-retries | Read / Write / Construct |
gboolean | autoconnect | Read / Write / Construct |
gint | autoconnect-priority | Read / Write / Construct |
gint | autoconnect-retries | Read / Write / Construct |
NMSettingConnectionAutoconnectSlaves | autoconnect-slaves | Read / Write / Construct |
guint | gateway-ping-timeout | Read / Write / Construct |
gchar * | id | Read / Write |
gchar * | interface-name | Read / Write |
gint | lldp | Read / Write / Construct |
gchar * | master | Read / Write |
gint | mdns | Read / Write |
NMMetered | metered | Read / Write |
GStrv | permissions | Read / Write |
gboolean | read-only | Read / Write / Construct |
GStrv | secondaries | Read / Write |
gchar * | slave-type | Read / Write |
gchar * | stable-id | Read / Write |
guint64 | timestamp | Read / Write / Construct |
gchar * | type | Read / Write |
gchar * | uuid | Read / Write |
gchar * | zone | Read / Write / Construct |
Types and Values
Object Hierarchy
GEnum ├── NMSettingConnectionAutoconnectSlaves ├── NMSettingConnectionLldp ╰── NMSettingConnectionMdns GObject ╰── NMSetting ╰── NMSettingConnection
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.
nm_setting_connection_get_id ()
const char *
nm_setting_connection_get_id (NMSettingConnection *setting
);
Returns the “id” property of the connection.
nm_setting_connection_get_uuid ()
const char *
nm_setting_connection_get_uuid (NMSettingConnection *setting
);
Returns the “uuid” property of the connection.
nm_setting_connection_get_stable_id ()
const char *
nm_setting_connection_get_stable_id (NMSettingConnection *setting
);
Returns the “stable_id” property of 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.
nm_setting_connection_get_connection_type ()
const char *
nm_setting_connection_get_connection_type
(NMSettingConnection *setting
);
Returns the “type” property of the connection.
nm_setting_connection_get_autoconnect ()
gboolean
nm_setting_connection_get_autoconnect (NMSettingConnection *setting
);
Returns the “autoconnect” property of the connection.
nm_setting_connection_get_autoconnect_priority ()
gint
nm_setting_connection_get_autoconnect_priority
(NMSettingConnection *setting
);
Returns the “autoconnect-priority” property of the connection. The higher number, the higher priority.
nm_setting_connection_get_autoconnect_retries ()
gint
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.
Since: 1.6
nm_setting_connection_get_timestamp ()
guint64
nm_setting_connection_get_timestamp (NMSettingConnection *setting
);
Returns the “timestamp” property of the connection.
nm_setting_connection_get_read_only ()
gboolean
nm_setting_connection_get_read_only (NMSettingConnection *setting
);
Returns the “read-only” property of the connection.
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.
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 |
||
idx |
the zero-based index of the permissions entry |
|
out_ptype |
on return, the permission type (at this time, always "user") |
|
out_pitem |
on return, the permission item (formatted accoring to |
|
out_detail |
on return, the permission detail (at this time, always |
nm_setting_connection_get_zone ()
const char *
nm_setting_connection_get_zone (NMSettingConnection *setting
);
Returns the “zone” property of the 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.
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 |
||
ptype |
the permission type; at this time only "user" is supported |
|
pitem |
the permission item formatted as required for |
|
detail |
unused at this time; must be |
[allow-none] |
nm_setting_connection_remove_permission ()
void nm_setting_connection_remove_permission (NMSettingConnection *setting
,guint32 idx
);
Removes the permission at index idx
from the connection.
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 |
||
ptype |
the permission type; at this time only "user" is supported |
|
pitem |
the permission item formatted as required for |
|
detail |
unused at this time; must be |
[allow-none] |
nm_setting_connection_get_master ()
const char *
nm_setting_connection_get_master (NMSettingConnection *setting
);
Returns the “master” property of the connection.
nm_setting_connection_is_slave_type ()
gboolean nm_setting_connection_is_slave_type (NMSettingConnection *setting
,const char *type
);
Parameters
setting |
||
type |
the setting name (ie NM_SETTING_BOND_SETTING_NAME) to be matched
against |
nm_setting_connection_get_slave_type ()
const char *
nm_setting_connection_get_slave_type (NMSettingConnection *setting
);
Returns the “slave-type” property of the connection.
nm_setting_connection_get_autoconnect_slaves ()
NMSettingConnectionAutoconnectSlaves
nm_setting_connection_get_autoconnect_slaves
(NMSettingConnection *setting
);
Returns the “autoconnect-slaves” property of the connection.
Since: 1.2
nm_setting_connection_get_num_secondaries ()
guint32
nm_setting_connection_get_num_secondaries
(NMSettingConnection *setting
);
nm_setting_connection_get_secondary ()
const char * nm_setting_connection_get_secondary (NMSettingConnection *setting
,guint32 idx
);
nm_setting_connection_add_secondary ()
gboolean nm_setting_connection_add_secondary (NMSettingConnection *setting
,const char *sec_uuid
);
Adds a new secondary connetion UUID to the setting.
nm_setting_connection_remove_secondary ()
void nm_setting_connection_remove_secondary (NMSettingConnection *setting
,guint32 idx
);
Removes the secondary coonnection UUID at index idx
.
nm_setting_connection_remove_secondary_by_value ()
gboolean nm_setting_connection_remove_secondary_by_value (NMSettingConnection *setting
,const char *sec_uuid
);
Removes the secondary coonnection UUID sec_uuid
.
nm_setting_connection_get_gateway_ping_timeout ()
guint32
nm_setting_connection_get_gateway_ping_timeout
(NMSettingConnection *setting
);
nm_setting_connection_get_metered ()
NMMetered
nm_setting_connection_get_metered (NMSettingConnection *setting
);
Since: 1.2
nm_setting_connection_get_lldp ()
NMSettingConnectionLldp
nm_setting_connection_get_lldp (NMSettingConnection *setting
);
Returns the “lldp” property of the connection.
Since: 1.2
nm_setting_connection_get_auth_retries ()
gint
nm_setting_connection_get_auth_retries
(NMSettingConnection *setting
);
Returns the value contained in the “auth-retries” property.
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
);
Since: 1.10.14
Types and Values
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_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_AUTOCONNECT_SLAVES
#define NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES "autoconnect-slaves"
NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT
#define NM_SETTING_CONNECTION_GATEWAY_PING_TIMEOUT "gateway-ping-timeout"
enum NMSettingConnectionAutoconnectSlaves
NMSettingConnectionAutoconnectSlaves values indicate whether slave connections should be activated when master is activated.
enum NMSettingConnectionLldp
NMSettingConnectionLldp values indicate whether LLDP should be enabled.
enum NMSettingConnectionMdns
NMSettingConnectionMdns values indicate whether mDNS should be enabled.
Since: 1.10.14
Property Details
The “auth-retries”
property
“auth-retries” gint
The number of retries for the authentication. Zero means to try indefinitely; -1 means to use a global default. If the global default is not set, the authentication retries for 3 times before failing the connection.
Currently this only applies to 802-1x authentication.
Flags: Read / Write / Construct
Allowed values: >= -1
Default value: -1
Since: 1.10
The “autoconnect”
property
“autoconnect” gboolean
Whether or not the connection should be automatically connected by
NetworkManager when the resources for the connection are available.
TRUE
to automatically activate the connection, FALSE
to require manual
intervention to activate the connection.
Flags: Read / Write / Construct
Default value: TRUE
The “autoconnect-priority”
property
“autoconnect-priority” gint
The autoconnect priority. If the connection is set to autoconnect, connections with higher priority will be preferred. Defaults to 0. The higher number means higher priority.
Flags: Read / Write / Construct
Allowed values: [-999,999]
Default value: 0
The “autoconnect-retries”
property
“autoconnect-retries” gint
The number of times a connection should be tried when autoactivating before giving up. Zero means forever, -1 means the global default (4 times if not overridden). Setting this to 1 means to try activation only once before blocking autoconnect. Note that after a timeout, NetworkManager will try to autoconnect again.
Flags: Read / Write / Construct
Allowed values: >= -1
Default value: -1
The “autoconnect-slaves”
property
“autoconnect-slaves” NMSettingConnectionAutoconnectSlaves
Whether or not slaves of this connection should be automatically brought up when NetworkManager activates this connection. This only has a real effect for master connections. The permitted values are: 0: leave slave connections untouched, 1: activate all the slave connections with this connection, -1: default. If -1 (default) is set, global connection.autoconnect-slaves is read to determine the real value. If it is default as well, this fallbacks to 0.
Flags: Read / Write / Construct
Default value: NM_SETTING_CONNECTION_AUTOCONNECT_SLAVES_DEFAULT
Since: 1.2
The “gateway-ping-timeout”
property
“gateway-ping-timeout” guint
If greater than zero, delay success of IP addressing until either the timeout is reached, or an IP gateway replies to a ping.
Flags: Read / Write / Construct
Allowed values: <= 600
Default value: 0
The “id”
property
“id” gchar *
A human readable unique identifier for the connection, like "Work Wi-Fi" or "T-Mobile 3G".
Flags: Read / Write
Default value: NULL
The “interface-name”
property
“interface-name” gchar *
The name of the network interface this connection is bound to. If not set, then the connection can be attached to any interface of the appropriate type (subject to restrictions imposed by other settings).
For software devices this specifies the name of the created device.
For connection types where interface names cannot easily be made persistent (e.g. mobile broadband or USB Ethernet), this property should not be used. Setting this property restricts the interfaces a connection can be used with, and if interface names change or are reordered the connection may be applied to the wrong interface.
Flags: Read / Write
Default value: NULL
The “lldp”
property
“lldp” gint
Whether LLDP is enabled for the connection.
Flags: Read / Write / Construct
Default value: -1
Since: 1.2
The “master”
property
“master” gchar *
Interface name of the master device or UUID of the master connection.
Flags: Read / Write
Default value: NULL
The “mdns”
property
“mdns” gint
Whether mDNS is enabled for the connection.
The permitted values are: yes: register hostname and resolving for the connection, no: disable mDNS for the interface, resolve: do not register hostname but allow resolving of mDNS host names. When updating this property on a currently activated connection, the change takes effect immediately.
This feature requires a plugin which supports mDNS. One such plugin is dns-systemd-resolved.
Flags: Read / Write
Default value: -1
Since: 1.10.14
The “metered”
property
“metered” NMMetered
Whether the connection is metered.
When updating this property on a currently activated connection, the change takes effect immediately.
Flags: Read / Write
Default value: NM_METERED_UNKNOWN
Since: 1.2
The “permissions”
property
“permissions” GStrv
An array of strings defining what access a given user has to this
connection. If this is NULL
or empty, all users are allowed to access
this connection; otherwise users are allowed if and only if they are in
this list. When this is not empty, the connection can be active only when
one of the specified users is logged into an active session. Each entry
is of the form "[type]:[id]:[reserved]"; for example, "user:dcbw:blah".
At this time only the "user" [type] is allowed. Any other values are ignored and reserved for future use. [id] is the username that this permission refers to, which may not contain the ":" character. Any [reserved] information present must be ignored and is reserved for future use. All of [type], [id], and [reserved] must be valid UTF-8.
Flags: Read / Write
The “read-only”
property
“read-only” gboolean
FALSE
if the connection can be modified using the provided settings
service's D-Bus interface with the right privileges, or TRUE
if the
connection is read-only and cannot be modified.
Flags: Read / Write / Construct
Default value: FALSE
The “secondaries”
property
“secondaries” GStrv
List of connection UUIDs that should be activated when the base connection itself is activated. Currently only VPN connections are supported.
Flags: Read / Write
The “slave-type”
property
“slave-type” gchar *
Setting name of the device type of this slave's master connection (eg,
NM_SETTING_BOND_SETTING_NAME
), or NULL
if this connection is not a
slave.
Flags: Read / Write
Default value: NULL
The “stable-id”
property
“stable-id” gchar *
Token to generate stable IDs for the connection.
The stable-id is used for generating IPv6 stable private addresses with ipv6.addr-gen-mode=stable-privacy. It is also used to seed the generated cloned MAC address for ethernet.cloned-mac-address=stable and wifi.cloned-mac-address=stable. Note that also the interface name of the activating connection and a per-host secret key is included into the address generation so that the same stable-id on different hosts/devices yields different addresses.
If the value is unset, an ID unique for the connection is used. Specifying a stable-id allows multiple connections to generate the same addresses. Another use is to generate IDs at runtime via dynamic substitutions.
The '$' character is treated special to perform dynamic substitutions at runtime. Currently supported are "${CONNECTION}", "${BOOT}", "${RANDOM}". These effectively create unique IDs per-connection, per-boot, or every time. Any unrecognized patterns following '$' are treated verbatim, however are reserved for future use. You are thus advised to avoid '$' or escape it as "$$". For example, set it to "${CONNECTION}/${BOOT}" to create a unique id for this connection that changes with every reboot.
Note that two connections only use the same effective id if their stable-id is also identical before performing dynamic substitutions.
Flags: Read / Write
Default value: NULL
Since: 1.4
The “timestamp”
property
“timestamp” guint64
The time, in seconds since the Unix Epoch, that the connection was last _successfully_ fully activated.
NetworkManager updates the connection timestamp periodically when the connection is active to ensure that an active connection has the latest timestamp. The property is only meant for reading (changes to this property will not be preserved).
Flags: Read / Write / Construct
Default value: 0
The “type”
property
“type” gchar *
Base type of the connection. For hardware-dependent connections, should contain the setting name of the hardware-type specific setting (ie, "802-3-ethernet" or "802-11-wireless" or "bluetooth", etc), and for non-hardware dependent connections like VPN or otherwise, should contain the setting name of that setting type (ie, "vpn" or "bridge", etc).
Flags: Read / Write
Default value: NULL
The “uuid”
property
“uuid” gchar *
A universally unique identifier for the connection, for example generated with libuuid. It should be assigned when the connection is created, and never changed as long as the connection still applies to the same network. For example, it should not be changed when the “id” property or NMSettingIP4Config changes, but might need to be re-created when the Wi-Fi SSID, mobile broadband network provider, or “type” property changes.
The UUID must be in the format "2815492f-7e56-435e-b2e9-246bd7cdc664"
(ie, contains only hexadecimal characters and "-"). A suitable UUID may
be generated by nm_utils_uuid_generate()
or
nm_utils_uuid_generate_from_string()
.
Flags: Read / Write
Default value: NULL
The “zone”
property
“zone” gchar *
The trust level of a the connection. Free form case-insensitive string
(for example "Home", "Work", "Public"). NULL
or unspecified zone means
the connection will be placed in the default zone as defined by the
firewall.
When updating this property on a currently activated connection, the change takes effect immediately.
Flags: Read / Write / Construct
Default value: NULL