Wireless Tools for Linux

The Wireless Extension is a generic API allowing a driver to expose to the user space configuration and statistics specific to common Wireless LANs. The beauty of it is that a single set of tool can support all the variations of Wireless LANs, regardless of their type (as long as the driver support Wireless Extension). Another advantage is these parameters may be changed on the fly without restarting the driver (or Linux).

The Wireless Tools is a set of tools allowing to manipulate the Wireless Extensions. They use a textual interface and are rather crude, but aim to support the full Wireless Extension.

• iwconfig manipulate the basic wireless parameters
• iwlist (formerly part of iwspy) allow to list addresses, frequencies, bit-rates...
• iwspy allow to get per node link quality
• iwpriv allow to manipulate the Wireless Extensions specific to a driver (private)

Modern versions of the Pcmcia package offer the possibility to set up various wireless parameters at boot time (or card insertion time) through the file wireless.opts. This allow to fully integrate wireless settings in the Pcmcia scheme mechansism. This of course require that the above wireless tools are installed on the system.

Please note that the Wireless Tools (as of version 19) supports fully IEEE 802.11 parameters and devices, support older style of devices and most proprietary protocols, and are prepared to handle HiperLan as well.
Version 20 adds some pretty nice features, like mode of operation, power saving settings and encryption setting.
But, unfortunately not all drivers support all these features...

Version 23 adds :

• Fix a problem when trying to use iwspy before the interface is configured
• Add missing commands in the iwlist man page
• Fix "make install" and install man pages
• Automatic glibc/kernel header configuration
• Nicer iwconfig error messages
• Add "iwconfig ethX commit"

Version 22 adds :

• Fix minor bugs in parsing command line
• Most basic functions of the tools available as a library (libiw)
• Add a few extra wireless statistics

Version 21 adds :

• Improved power management support
• Transmit Power parameter
• Document wireless.opts and Pcmcia scheme usage (multi cards, multi setups)
• Better Makefile, header options can be set there
• Support for GLibc2.2
• Check Wireless Extension version mismatch
• Retry settings
• Split iwspy into iwspy and iwlist

Version 20 was already adding :

• Operation mode support (managed/ad-hoc)
• Power saving support
• New encryption support

However, the version 20 and later don't work for older kernels (prior to 2.2.14 and 2.3.30), for those kernel I recommend to use version 19, which is also very stable (but with less features).

Both may be found on the Pcmcia ftp server, in the contrib directory :

• Download the wireless tools package

In case of trouble, you can fetch also from here version 19, version 20, version 21, version 22 and version 23, but be gentle on this server...

The latest beta version adds support for Wireless Events and Scanning, and some bug fixes from Pavel Roskin. This is still a work in progress (some things need fixing) and to use the new features it requires the new driver API patches (aka Wireless Extensions v14).

• Wireless Tools version 24-pre3 (beta)
• A patch to update your kernel to Wireless Extensions 12.

I'm currently working on a new driver API for the Wireless Extensions. First phase is frozen and almost merged with Linus, second phase is now stable and pending some reviews... Anyway, the patches are there...

If you want to try it and apply those patches to your kernel, you need to do it in sequence. My kernel is 2.5.3-pre3, and I'm using the orinoco driver version 9b. If you use other versions, it may be more work (the kernel patches should be ok, the orinoco patches will be problematic).

Note that if you don't care about old obsolete drivers (wavelan, wavelan_cs and netwave_cs), you can skip many patches (like all the preliminary phase).

Also, as usual, it may crash or eat your hard drive. But it would not be fun otherwise...

1. Preliminary phase : move a few drivers around
   • Update wavelan_cs to v23 : backport Pcmcia package fixes in the kernel. [Already in 2.5.3-pre2]
   • Shell script and Patch to move old wireless drivers : move wavelan.c, wavelan_cs.c and netwave_cs.c to driver/net/wireless. [Already in 2.5.3-pre3]
   • Additional fixed for wavelan_cs : fix trigraph warnings.
2. First phase (Wireless Extensions v13) : replace ioctl handler by iw_handlers in drivers.
   • Some comments on the new driver API.
   • Core of the new driver API (handle iw-handlers ;-). [Already in 2.5.3-pre3]
   • Conversion of the old Wavelan driver version 23 to the new API.
   • Conversion of the old Wavelan_cs driver version 23 to the new API.
   • Conversion of the Netwave_cs to the new API.
   • Conversion of the Orinoco driver version 0.9b to the new API.
3. Second phase (Wireless Extensions v14) : add driver and set events through rtnetlink and scanning support. Note : still work in progress, but at least now things are stable and documented...
   • Wireless Event dispatcher for the new driver API.
   • Add some Wireless Events and Scanning to the Orinoco driver.
   • To be able to use the new features, you will need Wireless Tools version 24-pre3

I've written a small document describing the use of Pcmcia schemes and wireless.opts.

Some driver documentations (man page, web, README) describe what the driver support in term of Wireless Extension and how the various Wireless Extension parameters map to the capability of the card.

The Linux Wireless LAN Howto contains a section about the Wireless Extensions, but it's a bit out of date for the details...

I have also the following erratas and comments :

• In the rare cases where your kernel isn't compiled with Wireless Extensions (/proc/net/wireless non-existent), you need to recompile it with Wireless Extensions (CONFIG_NET_RADIO enabled).
• After recompiling a kernel with Wireless Extension, you have to recompile your driver or the Pcmcia package as well (and restart it).
• Compilation of the Wireless Tools is tricky, especially in the header area. I don't have any bullet-proof solution right now, but please play with the constants in iwcommon.h... For the latest version, this has moved in the Makefile.
• For kernels before 2.2.14/2.3.30, use Wireless Tools version 19.
• For kernel after 2.2.14/2.3.30 use Wireless Tools version 20 or greater.
• The tools are supposed to be GPL. Version 21 and above has the proper licensing info...

• iwconfig says "no wireless extensions."
  1. Enable the config option CONFIG_NET_RADIO in your kernel setup.
  2. Recompile and reinstall this kernel.
  3. Recompile and reinstall the kernel modules.
  4. Do cat /proc/net/wireless. If the command returns an error, you are using the wrong kernel. Try again.
  5. If you are using Pcmcia, go into the Pcmcia package, do a make config
  6. Check that the following line appears : "Radio network interface support is enabled.".
  7. Recompile and install the Pcmcia package.
• iwconfig still says "no wireless extensions.", displays garbage or crashes before displaying anything.
  1. Make sure you have fully checked all the steps of the first question.
  2. The driver or driver version you are using probably does not support Wireless Extension.
  3. Check the list below.
  4. If your driver is listed, try a more recent version.
  5. If your hardware is listed, try the driver mentionned (there may be multiple of them - see also the Howto).
  6. Make sure that Pcmcia is loading the driver you think it is loading. Hack the various files in /etc/pcmcia/ until it loads the correct driver (grep is your friend).
  7. If you still can't get it, or if you find no suitable driver, complain to the driver maintainer.
• I try to change a specific parameter with iwconfig, it just returns an error message
  1. Check reading parameters and setting other parameters.
  2. If setting all parameters fail, see first two questions.
  3. No card support the full range of Wireless Extension, so your hardware or firmware may not have this feature.
  4. Check the Windows driver and card documentation to see if the feature exist.
  5. Then, your driver or your driver version may not export this particular feature. Try the latest version.
  6. For driver with otherwise rich support, it's more likely a hardware limitation. For driver with limited support, it might be a driver limitation.
  7. Check the driver documentation to see if the feature is supported.
  8. Lastly, ask the maintainer if it is a hardware, software or documentation limitation and what to do about it.
• I change stuff in wireless.opts, nothing happens
  1. Check that the MAC address prefix of the definition matches the MAC address of your card (with ifconfig).
  2. Check that no other previous definition would match your card (the first matching section is used, "*" matches everything).
  3. In particular, make sure that you have either commented or removed the "*,*,*,*)" at the top of wireless.opts.
  4. Check the scheme matching and the scheme you are currently using (with cardctl scheme).
  5. Restart the Pcmcia card manager.
  6. Check you system logs for error messages.
• My config in wireless.opts is still ignored, and I have no error message in the system log
  1. You are using Red-Hat configuration scripts (or similar). Those scripts don't support properly Wireless Extensions.
  2. File a bug report with your distribution.
  3. Reinstall standard Pcmcia scripts, especially /etc/pcmcia/network.
• When I set my configuration in wireless.opts, it complains in the system log that it can't find iwconfig
  1. Install Wireless Tools somewhere on the system, like in /usr/local/sbin
• When I set my configuration in wireless.opts, I've got weird errors in the system logs
  1. Run iwconfig. See first two questions.
  2. Try to set the equivalent parameters directly using iwconfig to make sure that you get the syntax right and that the card support those.
• iwconfig crashes after displaying valid info...
  1. Do cp /usr/src/linux/include/linux/wireless.h /usr/include/linux
  2. Recompile and reinstall the wireless tools
• iwconfig complain that the card/device uses a different version of Wireless Extensions
  1. Do cp /usr/src/linux/include/linux/wireless.h /usr/include/linux
  2. Recompile and reinstall the wireless tools
  3. If you still have this message after this, your driver need fixing...
• When compiling the Wireless Tools, it recommends to update my kernel and/or system headers
  1. If you don't have any of behaviours decribed in the two questions above (crash/message at runtime), you are fine... Don't worry...
  2. If you are on the adventurous side, you may update the kernel and the system header with the copy in the Wireless Extension package. However, some drivers may not cope with that...

• The Wavelan driver is the reference implementation of Wireless Extensions for pre-802.11 devices. It supports NWID, Channel, Sensitivity, Encryption key, stats and spy.
• The new Orinoco MPL/GPL driver is the reference implementation of Wireless Extensions for 802.11 devices. In particular, it supports ESSID, Frequency, Frag, RTS, Rate, Operation Mode, Power management, Encryption settings (all four keys), stats and spy.
• The old Wavelan IEEE GPL driver is similar to the Orinoco MPL/GPL driver, but not as much up to date...
• The Wavelan IEEE binary driver (from Lucent) has limited support for Wireless Extensions (stats, channel), and as this driver have some strong similarities with the previous one, somebody should do something about it...
• The Netwave Airsurfer driver has the essential : Domain, Scrambling key, Mode and stats.
• The Proxim RangeLan2 driver has solid support for Wireless Extensions : Domain, channel and stats. More recent versions may add mode of operation.
• The Aironet driver (version 1.4 and later from Ben) has some extremely complete support for Wireless Extensions, including ESSID, Frequency, Frag, RTS, Rate, Operation Mode, Power management, Encryption settings (all four keys), stats and spy.
• The Symbol Spectrum24 driver supports only ESSID (so far).
• The Samsung MagicLAN driver support of Wireless Extensions is a clone of the Wavelan IEEE. It should support ESSID, Frequency, Frag, RTS, Rate, and stats, however it seems that some settings are not fully fonctional.
• The Raylink driver has a quite complete support of Wireless Extensions (ESSID, Frag, RTS, Mode, Rate, stats, spy) but the majority of them read-only for now. I have made a patch for ray_cs to enable to write all Wireless Extensions while using wireless.opts (patch for the kernel or for the Pcmcia package).
• The Swallow driver has the essential : ESSID and Encryption. The support for encryption is very complete.
• The Poldhu driver has similar support to the Swallow driver..
• The Linux-wlan-ng driver version 0.1.13 support Wireless Extensions, thanks to the work of Reyk Floeter. The support is currently pretty basic, but you will improve that ;-)

The first set of application are applications that make use of Wireless Extensions :

• Download my wireless tools package (iwconfig, iwspy, iwpriv).
• The Pcmcia package uses wireless tools for integrated wireless setting in wireless.opts.

• Stefan Winter has developped KOrinoco, a very complete set of KDE tools using Wireless Extensions (configurator, link monitor - not Orinoco specific).
• Sujal Shah has developped GWireless, a Gnome link monitor and configurator for 802.11b cards using Wireless Extensions.
• Jan Morgenstern has written wavemon, a very nice curses application to monitor your card using Wireless Extensions.
• Green Bay Professional Packet Radio has a modified version of my Wireless Tools for the Symphony, with nice colors and bar graphs, to allow better setup of Wireless Links.
• Luis Peralta has written a web based Wireless Configurator and a Link Quality Checker, which are perl wrappers around my Wireless Tools.

• Tobias Rundström did wvlanmon, a link monitor for Gnome using Wireless Extensions.
• Mark C. Langston has developed a very nice Enlightenment epplet, E-Wireless, that monitor link quality, of course using Wireless Extensions...
• Carsten Schuermann has developed a very nice Window Maker dockapp, WMWave, that monitor link quality, signal strength and noise level.
• Gtnx Sjoerd has developped a signal strength plug-in that fits into the GKrellM monitoring system.
• Trent Trautman has developped a signal strength plug-in that fits into the Entity XML framework.
• Tim Ehlers has modified xosview to monitor the wireless link.
• Jim Binkley has developped a wireless signal strength monitor. The Linux version uses the Wireless Extensions and has been designed for the iPaq.
• David Koski has written a Java Applet to monitor the Wireless Link.

• Steven Hanley has developed a small package using Wireless Extensions to get the statistics at the other end of the wireless link (remote stats), with a nice graphical user interface, and which can be docked in your window manager.
• Eric Maland and friends have developped a package to log discovered ESSID (and related info) of wireless networks in range.
• Moustafa Youssef has developped a general API for interfacing with Wireless Extensions.

• Jim Binkley has developed a version of Mobile IP which is wireless aware. His Linux implementation uses the Wireless Extensions...

• Open1x is an Open Source implementation of the 802.1x protocol that uses Wireless Extensions.

• Jon Sevy has developped a Java-based AirPort/RG1000 Base Station configurator, that should please some people not owning a Mac... He has also done Wireless Link Test Utility and a Wireless Host Monitoring Utility for the Airport/RG1000.
• Johan Almqvist has developed a perl script to configure a D-Link DWL-1000AP Access Point via SNMP.
• Sujal Shah is writting a Gnome application to configure a Linksys WAP11 Access Point via SNMP.
• Roman Festchook has writen a ncurses based utility to configure Access Points based on Atmel chipset via SNMP protocol (the case for most Intersil clone vendors).

• Mark C. Langston has written some Perl script to check the status of the Airport Base Station.
• Tom Z. Meinlschmidt has developped an impressive package allowing to monitor a Wavelan Access Point using SNMP.
• Greg Hankins has done a similar monitor for the RoamAbout Access Points.
• V.Melnik has developped a package to monitor a Wavelan Access Point using SNMP and store the result in a mySQL database.

• Kirby Kuehl has developped a package discovering Wireless Access points from their wired side. It basically check MAC address that match known Access Point manufacturers.
• Jan.B.Fernquist has developped PrismStumbler, discovering networks in ranges with PrismII cards.

• The NetPerf benchmark. That's the one I use, and I love it !
• MRTG seems an interesting tool to monitor the quality of TCP links (I need to try it...).

Wavelan, Orinoco and Wireless LANs - jt@hpl.hp.com Updated 10 August 01

Project hosted and sponsored by :