Unsupported Version
This article applies to an unsupported version of Ubuntu. More info...

Wi-Fi WLAN wireless home networking information


The arcticle explains the very first steps to get a WLAN card running. It states what command line tools are required (i.e. lspci, ip, iwconfig) and what GUI tools are available (i.e. network-admin). Then it draws the way of setting up a WLAN card by starting at a unsecure configuration and continues to a WEP secured connection. It also presents a WLAN picker script (wlan-scan.sh) to automatically switch the wireless configuration, when accessing different WLAN networks. At end it refers to several related topics, such as roaming, trouble shooting and/or antennas/drivers.

Getting Started

Other places to find information here are

Also check this additional list of WiFi cards that are supported.

Obviously before you set up the wireless card on your computer you will need to become familiar with the basics of wireless and set up your wireless Router/Access Point. A good place to start is with the router documentation which often has a introduction to Wi-Fi. You will also probably have to look at the documentation to set up the Router. You may want to have a look at the Wi-Fi entry on Wikipedia or the technology overview of the Linux Wlan HOWTO however these are both a bit technical, it would be good if someone could find a simple newbie document and add it here. When you have got everything working you may want to have a look at NetworkManager and/or WirelessAssistant if you are planning on taking a laptop out and about and making ad hoc connections to wireless access points.

First thing you'll need to do is get the wireless-tools package (see SynapticHowto). Since this document is about how to get (wireless) networking working, we need an explaination here on how to install packages without a network connection!

sudo apt-get install wireless-tools

You will then have to find what chipset your card is (this is the chips the manufacturer uses, the make/model is of limited use as some manufactures use the same chipset and they also change the chipset without changing the model number). To do this in a shell type:

lspci | grep Network

One of the lines will tell you what chipset you have. It will be listed as a Network Controller. If it says something like unknown device, then Google for it.

Some Wi-Fi Cards work out of the box, specifically the ones with the Orinoko, Prism2 or Atheros chipsets (some Prism cards may not work out of the box).

  • For cards based on Ralink's RT2500 chipset, see WifiDocs/Driver/RalinkRT2500.

  • For cards based on Rakink's RT61 chipset see [Rt61WirelessCardsHowTo], these show up as 'Network controller: Ralink Unknown device 0301' if you do lspci.

  • If you have a Centrino based laptop, it likely has an Intel ipw2200 based card. It works out of the box but uses an ancient driver. See Luca_Linux's post for a really good guide on getting the ipw2200 card setup (you may want to stop before he takes you into the WPA portion of the setup). Some users have experienced problems with their wireless connections after upgrading to Hoary from Warty with the Intel ipw2200 (prior to upgrade in Warty everything worked fine). The following message on the mailing list is relevant: http://lists.ubuntu.com/archives/ubuntu-users/2005-April/029837.html One user reported having to remove the module and re-insert the driver once or twice before it can associate with the access point (on kernel linux-image-2.6.10-5-686).

  • For cards that do not work out of the box you can try WifiDocs/Driver/Ndiswrapper.

To begin with you'll need to set your Wireless Router up as an 'open' network. This means you'll need to turn off all security such as WAP, WEP and Mac Address restrictions. You'll be able to turn these back on later, we just want to make sure that they aren't causing any problems in the beginning.

You'll also need to give your network an ESSID. Most wireless routers have one set by default. Often it is "default", "linksys" "netgear" or some other generic name.

iwconfig Before You Start

(optional, but not a bad idea) Ubuntu ships with a fantastic GUI network tool called network-admin. It can be run from a terminal but it is also readily available under the system menu. (System)->(Administration)->(Networking). You can jump right in and start poking around with network-admin, but its best to run iwconfig from a terminal first. Since linux names your wifi card based on the driver it uses (can somebody back that up?) we first need to figure out what your card is called. Bring up a terminal (Applications)->(System Tools)->(Terminal) and issue the following command:


Your output should look like:

lo        no wireless extensions.

eth0      no wireless extensions.

sit0      no wireless extensions.

wlan0     unassociated  ESSID:off/any
          Mode:Managed  Channel=0  Access Point: 00:00:00:00:00:00
          Bit Rate=0 kb/s   Tx-Power:off
          Retry:on   RTS thr:off   Fragment thr:off
          Power Management:off
          Link Quality:0  Signal level:0  Noise level:0
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:0   Missed beacon:0

If all devices listed say "no wireless extensions." then your wireless card is not configured. You need to go back and get it setup. Please see the top of this document and also WifiDocs/Driver/Ndiswrapper for more information. Alternativly, the device may be disabled - you could try

sudo ip link set wlan0 up

you may also try to wake-up the interface using the keyboard command (Dell)

Then try iwconfig again to see if the device is now recognised.

Based on the iwconfig output from above, we know that "wlan0" is our WiFi card's linux device name. Knowing this you'll be able to use the Networking GUI tool to connect to your wireless router. (You may also see ath0 or even eth1 come up as your device name. Don't worry, that's totally fine, it just depends on the type of card you have and the drivers that are accessing it.)

Sometimes there are two devices that appear: wlan0 and wifi0, even if there is one card. This causes errors sometimes, like a tendency to not detect wireless access points. In certain configurations, this is caused by hostap_cs and hostap kernel modules. Check your dmesg output for errors around "wlan0". Place the appropriate excludes into /etc/modprobe.d/blacklist and reboot. An example workaround the wlan0 for the "orinoco" wifi driver:

ubuntu-7.10# gksu echo "blacklist hostap" >> /etc/modprobe.d/blacklist-orinoco
ubuntu-7.10# gksu echo "blacklist hostap_ap" >> /etc/modprobe.d/blacklist-orinoco

Click on (System)->(Administration)->(Networking) and see if your wireless network card is listed. If it isn't you've got a problem. (Somebody needs to describe what to do next) <!-- Is it possible for wireless interface to be in kernel and not be recognized by the GUI tool? If the tool is reliable we can reference user to troubleshooting a driver. -->

Using network-admin, the GUI Network Tool

As mentioned before Ubuntu ships with a fantastic GUI network tool called network-admin. It can be run from a terminal but it is also readily available under the system menu. (System)->(Administration)->(Networking).

Once it is launched you'll be presented with a list of network adapters that are available on your system. You should see an entry that named "Wireless connection" and just beneath it it may say "The interface wlan0 is not active". Your setup may not say "wlan0" however it should match the device name that we looked up in iwconfig above.

Since your card is listed in network-admin you can easily setup the network configuring. In network-admin select the Wireless connection entry and then click the Properties button.

This is where you actually specify the network to connect to. You should type the ESSID that you have assigned to your router into the box that says "Network Name (ESSID):". If we have disabled WEP at remote wireless router we can leave the WEP Key field blank. Normally Configuration can be left as Automatic (DHCP). Chances are you have set up your wireless router as a DHCP Server, if not do so (refer to Router documentation). Click on OK.

To test your new WiFi connection we should temporarily disable other network interfaces. Select the eth0 network and click on Deactivate button (if you have one - basically deactivate all Network cards other than the WiFi). Then select wlan0 (or whatever your wireless card is called) and click on the Activate button. You should end up with the checkbox under Active for wlan0 checked and the others not checked. You can now fire up a web browser and see if you can browse the web. Alternatively the best way of checking if you have a working internet connection is to use ping which checks that a domain exists and can be reached (think SONAR ping, but for networks). Open a terminal and type:

ping -n -c 4

This will send out 4 pings to the internet address

Your output should look something like:

PING ( 56(84) bytes of data
64 bytes from from icmp_seq=1 ttl=205 time={some value}
64 bytes from from icmp_seq=2 ttl=205 time={some value}
64 bytes from from icmp_seq=3 ttl=205 time={some value}
64 bytes from from icmp_seq=4 ttl=205 time={some value}

If it doesn't and you get statements saying "Destination host unreachable" or "request timed out", then you've got a problem and you aren't connected. (somebody should write some instructions on what to do next). (Possibly see WifiDocs/WirelessTroubleShootingGuide and WifiDocs/WiFiTroubleshooting.)

If you do get the results listed above then you are able to ping an internet address and your wireless card is working. Next you'll want to try a domain name. Lets go with google:

ping google.com -c 4

Your output should look something like:

PING google.com ( 56(84) bytes of data
64 bytes from from icmp_seq=1 ttl=205 time={some value}
64 bytes from from icmp_seq=2 ttl=205 time={some value}
64 bytes from from icmp_seq=3 ttl=205 time={some value}
64 bytes from from icmp_seq=4 ttl=205 time={some value}

If your first ping to worked and your ping to google.com doesn't (ie: you get "unknown host") then something is wrong with your DNS. (somebody needs to describe what to do next).

If both pings work then you can be pretty sure that your network is running. Fire up your favorite web browser and surf off to your favorite site. Everything should be good.

Using the command Line

If you can browse the web your card is set up and working. If not we can try doing it another way. Start a Terminal Window and type

ip link set

This will list your network interfaces. The wired network interface is normally called eth0. Stop this network by typing

sudo ifdown eth0

do this for all networks except for 'lo'. Then start your wireless network by typing

sudo ifup wlan0

Check this has worked by typing ip addr and if all is well try browsing the Web/ping. If it is not try the following

iwconfig wlan0 mode managed
iwconfig wlan0 channel 11
iwconfig wlan0 essid networkname

mode managed is what you want if you are connecting to a wireless router. The channel and esidd will have to be set the same as your router.

You have your network working but it is an open/unsecure network. Refer to your Router documentation to find out how to set up a secure network. Each Network card (either wired or wireless) has a unique number called a Mac Address. Most wireless routers allow you to restrict the Mac Addresses that can connect to them. To find out your Mac Address type

ip addr

This is listed as the first line after !HWaddr.


It is also good to set up encryption (we will use WEP encryption as it is well supported in Ubuntu) as Mac Address restricting can be circumnavigated. Firstly you will have to set up your router to use WEP encryption. This the rest of this paragraph is a bit vage as a different routers work slightly differently but should give you an idea. Refer to your router manual but WEP setup should be under something like wireless->security on the web interface of your router. Generally you then enable WEP security and choose a key size. The bigger the better but the example here is using 64 bit (sometimes referred to as 40 bit) keys. Generally you can then type a Passphrase (a password but you should use a few words next to each other). Generally you then click on something like Generate and several keys (normally 4) are created. One of them will be marked as the default key, this is the one we will use.

There is a field under Network Name (ESSID) in Computer->System Configuration->Networking->(wlan0) Properties. The idea is that you put your key here but I can't get it working. What I have managed to get working is typing

sudo iwconfig wlan0 key FEFEFEFEFE

Where FEFEFEFEFE is the WEP key in hexadecimal. Hexadecimel uses 0-F rather than 0-9 (This is base 16 with A representing 10 all the way up to F = 15 and then 10 representing 16.). This is the way all keys are specified. You should then be able to browse the web/ping. Not entirely sure but it seems sometimes you have to wait a minute or so for it to start working.

Adding it to /etc/network/interfaces

/etc/network/interfaces is the file where your network interfaces are defined, eth0 being the standard wired interface. To make the wireless network come up when you start your computer put # in front of 'auto eth0' (to stop it automatically starting) and add something like the following lines.

sudo nano -w /etc/network/interfaces

auto wlan0
iface wlan0 inet dhcp
wireless-essid   MYNETWOTK
wireless-key     FEFEFEFEFE
wireless-channel 11
wireless-mode    managed

Automatic WLAN Picker Script

I have written a small script to have my laptop automatically pick a WLAN network of several configured. It uses the wireless utils to scan for known/open networks on "ifup interface". The script wlan-scan.sh looks like this:


ip link set $IFACE up

SCAN=$( \
iwlist $IFACE scan 2>&1 | grep -v "^$IFACE" | grep -v "^$" | \
    sed -e "s/^\ *//" \
        -e "s/^Cell [0-9]\+ - /#/" \
        -e "s/^#Address: /#AP=/" \
        -e "s/^Quality:\([0-9]\+\)\/.*$/QUALITY=\1/" \
        -e "s/^.*Channel \([0-9]\+\).*$/CHANNEL=\1/" \
        -e "s/^ESSID:/ESSID=/" \
        -e "s/^Mode:/MODE=/" \
        -e "s/^Encryption key:/ENC=/" \
        -e "s/^[^#].*:.*//" | \
    tr "\n#" "|\n" \

ip link set $IFACE down

while read glob scheme; do
    AP=""; QUALITY=""; CHANNEL=""; ESSID=""; MODE=""; ENC=""
    for i in $SCAN ; do
        for j in $(echo $i | sed -e "s/|/ /g" ) ; do
            case $j in

        case "$AP,$ESSID,$ENC,$MODE,$CHANNEL" in
                echo $scheme
                exit 0

exit 1

and is used with the mapping primitive of the interfaces file.

Mine looks like this:

mapping wlan0

        script /path/to/wlan-scan.sh
        # Accesspoint,"ESSID",Encryption,Mode,Channel
        map 00:FE:FE:FE:00:00,"MY_NET",*,*,* wlan0-home
        map *,"COMPANY",on,Master,*          wlan0-office
        map *,*,off,Master,*                 wlan0-open

iface wlan0-home inet dhcp
        wireless-essid HOMENET
        wireless-mode managed
        wireless-enc FEFEFEFEFEFE

iface wlan0-office inet dhcp
        wireless-essid COMPANY
        wireless-mode managed
        wireless-enc s:Secret_password

# This is a fallback, selected for all unencrypted WLANs
iface wlan0-open inet dhcp
        wireless-essid ANY
        wireless-mode managed

Please report if this does not work for you (or if it does;-).

Note: The iwlist scan command only works with certain chipsets and hence this script may not work for all wireless adaptors

Wi-Fi roaming

Wi-Fi is most useful on a laptop. Taking your laptop everywhere also involves changing networks quite often. It is quite bothersome having to change this every time you want to hook up to a different network.

To solve this a number of programs have been developed that automatically bring up your wireless network interface when a network has been detected. The older encryption method WEP has been superseded by WPA. For setting up WPA, see the the description of setting up wpa_supplicant in the WifiDocs/WPAHowTo. However wpa_supplicant still has issues with some drivers. Especially roaming between old WEP networks isn't well supported with wpa_supplicant, therefore has a look at the older waproamd.

Some people might prefer a script to do network switching, have a look at:

Other people might prefer a GUI tool to do network switching though, have a look at:


See https://help.ubuntu.com/community/WirelessTroubleshootingProcedure

See "WifiDocs/WiFiTroubleshooting".

Useful info

From JBBell Sat Apr 16 18:26:15 +0100 2005 From: J B Bell Date: Sat, 16 Apr 2005 18:26:15 +0100 Subject: WEP key Message-ID: <20050416182615+0100@https://www.ubuntulinux.org>

You can also use a text-based key if you prepend it with "s:", both in the graphical interface and in the /etc/networking files.

From SoniaHamilton Sat Apr 23 04:56:37 +0100 2005 From: Sonia Hamilton Date: Sat, 23 Apr 2005 04:56:37 +0100 Subject: May need to install linux-restricted-modules Message-ID: <20050423045637+0100@https://www.ubuntulinux.org>

You may need to install linux-restricted-modules-* to get wireless going (Atheros chipset, under Hoary)

From samtygier Tue May 17 16:05:01 +0100 2005 From: sam tygier Date: Tue, 17 May 2005 16:05:01 +0100 Subject: ip address ? Message-ID: <20050517160501+0100@www.ubuntulinux.org>

whos ip address is this? do they mind being pinged, by people who want to check whether their dns is work? should we put the ip addess of the ubuntu homepage, or google or something else?

From WoutervanWijk Thu May 19 17:55:54 +0100 2005 From: Wouter van Wijk Date: Thu, 19 May 2005 17:55:54 +0100 Subject: gui key entry Message-ID: <20050519175554+0100@https://www.ubuntulinux.org>

I saw this about the gui wep-key entry (here http://www.ubuntulinux.org/support/documentation/faq/helpcenterfaq.2004-10-07.0031507315): One detail that was essential for me to get my laptop running on a Linksys WRT54G router: when you generate a WEP key that is 10 digits long (XXXXXXXXXX), you cannot just copy and paste this key into the WEP key field within the Network Settings dialogue. You must insert a dash after every fourth character, ie, XXXX-XXXX-XX. Once you do this, WEP encryption works fine.

This script is great! It should come standard with Ubuntu. Very out of the way and allows you to keep configuration in /etc/networking/interfaces.

The wlan-scan.sh looks really nice. However, it doesn't like ESSIDs with spaces in them, so I had to specify the MAC address of the access point insted of the ESSID because when I specified "WG 2 OG" in the map line, ifup would just complain it couldn't bring up the unknown interface eth1=eth1 or something like that.

CategoryNetworking CategoryWireless

WifiDocs/WiFiHowTo (last edited 2011-05-27 17:06:39 by vpn-2079)