Gentoo Logo

Disclaimer : This handbook has been replaced by a newer version and is not maintained anymore.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

4. Wireless Networking


4.a. Introduction

Wireless networking on Linux is usually pretty straightforward. There are two ways of configuring wifi: graphical clients, or the command line.

The easiest way is to use a graphical client once you've installed a desktop environment. Most graphical clients, such as wicd and NetworkManager, are pretty self-explanatory. They offer a handy point-and-click interface that gets you on a network in just a few seconds.

Note: wicd offers a command line utility in addition to the main graphical interface. You can get it by emerging wicd with the ncurses USE flag set. This wicd-curses utility is particularly useful for folks who don't use a gtk-based desktop environment, but still want an easy command line tool that doesn't require hand-editing configuration files.

However, if you don't want to use a graphical client, then you can configure wifi on 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 screenshots at their homepages), we'll focus on the command line alternatives.

You can setup wireless networking on the command line by installing wireless-tools or wpa_supplicant. The important thing to remember is that you configure wireless networks on a global basis and not an interface basis.

wpa_supplicant is the best choice. For a list of supported drivers, read the wpa_supplicant site.

wireless-tools supports nearly all cards and drivers, but it cannot connect to WPA-only Access Points. If your networks only offer WEP encryption or are completely open, you may prefer the simplicity of wireless-tools.

Warning: The linux-wlan-ng driver is not supported by baselayout at this time. This is because linux-wlan-ng have its own setup and configuration which is completely different to everyone else's. The linux-wlan-ng developers are rumoured to be changing their setup over to wireless-tools, so when this happens you may use linux-wlan-ng with baselayout.

Some wireless cards are deactivated by default. To activate them, please consult your 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, you might need to unblock the wireless card through a button, switch or special key combination on your laptop.

4.b. WPA Supplicant

WPA Supplicant is a package that allows you to connect to WPA enabled access points.

Code Listing 2.1: Install wpa_supplicant

# emerge net-wireless/wpa_supplicant

Important: You have to have CONFIG_PACKET enabled in your kernel for wpa_supplicant to work. Try running grep CONFIG_PACKET /usr/src/linux/.config to see if you have it enabled in your kernel.

Note: Depending on your USE flags, wpa_supplicant can install a graphical interface written in Qt4, which will integrate nicely with KDE. To get it, run echo "net-wireless/wpa_supplicant qt4" >> /etc/portage/package.use as root before emerging wpa_supplicant.

Now we have to configure /etc/conf.d/net to so that we prefer wpa_supplicant over wireless-tools (if both are installed, wireless-tools is the default).

Code Listing 2.2: configure /etc/conf.d/net for wpa_supplicant

# Prefer wpa_supplicant over wireless-tools

# It's important that we tell wpa_supplicant which driver we should
# be using as it's not very good at guessing yet

Note: If you're using the host-ap driver you will need to put the card in Managed mode before it can be used with wpa_supplicant correctly. You can use iwconfig_eth0="mode managed" to achieve this in /etc/conf.d/net.

That was simple, wasn't it? However, we still have to configure wpa_supplicant itself which is a bit more tricky depending on how secure the Access Points are that you are trying to connect to. The below example is taken and simplified from /usr/share/doc/wpa_supplicant-<version>/wpa_supplicant.conf.gz which ships with wpa_supplicant.

Code Listing 2.3: An example /etc/wpa_supplicant/wpa_supplicant.conf

# The below line not be changed otherwise we refuse to work

# Ensure that only root can read the WPA configuration

# Let wpa_supplicant take care of scanning and AP selection

# Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers
  psk="very secret passphrase"
  # The higher the priority the sooner we are matched

# Same as previous, but request SSID-specific scanning (for APs that reject
# broadcast SSID)
  ssid="second ssid"
  psk="very secret passphrase"

# Only WPA-PSK is used. Any valid cipher combination is accepted
  pairwise=CCMP TKIP
  group=CCMP TKIP WEP104 WEP40

# Plaintext connection (no WPA, no IEEE 802.1X)

# Shared WEP key connection (no WPA, no IEEE 802.1X)
  # Keys in quotes are ASCII keys
  # Keys specified without quotes are hex keys

# Shared WEP key connection (no WPA, no IEEE 802.1X) using Shared Key
# IEEE 802.11 authentication

# IBSS/ad-hoc network with WPA-None/TKIP
  ssid="test adhoc"
  psk="secret passphrase"

4.c. Wireless Tools

Initial setup and Managed Mode

Wireless Tools provide a generic way to configure basic wireless interfaces up to the WEP security level. While WEP is a weak security method it's also the most prevalent.

Wireless Tools configuration is controlled by a few main variables. The sample configuration file below should describe all you need. One thing to bear in mind is that no configuration means "connect to the strongest unencrypted Access Point" - we will always try and connect you to something.

Code Listing 3.1: Install wireless-tools

# emerge net-wireless/wireless-tools

Note: Although you can store your wireless settings in /etc/conf.d/wireless this guide recommends you store them in /etc/conf.d/net.

Important: You will need to consult the variable name documentation.

Code Listing 3.2: sample iwconfig setup in /etc/conf.d/net

# Prefer iwconfig over wpa_supplicant

# 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 Access Point Selection

You can add some extra options to fine-tune your Access Point selection, but these are not normally required.

You can decide whether we only connect to preferred Access Points or not. By default if everything configured has failed and we can connect to an unencrypted Access Point then we 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 behaviour
preferredonly We will only connect to visible APs in the preferred list
forcepreferred We will 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

Finally we have some 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.

Code Listing 3.3: blacklist_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"

Ad-Hoc and Master Modes

If you want to set yourself up as an Ad-Hoc node if you fail to connect to any Access Point in managed mode, you can do that too.

Code Listing 3.4: fallback to ad-hoc mode

adhoc_essid_eth0="This Adhoc Node"

What about connecting to Ad-Hoc networks or running in Master mode to become an Access Point? Here's a configuration just for that! You may need to specify WEP keys as shown above.

Code Listing 3.5: sample ad-hoc/master configuration

# Set the mode - can be managed (default), ad-hoc or master
# Not all drivers support all modes

# 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

Important: The below is taken verbatim from 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 your card or access point. Make sure that the channel you select is the same channel your 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 you can use to help get your wireless up and running due to driver or environment problems. Here's a table of other things you can try.

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

4.d. Defining network configuration per ESSID

Sometimes, you need a static IP when you connect to ESSID1 and you need DHCP when you connect to ESSID2. In fact, most module variables can be defined per ESSID. Here's how we do this.

Note: These work if you're using WPA Supplicant or Wireless Tools.

Important: You will need to consult the variable name documentation.

Code Listing 4.1: override network settings per ESSID

config_ESSID1=" brd"
routes_ESSID1="default via"

fallback_route_ESSID2="default via"

# We can define nameservers and other things too
# NOTE: DHCP will override these unless it's told not to
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
dhcpcd_001122334455="-t 10"

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated December 17, 2013

Summary: Wireless isn't straight-forward. Hopefully we'll get you working!

Sven Vermeulen

Grant Goodyear

Roy Marples

Daniel Robbins

Chris Houser

Jerry Alexandratos

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Xavier Neys

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Lars Weiler

Tobias Scherbaum

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.