Summit Network Manager User Guide Overview This document outlines the added features of the Ezurio version of NetworkManager. Some of these features are only compatible with our EZ Connectivity Stack. EZ Connectivity Stack For more information about the EZ Connectivity Stack, please visit https://www.ezurio.com/software/ez-connectivity-stack, contact your local RSM, or contact us at https://www.ezurio.com/contact. Release packages are available on Github at https://github.com/Ezurio/Connectivity_Stack_Release_Packages/releases. NetworkManager For general information about upstream NetworkManager, visit: https://networkmanager.dev/docs/api/latest/. Basic Connectivity This section provides commands to configure connection profiles for basic usage. This is only meant as a demonstration. We recommend that you follow the link provided in the Overview section and read the man (manual) pages for more information. Getting Started and Useful Commands man Pages # man nmcli # man nmcli-examples Starting up Wi-Fi The following is an example of starting up Wi-Fi and scanning for a list of available connections. # nmcli radio wifi on # nmcli dev wifi rescan # nmcli dev wifi list IN-USE SSID MODE CHAN RATE SIGNAL BARS SECURITY opentest Infra 1 195 Mbit/s 92 **** -- 8021xtest Infra 40 195 Mbit/s 59 *** WPA2 802.1X wpa2test Infra 1 195 Mbit/s 70 *** WPA2 adhoctest Ad-Hoc 1 54 Mbit/s 60 *** -- testac Infra 52 405 Mbit/s 60 *** -- Viewing Available Connection Profiles # nmcli con NAME UUID TYPE DEVICE 8021xtest 0e85c35a-e28e-4da8-a956-7d286c49b4b7 wifi -- Wired connection 1 a09d5560-4a54-34f6-b50c-b35d58a62f1f ethernet -- hotspot 92b33586-da57-442f-853f-a0e0b2359e83 wifi wlan0 opentest 3e152a5b-942a-4163-b418-9c236d2ec7a6 wifi -- wpa2test 41a56cde-57b1-47ac-a9df-fa62115d9da8 wifi -- Display Device Status # nmcli device status DEVICE TYPE STATE CONNECTION wlan0 wifi connected hotspot eth0 ethernet unavailable -- lo loopback unmanaged -- Display the Parameters of a Given Connection The output of this command is very exhaustive. We edited it (…) in this example to show some key parameters. # nmcli -p con show hotspot =============================================================================== Connection profile details (hotspot) =============================================================================== connection.id: hotspot5 connection.uuid: 92b33586-da57-442f-853f-a0e0b2359e83 connection.stable-id: -- connection.type: 802-11-wireless connection.interface-name: wlan0 connection.autoconnect: no ... 802-11-wireless.ssid: hotspot 802-11-wireless.mode: ap 802-11-wireless.band: bg 802-11-wireless.channel: 6 ... 802-11-wireless-security.key-mgmt: wpa-psk ... =============================================================================== Activate connection details (92b33586-da57-442f-853f-a0e0b2359e83) =============================================================================== GENERAL.NAME: hotspot GENERAL.UUID: 92b33586-da57-442f-853f-a0e0b2359e83 GENERAL.DEVICES: wlan0 GENERAL.STATE: activated ... ——————————————————————————- IP4.ADDRESS[1]: 10.42.0.1/24 IP4.GATEWAY: -- IP4.ROUTE[1]: dst = 10.42.0.0/24, nh = 0.0.0.0, mt = 600 UUID For best practice, give each connection profile a unique name to make managing the profiles an easier task. In situations where connection names are duplicated, there is an alternative method to addressing a profile by its name. The UUID (Universally Unique Identifier) is automatically generated for each profile upon creation and can be substituted for the connection name in any command. # nmcli con NAME UUID TYPE DEVICE 8021xtest bcb6a35b-305d-4ecc-b147-0c57c22884fc wifi -- Wired connection 1 a09d5560-4a54-34f6-b50c-b35d58a62f1f ethernet -- hotspot 99d9e9d5-d7b5-4217-919d-e4a6c23421fa wifi -- hotspot 44d0030f-872f-4684-921e-3077c3b02ea7 wifi -- opentest 3e152a5b-942a-4163-b418-9c236d2ec7a6 wifi -- wpa2test 41a56cde-57b1-47ac-a9df-fa62115d9da8 wifi -- # nmcli con up 99d9e9d5-d7b5-4217-919d-e4a6c23421fa Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/Ac... Connecting as a Client The following are examples that demonstrate connection profiles for different security types. Unsecured Network # nmcli con NAME UUID TYPE DEVICE Wired connection 1 bd88ab65-cad4-3012-b31d-b73ce7dc9de7 ethernet -- # nmcli con add con-name opentest ifname wlan0 type wifi ssid opentest Connection 'opentest' (3e152a5b-942a-4163-b418-9c236d2ec7a6) successfully added. # nmcli con NAME UUID TYPE DEVICE opentest 3e152a5b-942a-4163-b418-9c236d2ec7a6 wifi wlan0 Wired connection 1 bd88ab65-cad4-3012-b31d-b73ce7dc9de7 ethernet -- # nmcli con up opentest Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/Ac... WPA2-PSK Secured Network # nmcli conn add con-name wpa2test ifname wlan0 type wifi ssid "wpa2test" # nmcli conn modify id wpa2test 802-11-wireless-security.key-mgmt wpa-psk # nmcli conn modify id wpa2test 802-11-wireless-security.psk "test1234" # nmcli conn up wpa2test Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/Ac... WPA2-AES-802.1X + CCKM Secured Network Using EAP-TLS and Certificate # nmcli con add con-name 8021xtest ifname wlan0 type wifi ssid "8021xtest" Connection '8021xtest' (0e85c35a-e28e-4da8-a956-7d286c49b4b7) successfully added. # nmcli con mod id 8021xtest 802-1x.eap tls 802-1x.identity user1 802-1x.private-key \ /etc/ssl/certs/user1.pem 802-1x.password user1 802-1x.client-cert /etc/ssl/certs/user1.pem # nmcli con mod id 8021xtest 802-11-wireless-security.key-mgmt wpa-eap # nmcli --ask con up 8021xtest Passwords or encryption keys are required to access the wireless network '8021xtest'. Identity (802-1x.identity): user1 Passwords or encryption keys are required to access the wireless network '8021xtest'. Private key password (802-1x.private-key-password): ***** Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/Ac... SoftAP Mode SoftAP 2.4GHz b/g Band This connection profile configures the host to broadcast a WPA2-PSK secured network on channel 6 (2437 MHz) with the SSID named hotspot and to share the wired ethernet connection to connected clients. # nmcli conn add type wifi ifname wlan0 con-name hotspot autoconnect no ssid "hotspot" # nmcli con mod hotspot 802-11-wireless.mode ap ipv4.method shared # nmcli con mod hotspot 802-11-wireless.band bg 802-11-wireless.channel 6 # nmcli con mod hotspot wifi-sec.key-mgmt wpa-psk wifi-sec.psk "test1234" # nmcli con mod hotspot wifi-sec.pairwise CCMP wifi-sec.proto RSN # nmcli con up hotspot Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/Ac... Ezurio Commands 802-1x Properties Key Name: 802-1x.phase2-auth Value Type: List of authentication methods Default Value: Value Description: This field has been modified to accept multiple authentication methods. # nmcli con modify test 802-1x.phase2-auth mschapv2 +802-1x.phase2-auth gtc Key Name: 802-1x.phase2-autheap Value Type: List of authentication methods Default Value: Value Description: This field was modified to accept multiple authentication methods. # nmcli con modify test 802-1x.phase2-autheap mschapv2 +802-1x.phase2-autheap gtc Key Name: 802-1x.phase1-auth-flags Value Type: Space-separated list of authentication flag names Default Value: none Value Description: Specifies authentication flags for “phase 1” outer authentication. The tls-disable-time-checks flag disables time/date checking of server/CA certificates. Other available flags include tls-1-0-disable, tls-1-0-enable, tls-1-1-disable, tls-1-1-enable, tls-1-2-disable, tls-1-2-enable, tls-1-3-disable, tls-1-3-enable, and safe-renegotiation. See the wpa_supplicant documentation for more details. # nmcli con modify test 802-1x.phase1-auth-flags tls-disable-time-checks Key Name: 802-1x.pac-file-password Value Type: string Default Value: Not set Value Description: Used to decrypt manually provisioned EAP-FAST PAC files. Requires Summit supplicant. # nmcli con modify test 802-1x.pac-file-password password 802-11-wireless Properties Key Name: 802-11-wireless.auth-timeout Value Type: uint32 (0-60) Default Value: 0 Value Description: Will restart association if authentication does not complete within the configured timeout. A value of 0 uses the Summit supplicant default of 8 seconds. The minimum configurable non-zero value accepted by the supplicant is 3 seconds. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.auth-timeout 8 Key Name: 802-11-wireless.frequency-list Value Type: string – A list of frequencies separated by spaces Default Value: Not set – Use all frequencies Value Description: Limits scanning to the listed frequencies. When set, frequency-list applies to all scans (both while connected and disconnected). # nmcli con modify test 802-11-wireless.frequency-list "2412 2462" Key Name: 802-11-wireless.ccx Value Type: 0 (disabled), 1 (optimized) or 2 (full) Default Value: 0 (disabled) Value Description: Used to enable CCX features. 0 = Do not use Cisco IE and CCX version number. 1 = Use Cisco IE and CCX version number and enable support for all CCX features except AP-assisted roaming, AP-specified maximum transmit power, and radio management. 2 = Use Cisco IE and CCX version number and enable support for all CCX features. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.ccx 1 Key Name: 802-11-wireless.client-name Value Type: string (up to 16 character name - ascii) Default Value: Not set Value Description: If CCX is enabled, the client-name will be sent to a CCX capable AP to identify the device. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.client-name "device22" Key Name: 802-11-wireless.acs Value Type: uint32 (0-2) Default Value: 0 (disabled) Value Description: Auto channel selection. 0 disables ACS. 1 selects Summit ACS. 2 selects Survey-Based ACS. When ACS is enabled, a channel can be auto-selected for AP mode based on the configured frequency list, band, and channel. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.acs 1 Key Name: 802-11-wireless.dms Value Type: uint32 Default Value: 0 Value Description: Directed Multicast Service (DMS). 0 disables DMS (default). 4 enables DMS for IPv4. 6 enables DMS for IPv6. DMS is only activated if the AP advertises DMS support in its Extended Capabilities (bit 26). Requires Summit supplicant. # nmcli con modify test 802-11-wireless.dms 4 Key Name: 802-11-wireless.ap-config-file Value Type: string Default Value: Not set Value Description: Hostap configuration template file used for 802.1x AP modes. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.ap-config-file "/etc/hostapd.conf" Key Name: 802-11-wireless.summit-flags Value Type: uint32 (flags) Default Value: 0 (none) Value Description: Summit-specific feature flags. Available flags: roam-mfp-deauth (0x1) – deauthenticate before performing an MFP (Management Frame Protection) roam. Not all devices support all options. Requires Summit supplicant. # nmcli con modify test 802-11-wireless.summit-flags roam-mfp-deauth 802-11-wireless-security Properties Key Name: 802-11-wireless-security.proto Value Type: 802.11 authentication protocol Default Value: Value Description: ‘wpa3’ was added. When ‘wpa3’ is selected, it must be the only value. Requires Summit supplicant. # nmcli con modify test 802-11-wireless-security.proto wpa3 Key Name: 802-11-wireless-security.key-mgmt Value Type: key management method Default Value: Value Description: This field has been modified to add ‘cckm’. Requires Summit supplicant. # nmcli con modify test 802-11-wireless-security.key-mgmt cckm Key Name: 802-11-wireless-security.pairwise Value Type: pairwise cipher Default Value: Value Description: This field has been modified to add ‘ccmp-256’, ‘gcmp’ and ‘gcmp-256’. Requires Summit supplicant. # nmcli con modify test 802-11-wireless-security.pairwise ccmp-256 Key Name: 802-11-wireless-security.proactive-key-caching Value Type: string (“0” or “1”) Default Value: Conditional – “1” (enabled) when not explicitly set for wpa-eap, wpa-eap-suite-b, wpa-eap-suite-b-192, or cckm connections; “0” otherwise Value Description: Selects PMK usage normal/SPMK (“0”) or OPMK (“1”). This property is optional. When not explicitly set for wpa-eap, wpa-eap-suite-b, wpa-eap-suite-b-192, or cckm connections, it defaults to enabled (“1”). This property may also be applied to non wpa-eap key-mgmt profiles; for example, SAE with some controller APs uses OKC. # nmcli con modify test 802-11-wireless-security.proactive-key-caching 1 Key Name: 802-11-wireless-security.ft Value Type: default, disable, optional, required Default Value: default (disabled) Value Description: Used to enable Fast Transition/802.11r connection methods. One of default (use global default value), disable (disable FT), optional (enable FT if the supplicant and the access point support it) or required (enable FT and fail if not supported). # nmcli con modify test 802-11-wireless-security.ft optional Key Name: 802-11-wireless-security.owe-only Value Type: default, no, yes Default Value: default (enabled) Value Description: Indicates whether owe-only must be enabled for an OWE (Opportunistic Wireless Encryption) connection. When set to default and no global default is set, owe-only will be enabled. # nmcli con modify test 802-11-wireless-security.owe-only yes Additional notes regarding 802-11-wireless-security: Default pairwise/group and group management (group pmf) cipher values are as follows: When using wpa-eap-suite-b or wpa-eap-suite-b-192, the group management cipher is automatically configured: wpa-eap-suite-b (both wpa3 and wpa2): pairwise/group=gcmp with group_mgmt=BIP-GMAC-128 wpa-eap-suite-b-192 (wpa3): pairwise/group=gcmp-256 with group_mgmt=BIP-GMAC-256 wpa-eap-suite-b-192 (wpa2): pairwise/group=ccmp-256 and gcmp-256 with group_mgmt=BIP-CMAC-256 and BIP-GMAC-256 For other key-mgmt types: wpa3 proto (wpa-psk, wpa-eap, sae, owe, cckm): pairwise/group=ccmp (no group_mgmt) wpa2 proto (other key-mgmt): no defaults set – uses supplicant defaults other protos: no defaults set – uses supplicant defaults of tkip, ccmp Note: The group management cipher is automatically configured based on key-mgmt type and cannot be manually set. It is only configured for wpa-eap-suite-b and wpa-eap-suite-b-192. Note: For wpa-eap-suite-b and wpa-eap-suite-b-192: manually configured pairwise/group ciphers must be from the list above 802-1x.eap must be set to tls for proto wpa3, a CA certificate is required For wpa3 (802-11-wireless-security.proto wpa3): wpa3 is only supported with the Summit supplicant wpa3 must be the only 802-11-wireless-security.proto value 802-11-wireless.mode must be infrastructure or ap wep and tkip ciphers are not allowed (802-11-wireless-security.pairwise/group) 802-11-wireless-security.key-mgmt must be one of: wpa-psk, wpa-eap, sae, wpa-eap-suite-b, wpa-eap-suite-b-192, owe wpa-psk is wpa3-sae-transition mode; sae is wpa3-sae-only mode Scanning Key Name: 802-11-wireless.hidden Value Type: boolean (0 or 1) Default Value: 0 Value Description: Scanning behavior is modified. If all profiles are marked as hidden, broadcast probe requests are suppressed. # nmcli con modify test 802-11-wireless.hidden 1 Key Name: 802-11-wireless.max-scan-interval Value Type: uint32 (seconds) Default Value: 0 (unlimited) Value Description: When set to 0, the NetworkManager scan interval is unlimited. When set to a non-zero value, it limits the interval to a range of 3 to 120 seconds (values outside this range are clamped). While scanning, NetworkManager pauses between scans; this pause increases when a suitable network is not found. # nmcli con modify test 802-11-wireless.max-scan-interval 30 Key Name: 802-11-wireless.bgscan Value Type: string Default Value: Not set (uses default from NetworkManager) Value Description: Controls the supplicant background scanning while connected to a network. Refer to the supplicant wpa_supplicant.conf bgscan for more details. simple:<short interval seconds>:<threshold dBm>:<long interval seconds> – above the threshold uses the long interval (seconds) for scanning and below uses the short interval (seconds). # nmcli con modify test 802-11-wireless.bgscan "simple:30:-45:60" Scanning Parameters - 60 Series radio and Summit supplicant required Key Name: 802-11-wireless.scan-delay Value Type: uint32 (0-250) Default Value: 0 (use linux mac80211 default) Value Description: For active scanning, the time (msec) to wait after tuning to a new channel before transmitting a probe request. # nmcli con modify test 802-11-wireless.scan-delay 0 Key Name: 802-11-wireless.scan-dwell Value Type: uint32 (0-250) Default Value: 0 (use linux mac80211 default) Value Description: For active scanning, the time (msec) to wait for probe responses after transmitting a probe request. # nmcli con modify test 802-11-wireless.scan-dwell 0 Key Name: 802-11-wireless.scan-passive-dwell Value Type: uint32 (0-250) Default Value: 0 (use linux mac80211 default) Value Description: For passive scanning, the time (msec) to spend on the channel waiting/listening (e.g., for beacons and other management frames). # nmcli con modify test 802-11-wireless.scan-passive-dwell 0 Key Name: 802-11-wireless.scan-suspend-time Value Type: uint32 (0-250) Default Value: 0 (use linux mac80211 default) Value Description: For background scanning, the duration (msec) to periodically suspend background scanning to service the active connection. # nmcli con modify test 802-11-wireless.scan-suspend-time 0 Key Name: 802-11-wireless.frequency-dfs Value Type: uint32 (0 or 1) Default Value: 1 (enabled) Value Description: Set to zero to disable DFS/Radar frequencies. # nmcli con modify test 802-11-wireless.frequency-dfs 1 Key Name: 802-11-wireless.scan-roam-delta Value Type: uint32 (dB) Default Value: 0 (do not limit) Value Description: For roaming, limits the number of dB better required for a roam. # nmcli con modify test 802-11-wireless.scan-roam-delta 5 Scanning Notes While connected, the settings for that profile apply to all scans, including NetworkManager scans (both automatic and manual). While disconnected, NetworkManager automatic scanning uses the following: The union of the frequency-list from all profiles DFS/Radar channels are only disabled if disabled in all profiles The largest scan timing parameter value from all profiles While disconnected, NetworkManager manual scans do the following: # nmcli device wifi rescan ifname wlan0 ssid "abcd" # nmcli device wifi rescan ifname wlan0 ssid "" scan all-frequencies scan DFS/Radar channels use default scan timing NetworkManager.conf additions wifi.scan-avoid-bcast-ssid will limit NetworkManager from sending a broadcast probe request when scanning regardless of a connection’s wifi.hidden setting. Manual NetworkManager scans such as nmcli device wifi rescan ssid "" will force a broadcast probe request. This setting can be useful to limit the number of BSSIDs the radio needs to process in very busy environments, speeding up the time to connect. [device] wifi.scan-avoid-bcast-ssid=yes wifi.disable-periodic-scan will stop NetworkManager from doing periodic scans when the interface is disconnected or failed. This can be useful in AP+STA modes where we don’t want both wlan0 and wlan1 interfaces doing periodic scans when both interfaces use the same radio and share scan data. See NetworkManager.conf documentation to see how to apply it globally or per device. [device] wifi.disable-periodic-scan=yes
