IFCFG-WIRELESS(5)

📦 version 0.6.80, in opensuse-leap 16.0

💖 IFCFG-WIRELESS(5) 💖

okay so welcome to IFCFG-WIRELESS(5), the manual page you're gonna want open in a second tab while you set up Wi-Fi on your box. it's giving "nobody warned me wireless config was this deep" energy, and honestly? iconic. let's get into it 🫶

🌸 NAME 🌸

ifcfg-wireless — wireless LAN network interface configuration

like, this is the page that explains all the wireless-specific knobs you can put in your ifcfg files. no cap.

✨ SYNOPSIS ✨

/etc/sysconfig/network/ifcfg-*

that glob is the whole squad. your interface configs live there and this page is about the wireless ones. 💅

🦋 GENERAL 🦋

okay so real talk: wireless networks need some additional configuration data compared to ethernet ones. ethernet is basically the low-maintenance friend; Wi-Fi is the one who needs ✨details✨. that's why extra variables for ifcfg files were introduced in the first place.

and here's a thing you gotta know, bestie: some wireless variables are not applicable to a single wireless network — they're global to the interface. the description of each variable points this out, so watch for it. iykyk 👀

💅 OPTIONS 💅

👑 Mandatory options

  • WIRELESS_ESSID <string> — set the SSID/ESSID, aka the Network Name. the ESSID is what identifies cells that are part of the same virtual network. the format allows the following escape sequences:
    • \x[0-9A-Fa-f]{2}: define one byte as hex (\x0A for new line)
    • \[0-9]{1,3}: define one byte in oktal (\012 for new line)
    • \t: translated to tab (\x09)
    • \n: translated to new line (\x0A)
    • \r: translated to carriage return (\x0D)
    • \e: translated to ESC (\x1B)
    • \\: become single \
    • \": become single "

🌈 Global wireless options

  • WIRELESS <bool> — enable or disable wireless for this configuration. if you don't give it, wireless gets enabled anyway whenever one of WIRELESS_ESSID, WIRELESS_AP_SCANMODE or WIRELESS_WPA_DRIVER is given. so it kinda turns itself on, main character behavior honestly ✨
  • WIRELESS_AP_SCANMODE <0|1|2> — defines which SSID scan mode should be used.
    • Mode 0 means the driver performs the scan.
    • Mode 1 means wpa_supplicant takes care of scanning.
    • Mode 2 is basically the same as mode 0 but the access point gets chosen by security policy and SSID. 🚨 this mode does not support multiple network settings.

default is "1" for most drivers. this variable can have no suffix. this sets the wpa_supplicant variable ap_scan.

  • WIRELESS_WPA_DRIVER <string> — lets you override the wpa driver name that should be used by the wpa_supplicant. default is "nl80211,wext". 🎀

🧚 Wireless network configuration options

  • WIRELESS_AUTH_MODE <OPEN|SHARED|PSK|EAP> — sets the authentication mode. which mode you pick depends on the protection technology being used. heads up tho: shared key authentication makes it easier for a potential attacker to break into your network 😭 so unless you have specific needs for shared key authentication, use the open mode. and since WEP has been proved insecure, WPA (Wi-Fi Protected Access) was defined to close its security wholes. the values PSK and EAP are deprecated — use WIRELESS_WPA_PSK or WIRELESS_EAP_MODE instead. for a specific key management protocol, consider the variable WIRELESS_KEY_MGMT. 💀
  • WIRELESS_KEY_MGMT <WPA-EAP|WPA-PSK|SAE|WPA-EAP-SUITE-B-192|...> — set the list of accepted authenticated key management protocols. when unset, wicked is using all protocols reported as device capabilities and filtered by PSK or EAP depending on further configuration variables. here's the whole menu:
    • PSK key management protocols (require WIRELESS_WPA_PSK):
      • WPA-PSK: WPA pre-shared key
      • FT-PSK: Fast BSS Transition (IEEE 802.11r) with pre-shared key
      • WPA-PSK-SHA256: like WPA-PSK but using stronger SHA256-based algorithms
      • SAE: Simultaneous authentication of equals
      • FT-SAE: SAE with FT
    • EAP key management protocols (require WIRELESS_EAP_MODE):
      • WPA-EAP: WPA using EAP authentication
      • WPA-EAP-SHA256: like WPA-EAP but using stronger SHA256-based algorithms
      • WPA-EAP-SUITE-B: Suite B 128-bit level
      • WPA-EAP-SUITE-B-192: Suite B 192-bit level
      • FT-EAP: Fast BSS Transition (IEEE 802.11r) with EAP authentication
      • FT-EAP-SHA384: Fast BSS Transition (IEEE 802.11r) with EAP authentication and using SHA384
    • OPEN network key management protocols:
      • NONE: WPA is not used; plaintext or static WEP could be used
      • OWE: Opportunistic Wireless Encryption (a.k.a. Enhanced Open)
  • WIRELESS_MODE <MANAGED|AD-HOC|MASTER> — set the operating mode of the device, which depends on the network topology:
    • set to ad-hoc for a network composed of only one cell and without an Access Point
    • managed for a network composed of many cells, with roaming or with an Access Point
    • master if you want your system to act as an Access Point or synchronisation master

default is managed.. (yes the manpage really has two dots there, love that for it 🎀)

  • WIRELESS_AP <address> — in environments with multiple Access points you may want to define the one to connect to by entering its MAC address. format is 6x2 hex digits, separated by colons, e.g. 01:02:03:04:05:06. slay, precision 🎯
  • WIRELESS_PRIORITY <num> — this variable only makes sense used in conjunction with multiple networks. if you want to prefer one configured network over another, set the respective WIRELESS_PRIORITY variable (means, with the same suffix) to a higher value (integer only). 🏆
  • WIRELESS_CHANNEL <num> — with this variable you can define the channel being used. this is only applicable to ad-hoc and master operating modes. channels are usually numbered starting at 1, and you may use iwpriv(8) to get the total number of channels and list the available frequencies. depending on regulations, some frequencies/channels may not be available. 🌍
  • WIRELESS_FREQUENCY_LIST <num|frequency-set> — in station mode, this space-separated list restricts the frequencies (in MHz) to search for the BSS (Access-Point with ESSID). additionally, the following predefined frequency set names can be used to specify frequency ranges:
    • 2.4Ghz: 2412-2484 Mhz
    • 5Ghz: 4920-5885 Mhz
    • 6Ghz: 5935-7115 Mhz
  • WIRELESS_KEY_[0123] <string|hex> — you can define up to 4 WEP encryption keys. you can use WEP with open and sharedkey authentication. the key can be entered in as ASCII string, where char represent one byte of the key, thus the length must match 5, 13 or 16. or you can specify the key in hex digits.
📝 note: for backward compatibility a prefix "h:" or characters like "-" or ":" get removed from the hex-string.

examples:

WIRELESS_KEY_0="01020304ff"
WIRELESS_KEY_0="s:hello"
  • WIRELESS_DEFAULT_KEY <num> — sets the default WEP key. the default key is used to encrypt outgoing packets, incoming ones are decrypted with the key number specified in the packet. this defaults to 0. 💌
  • WIRELESS_WPA_PROTO <WPA|RSN> — using this variable you can specify the WPA protocol to be used. valid values are WPA and RSN (aka WPA2). multiple values are allowed. default is both. 🔥
  • WIRELESS_WPA_PSK <string|hex> — when using WPA-PSK authentication, you need to specify your pre shared key here. the key is used for authentication and encryption purposes. you can enter it in hex digits (needs to be exactly 64 digits long) or as passphrase getting hashed (8 to 63 ASCII characters long). 🔐
  • WIRELESS_CIPHER_PAIRWISE <TKIP|CCMP> — WPA modes support two different encryption systems, TKIP and CCMP. this variable defines which to use for unicast communication. default is to allow both. in case you want to restrict it to one protocol, set this variable. ✨
  • WIRELESS_CIPHER_GROUP <TKIP|CCMP|WEP104|WEP40> — WPA modes support two different encryption systems, TKIP and CCMP. this variable defines which to use for broad-/multicast communication. default is to allow both. in case you want to restrict it to one protocol, set this variable. 📡
  • WIRELESS_EAP_MODE <TLS|PEAP|TTLS|...> — use this variable to specify the outer WPA-EAP authentication methods. 🧅 (layers, get it)
  • WIRELESS_EAP_AUTH <PAP|CHAP|MSCHAP|MSCHAPv2|...> — use this variable to specify the inner WPA-EAP authentication methods. 🫶
  • WIRELESS_WPA_IDENTITY <string> — identity string for WPA-EAP as configured on the RADIUS server. 🪪
  • WIRELESS_WPA_PASSWORD <string> — needs to be set in conjunction with WPA-EAP. set to your password as configured on the RADIUS server. 🤫
  • WIRELESS_WPA_ANONID <name> — sets anonymous identity. default is "anonymous". the anonymous identity is used with WPA-EAP protocols that support different tunnelled identities (e.g., TTLS). 🎭
  • WIRELESS_PEAP_VERSION <0|1> — when using WPA-EAP with PEAP authentication, you can use this variable to force which PEAP version (0 or 1) to be used. default is to allow both. 0️⃣1️⃣
  • WIRELESS_PEAP_LABEL <string> — when set to 1 the new label: "client PEAP encryption" can be enforced to be used during key derivation with version PEAPv1 or newer. most existing PEAPv1 implementation tend to use the old label, "client EAP encryption", which is the default value for wpa_supplicant. default value is 0. 🏷️
  • WIRELESS_CA_CERT <string> — CA certificate for Interworking network selection. the file path can be specified relative to the ifcfg file or absolute. 📜
  • WIRELESS_CLIENT_CERT <string> — file path to client certificate file (PEM/DER). it is used with WPA-EAP where a client certificate/private key is used for authentication (EAP-TLS). 🎓
  • WIRELESS_CLIENT_KEY <string> — file path to client private key file (PEM/DER/PFX). if the key is encrypted, specify the WIRELESS_CLIENT_KEY_PASSWORD. 🗝️
  • WIRELESS_HIDDEN_SSID <NO|YES> — set to "yes" if you try to connect to a hidden network. the probe request frames will be specific to the configured ESSID. 🙈
  • WIRELESS_FRAG <num> — maximum EAP fragment size in bytes (default 1398). this value limits the fragment size for EAP methods that support fragmentation (e.g., EAP-TLS and EAP-PEAP). this value should be set small enough to make the EAP messages fit in MTU of the network interface used for EAPOL. the default value is suitable for most cases. 🧩
  • WIRELESS_PMF <disabled|optional|required> — whether Protected Management Frames are enabled or not. default is disabled. 🛡️

okay that's the options rundown so far, and bestie there is MORE 💖 — part 2 is right around the corner, don't go anywhere 🌈

✨ EXAMPLE ✨

okay bestie, this is the part you actually came for 💅 here are some examples of the different configuration types supported at the moment — like, actually supported, no cap:

🎀 Common parameters

BOOTPROTO='dhcp'
NAME='PRO/Wireless 4965 AG or AGN [Kedron] Network Connection'
STARTMODE='auto'

🌸 Global wireless parameters

WIRELESS_AP_SCANMODE='1'
WIRELESS_WPA_DRIVER='nl80211,wext'

🦋 Scan only wireless configuration

STARTMODE='manual'
BOOTPROTO='none'
WIRELESS='yes'
# scan only, don't expect established connection:
LINK_REQUIRED=no

so you can literally just vibe check the airwaves without committing to a connection, iconic ✨ the scan results are listed in the <wireless/scan-results/bss> node of the wicked show-xml [ifname] output.

and if you wanna show all visible SSIDs and KEY-MGMTs, you can use e.g.:

wicked show-xml wlan0 | wicked xpath --reference 'object/wireless/scan-results/bss' 'ssid="%{ssid}" key-mgmt="%{?rsn/key-management} %{?wpa/key-management}"'

🫶 Open network configuration

WIRELESS_ESSID='example_ssid'

🔥 WPA-PSK

WIRELESS_ESSID='example_ssid'
WIRELESS_WPA_PSK='example_passwd'

💖 WPA-PSK (WPA1 only)

WIRELESS_ESSID='example_ssid'
WIRELESS_WPA_PSK='example_passwd'
WIRELESS_KEY_MGMT='WPA-PSK'
WIRELESS_CIPHER_PAIRWISE='TKIP'
WIRELESS_CIPHER_GROUP='TKIP'

💜 WPA-PSK (WPA2 only)

WIRELESS_ESSID='example_ssid'
WIRELESS_WPA_PSK='example_passwd'
WIRELESS_KEY_MGMT='WPA-PSK'
WIRELESS_CIPHER_PAIRWISE='CCMP'
WIRELESS_CIPHER_GROUP='CCMP'

👑 WPA-PSK (WPA3 only)

WIRELESS_ESSID='example_ssid'
WIRELESS_WPA_PSK='example_passwd'
WIRELESS_KEY_MGMT='SAE'
WIRELESS_PMF='required'
WIRELESS_CIPHER_PAIRWISE='CCMP'
WIRELESS_CIPHER_GROUP='CCMP'

🌈 WPA-PSK (WPA2 and WPA3 transition)

WIRELESS_ESSID='example_ssid'
WIRELESS_WPA_PSK='example_passwd'
WIRELESS_KEY_MGMT='WPA-PSK WPA-PSK-SHA256 SAE'
WIRELESS_PMF='optional'
WIRELESS_CIPHER_PAIRWISE='CCMP'
WIRELESS_CIPHER_GROUP='CCMP'

🧚 WPA-EAP/PEAP/MSCHAPv2 network configuration

WIRELESS_ESSID='example_ssid'
WIRELESS_EAP_MODE='PEAP'
WIRELESS_EAP_AUTH='MSCHAPv2'
WIRELESS_WPA_IDENTITY='bob'
WIRELESS_WPA_PASSWORD='example_password'
WIRELESS_CA_CERT='/path/to/my/ca_cert.pem'

⭐ WPA-EAP/TTLS/PAP network configuration**

WIRELESS_ESSID='example_ssid'
WIRELESS_EAP_MODE='TTLS'
WIRELESS_EAP_AUTH='PAP'
WIRELESS_WPA_IDENTITY='bob'
WIRELESS_WPA_PASSWORD='example_passwd'
WIRELESS_CA_CERT='/path/to/my/ca_cert.pem'

(yes the double asterisk is in the original, we're not touching it, it's part of the lore 🫶)

🍓 WPA-EAP/TLS network configuration

WIRELESS_ESSID='example_ssid'
WIRELESS_EAP_MODE='TLS'
WIRELESS_WPA_IDENTITY='bob'
WIRELESS_CLIENT_CERT='/path/to/my/client.crt'
WIRELESS_CLIENT_KEY='/path/to/my/client.key'
WIRELESS_CA_CERT='/path/to/my/ca_cert.pem'

💀 WEP network configuration – insecure!

WIRELESS_AUTH_MODE='shared'
WIRELESS_KEY_0="s:hallo"
WIRELESS_KEY_1="01020304050607080900010203"
bestie I am begging you — insecure! that's literally in the title of the example. WEP is giving 2003 flip phone energy. it's here so you know what it looks like, not so you go do it 😭

💅 Multiple network configuration

WIRELESS_ESSID='example_open_ssid'

WIRELESS_ESSID_1='super_secure'
WIRELESS_PRIORITY_1='10'
WIRELESS_EAP_MODE_1='TLS'
WIRELESS_WPA_IDENTITY_1='bob'
WIRELESS_CA_CERT_1='/path/to/my/ca_cert.pem'
WIRELESS_CLIENT_CERT_1='/path/to/my/client.crt'
WIRELESS_CLIENT_KEY_1='/path/to/my/client.key'

WIRELESS_ESSID_2='example_psk_ssid'
WIRELESS_WPA_PSK_2='example_passwd'

WIRELESS_ESSID_3='home_wifi_5G'
WIRELESS_WPA_PSK_3='example_passwd'
WIRELESS_PRIORITY_3='5'
WIRELESS_WPA_PROTO_3='RSN'
WIRELESS_CIPHER_PAIRWISE_3='CCMP'
WIRELESS_CIPHER_GROUP_3='TKIP,CCMP'

look at all those numbered suffixes — that's the multiple-network main character energy, one base config and then _1, _2, _3 doing their own thing 💖

Copyright (C) 2014-2022 SUSE LLC

that's the whole section, short and sweet, periodt 🎀

🐛 BUGS

found a bug? don't suffer in silence bestie — please report bugs as described at <https://bugs.opensuse.org> 🫶

👀 SEE ALSO

go read these next, iykyk:

🌟 AUTHORS

  • Joachim Gleissner – original wireless man page
  • Pawel Wieczorkiewicz
  • Clemens Famulla-Conrad

and that's the whole page, bestie, you made it to the end 🎉 this was the Wicked User Manual, dated Jan 7, 2025, and you just read IFCFG-WIRELESS(5) — go forth and connect responsibly 💅✨💖

📦 where this page comes from