Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



Configuration for most cards is done in /etc/conf.d/net. There are two things required for wireless network configuration. The standard network adapter configuration (static IP or DHCP, DNS, gateways, etc.) and authentication against a wireless access point. Read the previous guides, and refer to this page for explanations and additions. There are 2 tools to configure a wireless connection with:

Kernel configuration

Linux Kernel Configuration: Wireless configuration
 Networking  --->
   [*] Networking support
   Wireless  --->
     <*> Improved wireless configuration API

The following is only used by very old drivers:

     --- Wireless extensions

The selection between the following two depends on the driver being used. The first is the new stack, the second is the old:

     < > Generic IEEE 802.11 Networking Stack (mac80211)
     <*> Generic IEEE 802.11 Networking Stack
     [ ]   Enable full debugging output
     ---   IEEE 802.11 WEP encryption (802.1x)
     <*>   IEEE 802.11i CCMP support
     <*>   IEEE 802.11i TKIP encryption
     <*>   Software MAC add-on to the IEEE 802.11 networking stack
     [ ]     Enable full debugging output
     [*]   Enable RAIODTAP headers for capibilities that can support it.

Turn on the following even if not using any of the drivers in the kernel:

 Device Drivers  --->
   Network device support  --->
     Wireless LAN  --->
       [*] Wireless LAN (IEEE 802.11)
       ... Select driver as needed if it's in the kernel source ...

The following should be on automatically by dependencies, but if not, turn it on:

 Cryptographic options  --->
   [*] Cryptographic API

Checking if the driver loaded

You need to install wireless-tools first. Run iwconfig. If the driver is loaded and attached to the adapter a line should appear which doesn't end with no wireless extensions.. Example output:

Code: iwconfig sample output
wlan0     IEEE 802.11g  ESSID:"<removed>"
          Mode:Managed  Frequency:2.437 GHz  Access Point: <removed>
          Bit Rate:54 Mb/s   Tx-Power:15 dBm
          Retry limit:15   RTS thr:off   Fragment thr:off
          Encryption key:<removed>   Security mode:open
          Power Management:off
          Link Quality=85/100  Signal level=-48 dBm  Noise level=-103 dBm
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:430   Missed beacon:0


If you are having issues, it may help to see the full output of the Gentoo network init script to troubleshoot the connection. Set RC_VERBOSE=yes in /etc/conf.d/rc. Some people may have to bring the network and the card down before being able to bring the device up:

Code: Commands
ifconfig <device> down
rmmod <module name>
modprobe <module name>

Please refer to dmesg if you have furthermore problems with connecting to an access point.

Required information

To configure your WLAN device, you need to know the following information about your access point:

Note: If the ESSID has dashes or other non-alphanumeric English characters (i.e. anything that isn't a letter or number, or that does not appear in the English alphabet) replace it with an underscore.

Configuring /etc/conf.d/net

It's possible to run completely different network settings per ESSID connected to - check the /etc/conf.d/wireless.example file for details on how to achieve this. Note: /etc/conf.d/wireless is deprecated. Please put all settings in /etc/conf.d/net. Also for more details look at the Gentoo Linux Networking Handbook.

A sample configuration file would look like this:

File: /etc/conf.d/net snippet
config_ath1=( "dhcp" )
dhcpcd_ath1="-t 30" # Timeout after 30 seconds
File: /etc/conf.d/net
 preferred_aps=( "MY-ESSID" )

Some cards (or drivers) may need some time to complete the association with the access point:

File: /etc/conf.d/net

Check the wireless section in /etc/conf.d/net.example for examples.

WEP Encryption

Warning: WEP is very insecure, if you have the option consider using WPA instead.

Up to 4 WEP keys can be specified for wireless networks:

File: /etc/conf.d/net
key_MY-ESSID="s:MY-WEPKEY enc open"

If you are using an hexadecimal WEP key instead (containing only 0 to 9 digits and A to F letters) instead, the key argument must be passed without s:

Code: hexadecimal WEP key
key_home=( "<hexa WEP key> enc open" )	

If you do not want to use the /etc/conf.d/net script, you can create a bash file which executes all commands manually. Note that this will only work with unencrypted or WEP protected access points. For WPA encryption, you need to use wpa_supplicant.

ifconfig <device> up
iwconfig <device> key <WEP key>
dhcpcd <device>

Then make it executable:

chmod +x
Note: Roaming

Many people put this in local.start to have it initiated at boot.

File: /etc/conf.d/local.start
# My init script to start the network


The second way of configuring wireless, and the best way, is by using wpa_supplicant. To install, simply emerge wpa_supplicant. Once installed, you can edit the /etc/wpa_supplicant/wpa_supplicant.conf file by checking out the examples in /etc/wpa_supplicant/wpa_supplicant.conf.example (or if not there, check in /usr/share/doc/wpa_supplicant-?.?.?/, filling in your version number) This file contains many options, is well documented and is a little easier to setup for multiple APs than by using /etc/conf.d/wireless. A sample configuration file would look like this:

File: /etc/wpa_supplicant/wpa_supplicant.conf snippet
# This is a network block that connects to a specific unsecured access point.
# We give it a higher priority.

# This is a network block that connects to any unsecured access point.
# We give it a low priority so any defined blocks are preferred.

You may also want to be able to configure wireless networks comfortable using wpa_gui which is very powerful and convenient. In order to use it as a user and, more important, to make it save the configs, you have to add followings to wpa_supplicant.conf:

File: /etc/wpa_supplicant/wpa_supplicant.conf snippet

The bonus in configuring your wireless setup using wpa_supplicant is that it supports all types of encryption currently used: WEP, WPA and even non-encrypted. Do not forget to compile the kernel modules necessary for encryption. These may be Networking -> IEEE 802.11i TKIP Encryption and similar ones.

To use wpa_supplicant over iwconfig for wireless configuration, put the following in /etc/conf.d/net:

File: /etc/conf.d/net snippet
modules=( "wpa_supplicant" )
# Users of madwifi add this:
# Users of Intel ipw2100/2200 (Centrino) chips with older kernels add this:

# As of kernel 2.6.15 (and probably earlier), centrino users have to use
wpa_supplicant_ath0="-Dwext -c /etc/wpa_supplicant/wpa_supplicant.conf"
# wpa_supplicant.conf by default now is located in /etc/wpa_supplicant
# but yours could be in /etc.

Note: Replace ath0 as required with wlan0, eth1 etc. and madwifi with ndiswrapper or the correct drivers for your wireless card (see wpa_supplicant --help for a list of drivers).

Note: With ndiswrapper version 1.13 and newer, use -Dwext instead of -Dndiswrapper ( Also make sure that you add "ap_scan=2" to your wpa_supplicant.conf if you want to connect to hidden networks.

Note: You will need to comment out any config_ESSID settings, as they do not work in conjunction with wpa_supplicant. If not, you will receive the following hard-to-read error:

Nov 13 06:14:20 yourhost wpa_cli: interface ath0 CONNECTED
Nov 13 06:14:21 yourhost wpa_cli: executing '/etc/init.d/net.ath0 --quiet start' failed

Connect using the Gentoo networking init script

Create a link that corresponds to your network interface/device in /etc/init.d/ and then start it:

cd /etc/init.d
ln -s net.lo net.DEVICE
/etc/init.d/net.DEVICE start

To start the Gentoo networking init script at boot: rc-update add net.<device> default.

Useful scripts

Wireless + Ethernet connections

Some computers (mostly laptops) have both ethernet and wireless connectors. Double network connection is generally not needed. Bringing up the wireless network interface can be prevented by the preup() function in /etc/conf.d/net (change wlan0 and eth0 as appropriate):

Code: /etc/conf.d/net
preup() {
if [[ ${IFACE} == "wlan0" ]]; then
	if ifplugstatus | grep -q 'eth0: link beat detected'; then
		ewarn "Wired connection on eth0 detected, aborting configuration on ${IFACE}"
		return 1
return 0

Wireless + Ethernet (ifplugd)

If the wired ethernet device is controlled via ifplugd we are able to use /etc/ifplugd/ifplugd.action to fire up the wireless device as soon as the ethernet cord is removed and bring it down if the cord is plugged in again. Add the lines marked new below in /etc/ifplugd/ifplugd.action

Code: /etc/ifplugd/ifplugd.action
case "$2" in
	if [ "${INITNG}" = "yes" ]
	    ARGS="-u net/$1"
	    /etc/init.d/net.wlan0 --quiet stop	# this line is new
	    modprobe -r iwl3945			# this line is new
	    ARGS="--quiet start"
	if [ "${INITNG}" = "yes" ]
	    ARGS="-d net/$1"
	    ARGS="--quiet stop"
	    modprobe iwl3945			# this line is new
	    /etc/init.d/net.wlan0 --quiet start	# this line is new


Connection times out every time

According to ArchLinux Wiki, if the connection always times out, you should set the rate of the card to 5.5M:

Code: Setting the rate to 5.5M
iwconfig wlan0 rate 5.5M auto

In Gentoo, this can be automated at startup by adding the following line to your /etc/conf.d/net:

Code: /etc/conf.d/net
rate_wlan0=( "5.5M auto" )

If this does not work for you, you could also try out 11M instead of 5.5M (see [1]). You can also try to change from pid to simple rate control algorithm by replacing this line




Failed to initialize WEP

If your card cannot be initialized due to an -12 error and you have error lines saying something like this:

Code: dmesg
wmaster0: Failed to initialize wep

Be sure you compiled Generic IEEE 802.11 Networking Stack into kernel (and not as a module!)

Linux Kernel Configuration: Wifi
Networking --->
  [*] Networking support
  Wireless --->
    <*> Generic IEEE 802.11 Networking Stack (mac80211)

Net services like Apache don't start if both wlan0 and eth0 aren't started

If RC strict is set to "yes", then it will require that all net devices are started before any of the net services are started, you need to set this to "no".

For baselayout-1: Open /etc/conf.d/rc and change RF_NET_STRICT_CHECKING to "NO"

For baselayout-2: Open /etc/rc.conf and change rc_depend_strict to "NO"

SIOCSIFADDR: No such device

It's a kernel or driver problem. Chances are you're using NDISwrapper and it's not configured correctly.

In addition one could be missing the proper microcode. For the Intel 3945ABG this situation can be resolved with "emerge iwl3945-ucode".

Can also be the wifi "kill switch" being turned on.

Prism based card behaving unreliably

Possibly cause by old buggy firmware. See here for a possible fix.

"Failed to initialize EAPOL state machines" error upon starting wpa_supplicant

Comment out the openssl lines in the wpa_supplicant config file:

File: /etc/wpa_supplicant/wpa_supplicant.conf


Wireless extensions missing even though the device is a wireless adapter

Wireless-Extensions must be enabled in the kernel. wireless-tools must be reinstalled for the new kernel.


Retrieved from ""

Last modified: Mon, 06 Oct 2008 19:24:00 +0000 Hits: 293,087