This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Handbook:Alpha/Networking/Wireless
Introduction
Wireless networking on Linux is usually pretty straightforward. There are three ways of configuring wifi: graphical clients, text-mode interfaces, and command-line interfaces.
The easiest way is to use a graphical client once a desktop environment is installed. Most graphical clients, such as wicd and NetworkManager, are pretty self-explanatory. They offer a handy point-and-click interface that gets users on a network in just a few seconds.
Both NetworkManager and wicd offer text-mode interface utilities in addition to the main graphical interface. Emerge either the net-misc/networkmanager or net-misc/wicd package with the
ncurses USE flag enabled. The nmtui or wicd-curses utilities are particularly useful for folks who do not use a X or Wayland based desktop environment, but still desire an easy-to-use tool that does not require hand-editing configuration files.Wireless can also be configured from the command line by editing a few configuration files. This takes a bit more time to setup, but it also requires the fewest packages to download and install. Since the graphical clients are mostly self-explanatory (with helpful screen shots at their home pages), we'll focus on the command line alternatives.
There are three tools that support command-line driven wireless configurations: net-wireless/iw, net-wireless/wireless-tools and net-wireless/wpa_supplicant. Of these three, net-wireless/wpa_supplicant is the preferred one. The important thing to remember is that wireless networks are configured on a global basis and not an interface basis.
The net-wireless/iw software, the successor of net-wireless/wireless-tools, supports nearly all cards and drivers, but it cannot connect to WPA-only Access Points. If the networks only offer WEP encryption or are completely open, then net-wireless/iw beats the other package over simplicity.
Some wireless cards are deactivated by default. To activate them, please consult the hardware documentation. Some of these cards can be unblocked using the rfkill application. If that is the case, use rfkill list to see the available cards and rfkill unblock INDEX to activate the wireless functionality. If not, then the wireless card might need to be unlocked through a button, switch or special key combination on the laptop.
WPA supplicant
The WPA supplicant project provides a package that allows users to connect to WPA enabled access points.
root #emerge --ask net-wireless/wpa_supplicantIt is necessary to have CONFIG_PACKET enabled in the kernel for wpa_supplicant to work. To see if it is enabled on the current kernel, try:
root #zgrep CONFIG_PACKET /proc/config.gz
root #grep CONFIG_PACKET /usr/src/linux/.config
Depending on the USE flags, wpa_supplicant can install a graphical interface written in Qt5, which will integrate nicely with KDE. To get it, enable
USE="qt5" for the net-wireless/wpa_supplicant package.Next, configure /etc/conf.d/net so that the wpa_supplicant module is preferred over wireless-tools (if both are installed, wireless-tools is the default).
/etc/conf.d/netForce the use of wpa_supplicant# Prefer wpa_supplicant over wireless-tools modules="wpa_supplicant"
When using the host-ap driver it is necessary to put the card in Managed mode before it can be used with wpa_supplicant correctly. This can be achieved by setting
iwconfig_eth0="mode managed" in /etc/conf.d/net.Next configure wpa_supplicant itself (which is a bit more tricky depending on how secure the Access Points are). The below example is taken and simplified from /usr/share/doc/wpa_supplicant-<version>/wpa_supplicant.conf.gz which ships with wpa_supplicant.
/etc/wpa_supplicant/wpa_supplicant.confSomewhat simplified example# The below line not be changed otherwise wpa_supplicant refuses to work ctrl_interface=/var/run/wpa_supplicant # Ensure that only root can read the WPA configuration ctrl_interface_group=0 # Let wpa_supplicant take care of scanning and AP selection ap_scan=1 # Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers network={ ssid="simple" psk="very secret passphrase" # The higher the priority the sooner we are matched priority=5 } # Same as previous, but request SSID-specific scanning (for APs that reject # broadcast SSID) network={ ssid="second ssid" scan_ssid=1 psk="very secret passphrase" priority=2 } # Only WPA-PSK is used. Any valid cipher combination is accepted network={ ssid="example" proto=WPA key_mgmt=WPA-PSK pairwise=CCMP TKIP group=CCMP TKIP WEP104 WEP40 psk=06b4be19da289f475aa46a33cb793029d4ab3db7a23ee92382eb0106c72ac7bb priority=2 } # Plaintext connection (no WPA, no IEEE 802.1X) network={ ssid="plaintext-test" key_mgmt=NONE } # Shared WEP key connection (no WPA, no IEEE 802.1X) network={ ssid="static-wep-test" key_mgmt=NONE # Keys in quotes are ASCII keys wep_key0="abcde" # Keys specified without quotes are hex keys wep_key1=0102030405 wep_key2="1234567890123" wep_tx_keyidx=0 priority=5 } # Shared WEP key connection (no WPA, no IEEE 802.1X) using Shared Key # IEEE 802.11 authentication network={ ssid="static-wep-test2" key_mgmt=NONE wep_key0="abcde" wep_key1=0102030405 wep_key2="1234567890123" wep_tx_keyidx=0 priority=5 auth_alg=SHARED } # IBSS/ad-hoc network with WPA-None/TKIP network={ ssid="test adhoc" mode=1 proto=WPA key_mgmt=WPA-NONE pairwise=NONE group=TKIP psk="secret passphrase" }
Wireless tools
Initial setup and managed mode
The wireless tools project provides a generic way to configure basic wireless interfaces up to the WEP security level. While WEP is a weak security method it's still prevalent in the world.
Wireless tools configuration is controlled by a few main variables. The sample configuration file below should describe all that is needed. One thing to bear in mind is that no configuration means "connect to the strongest unencrypted Access Point" - wireless tools will always try and connect the system to something.
root #emerge --ask net-wireless/wireless-toolsAlthough net-wireless/iw is the current tool for the wireless stack, net-misc/netifrc does not work with the new commands. net-wireless/wireless-tools must be used with netifrc. For more information consult the variable name documentation.
/etc/conf.d/netSample iwconfig setup# Prefer iwconfig over wpa_supplicant modules="iwconfig" # Configure WEP keys for Access Points called ESSID1 and ESSID2 # You may configure up to 4 WEP keys, but only 1 can be active at # any time so we supply a default index of [1] to set key [1] and then # again afterwards to change the active key to [1] # We do this incase you define other ESSID's to use WEP keys other than 1 # # Prefixing the key with s: means it's an ASCII key, otherwise a HEX key # # enc open specified open security (most secure) # enc restricted specified restricted security (least secure) key_ESSID1="[1] s:yourkeyhere key [1] enc open" key_ESSID2="[1] aaaa-bbbb-cccc-dd key [1] enc restricted" # The below only work when we scan for available Access Points # Sometimes more than one Access Point is visible so we need to # define a preferred order to connect in preferred_aps="'ESSID1' 'ESSID2'"
Fine-tune AP selection
It is possible to add some extra options to fine-tune the AP selection, but these are not required.
One way is to configure the system so it only connects to preferred APs. By default if everything configured has failed and wireless-tools can connect to an unencrypted Access Point then it will. This can be controlled by the associate_order variable. Here's a table of values and how they control this.
| Value | Description |
|---|---|
| any | Default behavior. |
| preferredonly | Only connect to visible APs in the preferred list. |
| forcepreferred | Forceably connect to APs in the preferred order if they are not found in a scan. |
| forcepreferredonly | Do not scan for APs - instead just try to connect to each one in order. |
| forceany | Same as forcepreferred + connect to any other available AP. |
There is also the blacklist_aps and unique_ap selection. blacklist_aps works in a similar way to preferred_aps. unique_ap is a yes or no value that says if a second wireless interface can connect to the same Access Point as the first interface.
/etc/conf.d/netblacklist_aps and unique_ap example# Sometimes you never want to connect to certain access points blacklist_aps="'ESSID3' 'ESSID4'" # If you have more than one wireless card, you can say if you want # to allow each card to associate with the same Access Point or not # Values are "yes" and "no" # Default is "yes" unique_ap="yes"
Ad-hoc and master modes
To set the system up as an ad-hoc node when it fails to connect to any Access Point in managed mode, use this as a fallback:
/etc/conf.d/netFallback to ad-hoc modeadhoc_essid_eth0="This Adhoc Node"
It is also possible to connect to ad-hoc networks, or to run the system in master mode so it becomes an access point itself.
/etc/conf.d/netSample ad-hoc/master configuration# Set the mode - can be managed (default), ad-hoc or master # Not all drivers support all modes mode_eth0="ad-hoc" # Set the ESSID of the interface # In managed mode, this forces the interface to try and connect to the # specified ESSID and nothing else essid_eth0="This Adhoc Node" # We use channel 3 if you don't specify one channel_eth0="9"
An important resource about channel selection is the BSD wavelan documentation found at the NetBSD documentation. There are 14 channels possible; We are told that channels 1-11 are legal for North America, channels 1-13 for most of Europe, channels 10-13 for France, and only channel 14 for Japan. If in doubt, please refer to the documentation that came with the card or access point. Make sure that the channel selected is the same channel the access point (or the other card in an ad-hoc network) is on. The default for cards sold in North America and most of Europe is 3; the default for cards sold in France is 11, and the default for cards sold in Japan is 14.
Troubleshooting wireless tools
There are some more variables that can help to get the wireless up and running due to driver or environment problems. Here's a table of other things that can be tried.
| Variable name | Default value | Description |
|---|---|---|
| iwconfig_eth0 | See the iwconfig man page for details on what to send iwconfig. | |
| iwpriv_eth0 | See the iwpriv man page for details on what to send iwpriv. | |
| sleep_scan_eth0 | 0 | The number of seconds to sleep before attempting to scan. This is needed when the driver/firmware needs more time to active before it can be used. |
| sleep_associate_eth0 | 5 | The number of seconds to wait for the interface to associate with the Access Point before moving onto the next one. |
| associate_test_eth0 | MAC | Some drivers do not reset the MAC address associated with an invalid one when they lose or attempt association. Some drivers do not reset the quality level when they lose or attempt association. Valid settings are MAC, quality and all. |
| scan_mode_eth0 | Some drivers have to scan in ad-hoc mode, so if scanning fails try setting ad-hoc here. | |
| iwpriv_scan_pre_eth0 | Sends some iwpriv commands to the interface before scanning. See the iwpriv man page for more details. | |
| iwpriv_scan_post_eth0 | Sends some iwpriv commands to the interface after scanning. See the iwpriv man page for more details. |
Defining network configuration per ESSID
In this section, we show how to configure network settings based on the ESSID. For instance, with the wireless network with ESSID ESSID1 configure a static IP address while ESSID ESSID2 uses DHCP.
This works with both wpa_supplicant as well as wireless-tools
Please consult the variable name documentation.
/etc/conf.d/netoverride network settings per ESSIDconfig_ESSID1="192.168.0.3/24 brd 192.168.0.255" routes_ESSID1="default via 192.168.0.1" config_ESSID2="dhcp" fallback_ESSID2="192.168.3.4/24" fallback_route_ESSID2="default via 192.168.3.1" # We can define nameservers and other things too # NOTE: DHCP will override these unless it's told not to dns_servers_ESSID1="192.168.0.1 192.168.0.2" dns_domain_ESSID1="some.domain" dns_search_domains_ESSID1="search.this.domain search.that.domain" # You override by the MAC address of the Access Point # This handy if you goto different locations that have the same ESSID config_001122334455="dhcp" dhcpcd_001122334455="-t 10" dns_servers_001122334455="192.168.0.1 192.168.0.2"