NM.SettingWireless¶

Subclasses:: None

Methods¶

Inherited:: NM.Setting (21), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add_mac_blacklist_item` (mac)
	`add_mac_denylist_item` (mac)
	`add_seen_bssid` (bssid)
	`ap_security_compatible` (s_wireless_sec, ap_flags, ap_wpa, ap_rsn, ap_mode)
	`clear_mac_blacklist_items` ()
	`clear_mac_denylist_items` ()
	`get_ap_isolation` ()
	`get_band` ()
	`get_bssid` ()
	`get_channel` ()
	`get_channel_width` ()
	`get_cloned_mac_address` ()
	`get_generate_mac_address_mask` ()
	`get_hidden` ()
	`get_mac_address` ()
	`get_mac_address_blacklist` ()
	`get_mac_address_denylist` ()
	`get_mac_address_randomization` ()
	`get_mac_blacklist_item` (idx)
	`get_mac_denylist_item` (idx)
	`get_mode` ()
	`get_mtu` ()
	`get_num_mac_blacklist_items` ()
	`get_num_mac_denylist_items` ()
	`get_num_seen_bssids` ()
	`get_powersave` ()
	`get_rate` ()
	`get_seen_bssid` (i)
	`get_ssid` ()
	`get_tx_power` ()
	`get_wake_on_wlan` ()
	`remove_mac_blacklist_item` (idx)
	`remove_mac_blacklist_item_by_value` (mac)
	`remove_mac_denylist_item` (idx)
	`remove_mac_denylist_item_by_value` (mac)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: NM.Setting (1)

Name	Type	Flags	Short Description
`ap-isolation`	`NM.Ternary`	r/w/en
`band`	`str`	r/w/en
`bssid`	`str`	r/w/en
`channel`	`int`	r/w/en
`channel-width`	`int`	r/w/en
`cloned-mac-address`	`str`	r/w/en
`generate-mac-address-mask`	`str`	r/w/en
`hidden`	`bool`	r/w/en
`mac-address`	`str`	r/w/en
`mac-address-blacklist`	[`str`]	r/w/en
`mac-address-denylist`	[`str`]	r/w/en
`mac-address-randomization`	`int`	r/w/en	`deprecated`
`mode`	`str`	r/w/en
`mtu`	`int`	r/w/en
`powersave`	`int`	r/w/en
`rate`	`int`	r/w/en	`deprecated`
`seen-bssids`	[`str`]	r/w
`ssid`	`GLib.Bytes`	r/w/en
`tx-power`	`int`	r/w/en	`deprecated`
`wake-on-wlan`	`int`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class NM.SettingWireless(**kwargs)¶

Bases:: NM.Setting
Abstract:: No
Structure:: NM.SettingWirelessClass

Wi-Fi Settings

classmethod new()¶

Returns:: the new empty NM.SettingWireless object
Return type:: NM.Setting

Creates a new NM.SettingWireless object with default values.

add_mac_blacklist_item(mac)¶

Parameters:: mac (str) – the MAC address string (hex-digits-and-colons notation) to denylist
Returns:: True if the MAC address was added; False if the MAC address is invalid or was already present
Return type:: bool

Adds a new MAC address to the NM.SettingWireless :mac-address-denylist property.

Deprecated since version 1.48.: Use NM.SettingWireless.add_mac_denylist_item() instead.

add_mac_denylist_item(mac)¶

Parameters:: mac (str) – the MAC address string (hex-digits-and-colons notation) to denylist
Returns:: True if the MAC address was added; False if the MAC address is invalid or was already present
Return type:: bool

Adds a new MAC address to the NM.SettingWireless :mac-address-denylist property.

New in version 1.48.

add_seen_bssid(bssid)¶

Parameters:: bssid (str) – the new BSSID to add to the list
Returns:: True if bssid was already known, False if not
Return type:: bool

Adds a new Wi-Fi AP’s BSSID to the previously seen BSSID list of the setting. NetworkManager now tracks previously seen BSSIDs internally so this function no longer has much use. Actually, changes you make using this function will not be preserved.

ap_security_compatible(s_wireless_sec, ap_flags, ap_wpa, ap_rsn, ap_mode)¶

Parameters:

s_wireless_sec (NM.SettingWirelessSecurity) – a NM.SettingWirelessSecurity or None
ap_flags (NM.80211ApFlags) – the NM._80211ApFlags of the given access point
ap_wpa (NM.80211ApSecurityFlags) – the NM._80211ApSecurityFlags of the given access point’s WPA capabilities
ap_rsn (NM.80211ApSecurityFlags) – the NM._80211ApSecurityFlags of the given access point’s WPA2/RSN capabilities
ap_mode (NM.80211Mode) – the 802.11 mode of the AP, either Ad-Hoc or Infrastructure

Returns:

True if the given settings are compatible with the access point’s security flags and mode, False if they are not.

Return type:

bool

Given a NM.SettingWireless and an optional NM.SettingWirelessSecurity, determine if the configuration given by the settings is compatible with the security of an access point using that access point’s capability flags and mode. Useful for clients that wish to filter a set of connections against a set of access points and determine which connections are compatible with which access points.

clear_mac_blacklist_items()¶: Removes all denylisted MAC addresses.

Deprecated since version 1.48.: Use NM.SettingWireless.clear_mac_denylist_items() instead.

clear_mac_denylist_items()¶: Removes all denylisted MAC addresses.

New in version 1.48.

get_ap_isolation()¶

Returns:: the NM.SettingWireless :ap-isolation property of the setting
Return type:: NM.Ternary

New in version 1.28.

get_band()¶

Returns:: the NM.SettingWireless :band property of the setting
Return type:: str

get_bssid()¶

Returns:: the NM.SettingWireless :bssid property of the setting
Return type:: str

get_channel()¶

Returns:: the NM.SettingWireless :channel property of the setting
Return type:: int

get_channel_width()¶

Returns:: the channel width
Return type:: NM.SettingWirelessChannelWidth

Returns the NM.SettingWireless :channel-width property.

New in version 1.50.

get_cloned_mac_address()¶

Returns:: the NM.SettingWireless :cloned-mac-address property of the setting
Return type:: str

get_generate_mac_address_mask()¶

Returns:: the NM.SettingWireless :generate-mac-address-mask property of the setting
Return type:: str

New in version 1.4.

get_hidden()¶

Returns:: the NM.SettingWireless :hidden property of the setting
Return type:: bool

get_mac_address()¶

Returns:: the NM.SettingWireless :mac-address property of the setting
Return type:: str

get_mac_address_blacklist()¶

Returns:: the NM.SettingWireless :mac-address-blacklist property of the setting
Return type:: [str]

Deprecated since version 1.48.: Use NM.SettingWireless.get_mac_address_denylist() instead.

get_mac_address_denylist()¶

Returns:: the NM.SettingWireless :mac-address-denylist property of the setting
Return type:: [str]

New in version 1.48.

get_mac_address_randomization()¶

Returns:: the NM.SettingWireless :mac-address-randomization property of the setting
Return type:: NM.SettingMacRandomization

New in version 1.2.

get_mac_blacklist_item(idx)¶

Parameters:: idx (int) – the zero-based index of the MAC address entry
Returns:: the denylisted MAC address string (hex-digits-and-colons notation) at index idx
Return type:: str

Since 1.46, access at index “len” is allowed and returns None.

Deprecated since version 1.48.: Use NM.SettingWireless.get_mac_denylist_item() instead.

get_mac_denylist_item(idx)¶

Parameters:: idx (int) – the zero-based index of the MAC address entry
Returns:: the denylisted MAC address string (hex-digits-and-colons notation) at index idx
Return type:: str

New in version 1.48.

get_mode()¶

Returns:: the NM.SettingWireless :mode property of the setting
Return type:: str

get_mtu()¶

Returns:: the NM.SettingWireless :mtu property of the setting
Return type:: int

get_num_mac_blacklist_items()¶

Returns:: the number of blacklist MAC addresses
Return type:: int

Deprecated since version 1.48.: Use NM.SettingWireless.get_num_mac_denylist_items() instead.

get_num_mac_denylist_items()¶

Returns:: the number of denylisted MAC addresses
Return type:: int

New in version 1.48.

get_num_seen_bssids()¶

Returns:: the number of BSSIDs in the previously seen BSSID list
Return type:: int

get_powersave()¶

Returns:: the NM.SettingWireless :powersave property of the setting
Return type:: int

New in version 1.2.

get_rate()¶

Returns:: the NM.SettingWireless :rate property of the setting
Return type:: int

Deprecated since version 1.44: This setting is not implemented and has no effect.

get_seen_bssid(i)¶

Parameters:: i (int) – index of a BSSID in the previously seen BSSID list
Returns:: the BSSID at index i
Return type:: str

get_ssid()¶

Returns:: the NM.SettingWireless :ssid property of the setting
Return type:: GLib.Bytes

get_tx_power()¶

Returns:: the NM.SettingWireless :tx-power property of the setting
Return type:: int

Deprecated since version 1.44: This setting is not implemented and has no effect.

get_wake_on_wlan()¶

Returns:: the Wake-on-WLAN options
Return type:: NM.SettingWirelessWakeOnWLan

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

New in version 1.12.

remove_mac_blacklist_item(idx)¶

Parameters:: idx (int) – index number of the MAC address

Removes the MAC address at index idx from the denylist.

Deprecated since version 1.48.: Use NM.SettingWireless.remove_mac_denylist_item() instead.

remove_mac_blacklist_item_by_value(mac)¶

Parameters:: mac (str) – the MAC address string (hex-digits-and-colons notation) to remove from the denylist
Returns:: True if the MAC address was found and removed; False if it was not.
Return type:: bool

Removes the MAC address mac from the denylist.

Deprecated since version 1.48.: Use NM.SettingWireless.remove_mac_denylist_item_by_value() instead.

remove_mac_denylist_item(idx)¶

Parameters:: idx (int) – index number of the MAC address

Removes the MAC address at index idx from the denylist.

New in version 1.48.

remove_mac_denylist_item_by_value(mac)¶

Parameters:: mac (str) – the MAC address string (hex-digits-and-colons notation) to remove from the denylist
Returns:: True if the MAC address was found and removed; False if it was not.
Return type:: bool

Removes the MAC address mac from the denylist.

New in version 1.48.

Property Details¶

NM.SettingWireless.props.ap_isolation¶

Name:: ap-isolation
Type:: NM.Ternary
Default Value:: NM.Ternary.DEFAULT
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Configures AP isolation, which prevents communication between wireless devices connected to this AP. This property can be set to a value different from NM.Ternary.DEFAULT only when the interface is configured in AP mode.

If set to NM.Ternary.TRUE, devices are not able to communicate with each other. This increases security because it protects devices against attacks from other clients in the network. At the same time, it prevents devices to access resources on the same wireless networks as file shares, printers, etc.

If set to NM.Ternary.FALSE, devices can talk to each other.

When set to NM.Ternary.DEFAULT, the global default is used; in case the global default is unspecified it is assumed to be NM.Ternary.FALSE.

New in version 1.28.

NM.SettingWireless.props.band¶

Name:: band
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

802.11 frequency band of the network. One of “a” for 5GHz 802.11a or “bg” for 2.4GHz 802.11. This will lock associations to the Wi-Fi network to the specific band, i.e. if “a” is specified, the device will not associate with the same network in the 2.4GHz band even if the network’s settings are compatible. This setting depends on specific driver capability and may not work with all drivers.

NM.SettingWireless.props.bssid¶

Name:: bssid
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If specified, directs the device to only associate with the given access point. This capability is highly driver dependent and not supported by all devices. Note: this property does not control the BSSID used when creating an Ad-Hoc network and is unlikely to in the future.

Locking a client profile to a certain BSSID will prevent roaming and also disable background scanning. That can be useful, if there is only one access point for the SSID.

NM.SettingWireless.props.channel¶

Name:: channel
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Wireless channel to use for the Wi-Fi connection. The device will only join (or create for Ad-Hoc networks) a Wi-Fi network on the specified channel. Because channel numbers overlap between bands, this property also requires the “band” property to be set.

NM.SettingWireless.props.channel_width¶

Name:: channel-width
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Specifies width of the wireless channel in Access Point (AP) mode.

When set to NM.SettingWirelessChannelWidth.AUTO (the default), the channel width is automatically determined. At the moment, this means that the safest (smallest) width is chosen.

If the value is not NM.SettingWirelessChannelWidth.AUTO, then the ‘channel’ property must also be set. When using the 2.4GHz band, the width can be at most 40MHz.

This property can be set to a value different from NM.SettingWirelessChannelWidth.AUTO only when the interface is configured in AP mode.

New in version 1.50.

NM.SettingWireless.props.cloned_mac_address¶

Name:: cloned-mac-address
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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”, “stable” and “stable-ssid” are supported. “preserve” means not to touch the MAC address on activation. “permanent” means to use the permanent hardware address of the device. “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. “stable-ssid” creates a hashed MAC address based on the SSID, the same as setting the stable-id to “${NETWORK_SSID}”.

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

NM.SettingWireless.props.generate_mac_address_mask¶

Name:: generate-mac-address-mask
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

With NM.SettingWireless :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 None, it is eligible to be overwritten by a default connection setting. If the value is still None 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:py:data::FF<NM.SettingWireless.props.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:py:data::FF<NM.SettingWireless.props.FF>:00:00:00 68:py:data::F7<NM.SettingWireless.props.F7>:28:00:00:00” will set the OUI of the MAC address to 68:py:data::F7<NM.SettingWireless.props.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.

NM.SettingWireless.props.hidden¶

Name:: hidden
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

If True, indicates that the network is a non-broadcasting network that hides its SSID. This works both in infrastructure and AP mode.

In infrastructure mode, various workarounds are used for a more reliable discovery of hidden networks, such as probe-scanning the SSID. However, these workarounds expose inherent insecurities with hidden SSID networks, and thus hidden SSID networks should be used with caution.

In AP mode, the created network does not broadcast its SSID.

Note that marking the network as hidden may be a privacy issue for you (in infrastructure mode) or client stations (in AP mode), as the explicit probe-scans are distinctly recognizable on the air.

NM.SettingWireless.props.mac_address¶

Name:: mac-address
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

NM.SettingWireless.props.mac_address_blacklist¶

Name:: mac-address-blacklist
Type:: [str]
Default Value:: []
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply. Each MAC address should be given in the standard hex-digits-and-colons notation (eg “00:11:22:33:44:55”).

NM.SettingWireless.props.mac_address_denylist¶

Name:: mac-address-denylist
Type:: [str]
Default Value:: []
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply. Each MAC address should be given in the standard hex-digits-and-colons notation (eg “00:11:22:33:44:55”).

NM.SettingWireless.props.mac_address_randomization¶

Name:: mac-address-randomization
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

One of NM.SettingMacRandomization.DEFAULT (never randomize unless the user has set a global default to randomize and the supplicant supports randomization), NM.SettingMacRandomization.NEVER (never randomize the MAC address), or NM.SettingMacRandomization.ALWAYS (always randomize the MAC address).

New in version 1.2.

Deprecated since version 1.4: Use the NM.SettingWireless :cloned-mac-address property instead.

NM.SettingWireless.props.mode¶

Name:: mode
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Wi-Fi network mode; one of “infrastructure”, “mesh”, “adhoc” or “ap”. If blank, infrastructure is assumed.

NM.SettingWireless.props.mtu¶

Name:: mtu
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

NM.SettingWireless.props.powersave¶

Name:: powersave
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

One of NM.SettingWirelessPowersave.DISABLE (disable Wi-Fi power saving), NM.SettingWirelessPowersave.ENABLE (enable Wi-Fi power saving), NM.SettingWirelessPowersave.IGNORE (don’t touch currently configure setting) or NM.SettingWirelessPowersave.DEFAULT (use the globally configured value). All other values are reserved.

New in version 1.2.

NM.SettingWireless.props.rate¶

Name:: rate
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

This property is not implemented and has no effect.

Deprecated since version 1.44: This property is not implemented and has no effect.

NM.SettingWireless.props.seen_bssids¶

Name:: seen-bssids
Type:: [str]
Default Value:: []
Flags:: READABLE, WRITABLE

A list of BSSIDs (each BSSID formatted as a MAC address like “00:11:22:33:44:55”) that have been detected as part of the Wi-Fi network. NetworkManager internally tracks previously seen BSSIDs. The property is only meant for reading and reflects the BSSID list of NetworkManager. The changes you make to this property will not be preserved.

This is not a regular property that the user would configure. Instead, NetworkManager automatically sets the seen BSSIDs and tracks them internally in “/var/lib/NetworkManager/seen-bssids” file.

NM.SettingWireless.props.ssid¶

Name:: ssid
Type:: GLib.Bytes
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

SSID of the Wi-Fi network. Must be specified.

NM.SettingWireless.props.tx_power¶

Name:: tx-power
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

This property is not implemented and has no effect.

Deprecated since version 1.44: This property is not implemented and has no effect.

NM.SettingWireless.props.wake_on_wlan¶

Name:: wake-on-wlan
Type:: int
Default Value:: 1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

New in version 1.12.