NMSettingWired

NMSettingWired — Describes connection properties for Ethernet-based networks

Synopsis

#define             NM_SETTING_WIRED_SETTING_NAME
enum                NMSettingWiredWakeOnLan;
#define             NM_SETTING_WIRED_PORT
#define             NM_SETTING_WIRED_SPEED
#define             NM_SETTING_WIRED_DUPLEX
#define             NM_SETTING_WIRED_AUTO_NEGOTIATE
#define             NM_SETTING_WIRED_MAC_ADDRESS
#define             NM_SETTING_WIRED_CLONED_MAC_ADDRESS
#define             NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST
#define             NM_SETTING_WIRED_MTU
#define             NM_SETTING_WIRED_S390_SUBCHANNELS
#define             NM_SETTING_WIRED_S390_NETTYPE
#define             NM_SETTING_WIRED_S390_OPTIONS
#define             NM_SETTING_WIRED_WAKE_ON_LAN
#define             NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD
                    NMSettingWired;
                    NMSettingWiredClass;
NMSetting *         nm_setting_wired_new                (void);
const char *        nm_setting_wired_get_port           (NMSettingWired *setting);
guint32             nm_setting_wired_get_speed          (NMSettingWired *setting);
const char *        nm_setting_wired_get_duplex         (NMSettingWired *setting);
gboolean            nm_setting_wired_get_auto_negotiate (NMSettingWired *setting);
const char *        nm_setting_wired_get_mac_address    (NMSettingWired *setting);
const char *        nm_setting_wired_get_cloned_mac_address
                                                        (NMSettingWired *setting);
const char * const * nm_setting_wired_get_mac_address_blacklist
                                                        (NMSettingWired *setting);
guint32             nm_setting_wired_get_num_mac_blacklist_items
                                                        (NMSettingWired *setting);
const char *        nm_setting_wired_get_mac_blacklist_item
                                                        (NMSettingWired *setting,
                                                         guint32 idx);
gboolean            nm_setting_wired_add_mac_blacklist_item
                                                        (NMSettingWired *setting,
                                                         const char *mac);
void                nm_setting_wired_remove_mac_blacklist_item
                                                        (NMSettingWired *setting,
                                                         guint32 idx);
gboolean            nm_setting_wired_remove_mac_blacklist_item_by_value
                                                        (NMSettingWired *setting,
                                                         const char *mac);
void                nm_setting_wired_clear_mac_blacklist_items
                                                        (NMSettingWired *setting);
guint32             nm_setting_wired_get_mtu            (NMSettingWired *setting);
const char * const * nm_setting_wired_get_s390_subchannels
                                                        (NMSettingWired *setting);
const char *        nm_setting_wired_get_s390_nettype   (NMSettingWired *setting);
guint32             nm_setting_wired_get_num_s390_options
                                                        (NMSettingWired *setting);
gboolean            nm_setting_wired_get_s390_option    (NMSettingWired *setting,
                                                         guint32 idx,
                                                         const char **out_key,
                                                         const char **out_value);
const char *        nm_setting_wired_get_s390_option_by_key
                                                        (NMSettingWired *setting,
                                                         const char *key);
gboolean            nm_setting_wired_add_s390_option    (NMSettingWired *setting,
                                                         const char *key,
                                                         const char *value);
gboolean            nm_setting_wired_remove_s390_option (NMSettingWired *setting,
                                                         const char *key);
const char **       nm_setting_wired_get_valid_s390_options
                                                        (NMSettingWired *setting);
NMSettingWiredWakeOnLan nm_setting_wired_get_wake_on_lan
                                                        (NMSettingWired *setting);
const char *        nm_setting_wired_get_wake_on_lan_password
                                                        (NMSettingWired *setting);

Object Hierarchy

  GFlags
   +----NMSettingWiredWakeOnLan
  GObject
   +----NMSetting
         +----NMSettingWired

Properties

  "auto-negotiate"           gboolean              : Read / Write / Construct
  "cloned-mac-address"       gchar*                : Read / Write
  "duplex"                   gchar*                : Read / Write
  "mac-address"              gchar*                : Read / Write
  "mac-address-blacklist"    GStrv                 : Read / Write
  "mtu"                      guint                 : Read / Write / Construct
  "port"                     gchar*                : Read / Write
  "s390-nettype"             gchar*                : Read / Write
  "s390-options"             GHashTable*           : Read / Write
  "s390-subchannels"         GStrv                 : Read / Write
  "speed"                    guint                 : Read / Write / Construct
  "wake-on-lan"              guint                 : Read / Write / Construct
  "wake-on-lan-password"     gchar*                : Read / Write

Description

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

Details

NM_SETTING_WIRED_SETTING_NAME

#define NM_SETTING_WIRED_SETTING_NAME "802-3-ethernet"


enum NMSettingWiredWakeOnLan

typedef enum {
 /*< flags >*/
	NM_SETTING_WIRED_WAKE_ON_LAN_NONE      = 0, /*< skip >*/
	NM_SETTING_WIRED_WAKE_ON_LAN_PHY       = (1 << 1),
	NM_SETTING_WIRED_WAKE_ON_LAN_UNICAST   = (1 << 2),
	NM_SETTING_WIRED_WAKE_ON_LAN_MULTICAST = (1 << 3),
	NM_SETTING_WIRED_WAKE_ON_LAN_BROADCAST = (1 << 4),
	NM_SETTING_WIRED_WAKE_ON_LAN_ARP       = (1 << 5),
	NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC     = (1 << 6),

	_NM_SETTING_WIRED_WAKE_ON_LAN_LAST_OPT, /*< skip >*/
	NM_SETTING_WIRED_WAKE_ON_LAN_ALL       = (((_NM_SETTING_WIRED_WAKE_ON_LAN_LAST_OPT - 1) << 1) - 1) - (1 << 0 /*DEFAULT*/), /*< skip >*/

	NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT   = (1 << 0),
	NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE    = (1 << 15),
	NM_SETTING_WIRED_WAKE_ON_LAN_EXCLUSIVE_FLAGS = NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT | NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE, /*< skip >*/
} NMSettingWiredWakeOnLan;

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

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_LAST_OPT

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_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;

NMSettingWiredClass

typedef struct {
	NMSettingClass parent;
} NMSettingWiredClass;


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);

setting :

the NMSettingWired

Returns :

the "port" property of the setting

nm_setting_wired_get_speed ()

guint32             nm_setting_wired_get_speed          (NMSettingWired *setting);

setting :

the NMSettingWired

Returns :

the "speed" property of the setting

nm_setting_wired_get_duplex ()

const char *        nm_setting_wired_get_duplex         (NMSettingWired *setting);

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);

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);

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);

setting :

the NMSettingWired

Returns :

the "cloned-mac-address" property of the setting

nm_setting_wired_get_mac_address_blacklist ()

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

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);

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);

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.

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.

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.

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.

setting :

the NMSettingWired

nm_setting_wired_get_mtu ()

guint32             nm_setting_wired_get_mtu            (NMSettingWired *setting);

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.

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'.

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().

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.

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.

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.

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.

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.

setting :

the NMSettingWired

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

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.

setting :

the NMSettingWired

Returns :

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

Since 1.2

Property Details

The "auto-negotiate" property

  "auto-negotiate"           gboolean              : Read / Write / Construct

If TRUE, allow auto-negotiation of port speed and duplex mode. If FALSE, do not allow auto-negotiation, in which case the "speed" and "duplex" properties should be set.

Default value: TRUE


The "cloned-mac-address" property

  "cloned-mac-address"       gchar*                : Read / Write

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

Default value: NULL


The "duplex" property

  "duplex"                   gchar*                : Read / Write

If specified, request that the device only use the specified duplex mode. Either "half" or "full".

Default value: NULL


The "mac-address" property

  "mac-address"              gchar*                : Read / Write

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).

Default value: NULL


The "mac-address-blacklist" property

  "mac-address-blacklist"    GStrv                 : Read / Write

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).


The "mtu" property

  "mtu"                      guint                 : Read / Write / Construct

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

Default value: 0


The "port" property

  "port"                     gchar*                : Read / Write

Specific port type to use if multiple 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.

Default value: NULL


The "s390-nettype" property

  "s390-nettype"             gchar*                : Read / Write

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

Default value: NULL


The "s390-options" property

  "s390-options"             GHashTable*           : Read / Write

Dictionary of key/value pairs of s390-specific device options. Both keys and values must be strings. Allowed keys include "portno", "layer2", "portname", "protocol", among others. Key names must contain only alphanumeric characters (ie, [a-zA-Z0-9]).

Type: GHashTable(utf8,utf8)


The "s390-subchannels" property

  "s390-subchannels"         GStrv                 : Read / Write

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.


The "speed" property

  "speed"                    guint                 : Read / Write / Construct

If non-zero, request that the device use only the specified speed. In Mbit/s, ie 100 == 100Mbit/s.

Default value: 0


The "wake-on-lan" property

  "wake-on-lan"              guint                 : Read / Write / Construct

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).

Default value: 1

Since 1.2


The "wake-on-lan-password" property

  "wake-on-lan-password"     gchar*                : Read / Write

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.

Default value: NULL

Since 1.2