NMSettingWired

NMSettingWired — Describes connection properties for Ethernet-based networks

Properties

gboolean auto-negotiate Read / Write
char * cloned-mac-address Read / Write
char * duplex Read / Write
char * generate-mac-address-mask Read / Write
char * mac-address Read / Write
GStrv mac-address-blacklist Read / Write
guint mtu Read / Write
char * port Read / Write
char * s390-nettype Read / Write
GHashTable * s390-options Read / Write
GStrv s390-subchannels Read / Write
guint speed Read / Write
guint wake-on-lan Read / Write
char * wake-on-lan-password Read / Write

Object Hierarchy

    GFlags
    ╰── NMSettingWiredWakeOnLan
    GObject
    ╰── NMSetting
        ╰── NMSettingWired

Description

The NMSettingWired object is a NMSetting subclass that describes properties necessary for connection to Ethernet networks.

Functions

nm_setting_wired_new ()

NMSetting *
nm_setting_wired_new (void);

Creates a new NMSettingWired object with default values.

Returns

the new empty NMSettingWired object.

[transfer full]


nm_setting_wired_get_port ()

const char *
nm_setting_wired_get_port (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “port” property of the setting


nm_setting_wired_get_speed ()

guint32
nm_setting_wired_get_speed (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “speed” property of the setting


nm_setting_wired_get_duplex ()

const char *
nm_setting_wired_get_duplex (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “duplex” property of the setting


nm_setting_wired_get_auto_negotiate ()

gboolean
nm_setting_wired_get_auto_negotiate (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “auto-negotiate” property of the setting


nm_setting_wired_get_mac_address ()

const char *
nm_setting_wired_get_mac_address (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “mac-address” property of the setting


nm_setting_wired_get_cloned_mac_address ()

const char *
nm_setting_wired_get_cloned_mac_address
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “cloned-mac-address” property of the setting


nm_setting_wired_get_generate_mac_address_mask ()

const char *
nm_setting_wired_get_generate_mac_address_mask
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “generate-mac-address-mask” property of the setting

Since: 1.4


nm_setting_wired_get_mac_address_blacklist ()

const char *const *
nm_setting_wired_get_mac_address_blacklist
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “mac-address-blacklist” property of the setting


nm_setting_wired_get_num_mac_blacklist_items ()

guint32
nm_setting_wired_get_num_mac_blacklist_items
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the number of blacklisted MAC addresses


nm_setting_wired_get_mac_blacklist_item ()

const char *
nm_setting_wired_get_mac_blacklist_item
                               (NMSettingWired *setting,
                                guint32 idx);

Parameters

setting

the NMSettingWired

 

idx

the zero-based index of the MAC address entry

 

Returns

the blacklisted MAC address string (hex-digits-and-colons notation) at index idx


nm_setting_wired_add_mac_blacklist_item ()

gboolean
nm_setting_wired_add_mac_blacklist_item
                               (NMSettingWired *setting,
                                const char *mac);

Adds a new MAC address to the “mac-address-blacklist” property.

Parameters

setting

the NMSettingWired

 

mac

the MAC address string (hex-digits-and-colons notation) to blacklist

 

Returns

TRUE if the MAC address was added; FALSE if the MAC address is invalid or was already present


nm_setting_wired_remove_mac_blacklist_item ()

void
nm_setting_wired_remove_mac_blacklist_item
                               (NMSettingWired *setting,
                                guint32 idx);

Removes the MAC address at index idx from the blacklist.

Parameters

setting

the NMSettingWired

 

idx

index number of the MAC address

 

nm_setting_wired_remove_mac_blacklist_item_by_value ()

gboolean
nm_setting_wired_remove_mac_blacklist_item_by_value
                               (NMSettingWired *setting,
                                const char *mac);

Removes the MAC address mac from the blacklist.

Parameters

setting

the NMSettingWired

 

mac

the MAC address string (hex-digits-and-colons notation) to remove from the blacklist

 

Returns

TRUE if the MAC address was found and removed; FALSE if it was not.


nm_setting_wired_clear_mac_blacklist_items ()

void
nm_setting_wired_clear_mac_blacklist_items
                               (NMSettingWired *setting);

Removes all blacklisted MAC addresses.

Parameters

setting

the NMSettingWired

 

nm_setting_wired_get_mtu ()

guint32
nm_setting_wired_get_mtu (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

 

Returns

the “mtu” property of the setting


nm_setting_wired_get_s390_subchannels ()

const char *const *
nm_setting_wired_get_s390_subchannels (NMSettingWired *setting);

Return the list of s390 subchannels that identify the device that this connection is applicable to. The connection should only be used in conjunction with that device.

Parameters

setting

the NMSettingWired

 

Returns

array of strings, each specifying one subchannel the s390 device uses to communicate to the host.

[transfer none][element-type utf8]


nm_setting_wired_get_s390_nettype ()

const char *
nm_setting_wired_get_s390_nettype (NMSettingWired *setting);

Returns the s390 device type this connection should apply to. Will be one of 'qeth', 'lcs', or 'ctc'.

Parameters

setting

the NMSettingWired

 

Returns

the s390 device type


nm_setting_wired_get_num_s390_options ()

guint32
nm_setting_wired_get_num_s390_options (NMSettingWired *setting);

Returns the number of s390-specific options that should be set for this device when it is activated. This can be used to retrieve each s390 option individually using nm_setting_wired_get_s390_option().

Parameters

setting

the NMSettingWired

 

Returns

the number of s390-specific device options


nm_setting_wired_get_s390_option ()

gboolean
nm_setting_wired_get_s390_option (NMSettingWired *setting,
                                  guint32 idx,
                                  const char **out_key,
                                  const char **out_value);

Given an index, return the value of the s390 option at that index. indexes are *not* guaranteed to be static across modifications to options done by nm_setting_wired_add_s390_option() and nm_setting_wired_remove_s390_option(), and should not be used to refer to options except for short periods of time such as during option iteration.

Parameters

setting

the NMSettingWired

 

idx

index of the desired option, from 0 to nm_setting_wired_get_num_s390_options() - 1

 

out_key

on return, the key name of the s390 specific option; this value is owned by the setting and should not be modified.

[out][transfer none]

out_value

on return, the value of the key of the s390 specific option; this value is owned by the setting and should not be modified.

[out][transfer none]

Returns

TRUE on success if the index was valid and an option was found, FALSE if the index was invalid (ie, greater than the number of options currently held by the setting)


nm_setting_wired_get_s390_option_by_key ()

const char *
nm_setting_wired_get_s390_option_by_key
                               (NMSettingWired *setting,
                                const char *key);

Returns the value associated with the s390-specific option specified by key , if it exists.

Parameters

setting

the NMSettingWired

 

key

the key for which to retrieve the value

 

Returns

the value, or NULL if the key/value pair was never added to the setting; the value is owned by the setting and must not be modified


nm_setting_wired_add_s390_option ()

gboolean
nm_setting_wired_add_s390_option (NMSettingWired *setting,
                                  const char *key,
                                  const char *value);

Add an option to the table. The option is compared to an internal list of allowed options. Key names may contain only alphanumeric characters (ie [a-zA-Z0-9]). Adding a new key replaces any existing key/value pair that may already exist.

Parameters

setting

the NMSettingWired

 

key

key name for the option

 

value

value for the option

 

Returns

TRUE if the option was valid and was added to the internal option list, FALSE if it was not.


nm_setting_wired_remove_s390_option ()

gboolean
nm_setting_wired_remove_s390_option (NMSettingWired *setting,
                                     const char *key);

Remove the s390-specific option referenced by key from the internal option list.

Parameters

setting

the NMSettingWired

 

key

key name for the option to remove

 

Returns

TRUE if the option was found and removed from the internal option list, FALSE if it was not.


nm_setting_wired_get_valid_s390_options ()

const char **
nm_setting_wired_get_valid_s390_options
                               (NMSettingWired *setting);

Returns a list of valid s390 options.

The setting argument is unused and NULL may be passed instead.

Parameters

setting

the NMSettingWired. This argument is unused and you may pass NULL.

[allow-none]

Returns

a NULL-terminated array of strings of valid s390 options.

[transfer none]


nm_setting_wired_get_wake_on_lan ()

NMSettingWiredWakeOnLan
nm_setting_wired_get_wake_on_lan (NMSettingWired *setting);

Returns the Wake-on-LAN options enabled for the connection

Parameters

setting

the NMSettingWired

 

Returns

the Wake-on-LAN options

Since: 1.2


nm_setting_wired_get_wake_on_lan_password ()

const char *
nm_setting_wired_get_wake_on_lan_password
                               (NMSettingWired *setting);

Returns the Wake-on-LAN password. This only applies to NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC.

Parameters

setting

the NMSettingWired

 

Returns

the Wake-on-LAN setting password, or NULL if there is no password.

Since: 1.2

Types and Values

NM_SETTING_WIRED_SETTING_NAME

#define NM_SETTING_WIRED_SETTING_NAME "802-3-ethernet"

enum NMSettingWiredWakeOnLan

Options for “wake-on-lan”. Note that not all options are supported by all devices.

Members

NM_SETTING_WIRED_WAKE_ON_LAN_NONE

Wake-on-LAN disabled

 

NM_SETTING_WIRED_WAKE_ON_LAN_PHY

Wake on PHY activity

 

NM_SETTING_WIRED_WAKE_ON_LAN_UNICAST

Wake on unicast messages

 

NM_SETTING_WIRED_WAKE_ON_LAN_MULTICAST

Wake on multicast messages

 

NM_SETTING_WIRED_WAKE_ON_LAN_BROADCAST

Wake on broadcast messages

 

NM_SETTING_WIRED_WAKE_ON_LAN_ARP

Wake on ARP

 

NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC

Wake on magic packet

 

NM_SETTING_WIRED_WAKE_ON_LAN_ALL

Wake on all events. This does not include the exclusive flags NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT or NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE .

 

NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT

Use the default value

 

NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE

Don't change configured settings

 

NM_SETTING_WIRED_WAKE_ON_LAN_EXCLUSIVE_FLAGS

Mask of flags that are incompatible with other flags

 

Since: 1.2


NM_SETTING_WIRED_PORT

#define NM_SETTING_WIRED_PORT                      "port"

NM_SETTING_WIRED_SPEED

#define NM_SETTING_WIRED_SPEED                     "speed"

NM_SETTING_WIRED_DUPLEX

#define NM_SETTING_WIRED_DUPLEX                    "duplex"

NM_SETTING_WIRED_AUTO_NEGOTIATE

#define NM_SETTING_WIRED_AUTO_NEGOTIATE            "auto-negotiate"

NM_SETTING_WIRED_MAC_ADDRESS

#define NM_SETTING_WIRED_MAC_ADDRESS               "mac-address"

NM_SETTING_WIRED_CLONED_MAC_ADDRESS

#define NM_SETTING_WIRED_CLONED_MAC_ADDRESS        "cloned-mac-address"

NM_SETTING_WIRED_GENERATE_MAC_ADDRESS_MASK

#define NM_SETTING_WIRED_GENERATE_MAC_ADDRESS_MASK "generate-mac-address-mask"

NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST

#define NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST     "mac-address-blacklist"

NM_SETTING_WIRED_MTU

#define NM_SETTING_WIRED_MTU                       "mtu"

NM_SETTING_WIRED_S390_SUBCHANNELS

#define NM_SETTING_WIRED_S390_SUBCHANNELS          "s390-subchannels"

NM_SETTING_WIRED_S390_NETTYPE

#define NM_SETTING_WIRED_S390_NETTYPE              "s390-nettype"

NM_SETTING_WIRED_S390_OPTIONS

#define NM_SETTING_WIRED_S390_OPTIONS              "s390-options"

NM_SETTING_WIRED_WAKE_ON_LAN

#define NM_SETTING_WIRED_WAKE_ON_LAN               "wake-on-lan"

NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD

#define NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD      "wake-on-lan-password"

NMSettingWired

typedef struct _NMSettingWired NMSettingWired;

Wired Ethernet Settings

Property Details

The “auto-negotiate” property

  “auto-negotiate”           gboolean

When TRUE, enforce auto-negotiation of speed and duplex mode. If "speed" and "duplex" properties are both specified, only that single mode will be advertised and accepted during the link auto-negotiation process: this works only for BASE-T 802.3 specifications and is useful for enforcing gigabits modes, as in these cases link negotiation is mandatory. When FALSE, "speed" and "duplex" properties should be both set or link configuration will be skipped.

Owner: NMSettingWired

Flags: Read / Write

Default value: FALSE


The “cloned-mac-address” property

  “cloned-mac-address”       char *

If specified, request that the device use this MAC address instead. This is known as MAC cloning or spoofing.

Beside explicitly specifying a MAC address, the special values "preserve", "permanent", "random" and "stable" are supported. "preserve" means not to touch the MAC address on activation. "permanent" means to use the permanent hardware address if the device has one (otherwise this is treated as "preserve"). "random" creates a random MAC address on each connect. "stable" creates a hashed MAC address based on connection.stable-id and a machine dependent key.

If unspecified, the value can be overwritten via global defaults, see manual of NetworkManager.conf. If still unspecified, it defaults to "preserve" (older versions of NetworkManager may use a different default value).

On D-Bus, this field is expressed as "assigned-mac-address" or the deprecated "cloned-mac-address".

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “duplex” property

  “duplex”                   char *

When a value is set, either "half" or "full", configures the device to use the specified duplex mode. If "auto-negotiate" is "yes" the specified duplex mode will be the only one advertised during link negotiation: this works only for BASE-T 802.3 specifications and is useful for enforcing gigabits modes, as in these cases link negotiation is mandatory. If the value is unset (the default), the link configuration will be either skipped (if "auto-negotiate" is "no", the default) or will be auto-negotiated (if "auto-negotiate" is "yes") and the local device will advertise all the supported duplex modes. Must be set together with the "speed" property if specified. Before specifying a duplex mode be sure your device supports it.

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “generate-mac-address-mask” property

  “generate-mac-address-mask” char *

With “cloned-mac-address” setting "random" or "stable", by default all bits of the MAC address are scrambled and a locally-administered, unicast MAC address is created. This property allows to specify that certain bits are fixed. Note that the least significant bit of the first MAC address will always be unset to create a unicast MAC address.

If the property is NULL, it is eligible to be overwritten by a default connection setting. If the value is still NULL or an empty string, the default is to create a locally-administered, unicast MAC address.

If the value contains one MAC address, this address is used as mask. The set bits of the mask are to be filled with the current MAC address of the device, while the unset bits are subject to randomization. Setting "FE:FF:FF:00:00:00" means to preserve the OUI of the current MAC address and only randomize the lower 3 bytes using the "random" or "stable" algorithm.

If the value contains one additional MAC address after the mask, this address is used instead of the current MAC address to fill the bits that shall not be randomized. For example, a value of "FE:FF:FF:00:00:00 68:F7:28:00:00:00" will set the OUI of the MAC address to 68:F7:28, while the lower bits are randomized. A value of "02:00:00:00:00:00 00:00:00:00:00:00" will create a fully scrambled globally-administered, burned-in MAC address.

If the value contains more than one additional MAC addresses, one of them is chosen randomly. For example, "02:00:00:00:00:00 00:00:00:00:00:00 02:00:00:00:00:00" will create a fully scrambled MAC address, randomly locally or globally administered.

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “mac-address” property

  “mac-address”              char *

If specified, this connection will only apply to the Ethernet device whose permanent MAC address matches. This property does not change the MAC address of the device (i.e. MAC spoofing).

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “mac-address-blacklist” property

  “mac-address-blacklist”    GStrv

If specified, this connection will never apply to the Ethernet device whose permanent MAC address matches an address in the list. Each MAC address is in the standard hex-digits-and-colons notation (00:11:22:33:44:55).

Owner: NMSettingWired

Flags: Read / Write


The “mtu” property

  “mtu”                      guint

If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.

Owner: NMSettingWired

Flags: Read / Write

Default value: 0


The “port” property

  “port”                     char *

Specific port type to use if the device supports multiple attachment methods. One of "tp" (Twisted Pair), "aui" (Attachment Unit Interface), "bnc" (Thin Ethernet) or "mii" (Media Independent Interface). If the device supports only one port type, this setting is ignored.

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “s390-nettype” property

  “s390-nettype”             char *

s390 network device type; one of "qeth", "lcs", or "ctc", representing the different types of virtual network devices available on s390 systems.

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL


The “s390-options” property

  “s390-options”             GHashTable *

Owner: NMSettingWired

Flags: Read / Write


The “s390-subchannels” property

  “s390-subchannels”         GStrv

Identifies specific subchannels that this network device uses for communication with z/VM or s390 host. Like the “mac-address” property for non-z/VM devices, this property can be used to ensure this connection only applies to the network device that uses these subchannels. The list should contain exactly 3 strings, and each string may only be composed of hexadecimal characters and the period (.) character.

Owner: NMSettingWired

Flags: Read / Write


The “speed” property

  “speed”                    guint

When a value greater than 0 is set, configures the device to use the specified speed. If "auto-negotiate" is "yes" the specified speed will be the only one advertised during link negotiation: this works only for BASE-T 802.3 specifications and is useful for enforcing gigabit speeds, as in this case link negotiation is mandatory. If the value is unset (0, the default), the link configuration will be either skipped (if "auto-negotiate" is "no", the default) or will be auto-negotiated (if "auto-negotiate" is "yes") and the local device will advertise all the supported speeds. In Mbit/s, ie 100 == 100Mbit/s. Must be set together with the "duplex" property when non-zero. Before specifying a speed value be sure your device supports it.

Owner: NMSettingWired

Flags: Read / Write

Default value: 0


The “wake-on-lan” property

  “wake-on-lan”              guint

The NMSettingWiredWakeOnLan options to enable. Not all devices support all options. May be any combination of NM_SETTING_WIRED_WAKE_ON_LAN_PHY, NM_SETTING_WIRED_WAKE_ON_LAN_UNICAST, NM_SETTING_WIRED_WAKE_ON_LAN_MULTICAST, NM_SETTING_WIRED_WAKE_ON_LAN_BROADCAST, NM_SETTING_WIRED_WAKE_ON_LAN_ARP, NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC or the special values NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT (to use global settings) and NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE (to disable management of Wake-on-LAN in NetworkManager).

Owner: NMSettingWired

Flags: Read / Write

Default value: 1

Since: 1.2


The “wake-on-lan-password” property

  “wake-on-lan-password”     char *

If specified, the password used with magic-packet-based Wake-on-LAN, represented as an Ethernet MAC address. If NULL, no password will be required.

Owner: NMSettingWired

Flags: Read / Write

Default value: NULL

Since: 1.2