Cisco Aironet Linux Driver and Utilities Release 1.6

Part 1) - File identification:

The archive this file was contained in, should have contained the following:

driver/airo.c		main driver file, v2.0.0
driver/airo_cs.c	card and socket services loader for airo.c
driver/mpi350.c		mini pci driver (not PCMCIA)
driver/aes.h            support header file for airo and mpi350
driver/aestab.h         suoport header file for airo and mpi350
driver/DRVRBUILD        shell script for building stand alone airo and mpi350
                        driver

utilities/acu		Aironet Client Utility + Client Encryption Manager
utilities/bcard		command line card re-configuration utility
utilities/leaplogin	X Window utility for configuring LEAP credentials
utilities/leapset	utility for configuring LEAP credentials from command line
utilities/leapscript	utility for configuring LEAP credentials from shell script
			(warning - requires passwords in cleartext in scripts)
helpml.tar.gz		ACU's HELP pages
readme.txt		This file
config.350		A modified version of the /etc/pcmcia/config file to allow
			detection and usage of 350 series cards with c&s prior
			to version 3.1.26
ethX.cfg		A default radio configuration file placeholder,
			pre-configured for 30mw operation.

Red Hat 7.1 specific files:
redhat71/binaries/	pre-compiled binary versions of the driver
redhat71/redhat.1	Red Hat 7.1 specific script for installation method #1
redhat71/redhat.2	Red Hat 7.1 specific script for installation method #2
redhat71/redhat.3	Red Hat 7.1 specific script for installation method #3
redhat71/redhat71_cfg	Red Hat 7.1 specific replacement for /etc/pcmcia/config
redhat71/redhat71_pat	Patch for Red Hat kernel source to allow driver to be
			built as a module using the kernel pcmcia support that
			is enabled by default.  No kernel re-compilation needed.

Part 2) - Installation:

A bash shell script "cwinstall" has been provided to help install
the Cisco-Aironet driver and supporting utilities.
It will only run properly if executed as root since system level
changes need to be made.
To begin installation of the driver and utilities,  as root type:

sh ./cwinstall

Once the driver and utilities are properly installed - it is possible
to configure the radio as a normal user - by default.
If this is not desired - you will need to change the execute permissions
on the utilities (installed in /opt/cisco/bin) to 500.
The radio configuration is also stored in /etc/ in a file called ethX.cfg
where the X is the Ethernet adapter number of the wireless client card.
This is normally world writable to allow configuration by normal
non-root users.  If this is not desired - this will need to have it's
permissions changed also.

NOTE: Some distributions include their own pcmcia card and socket services
in their kernel source directories.
RedHat 6.2 for example includes an ancient version - 3.1.8 - this driver
has not been tested using that version - please use 3.1.26 at a minimum.

RedHat 7.1 includes pcmcia support in the 2.4.2-2 kernel by default.
RedHat 7.1 systems have three installation choices, with #1 being the
easiest and most recommended.

#1 - replace the stock /etc/pcmcia/config file with the supplied one
and use the supplied binary versions of the driver.
No compilation is needed, recommended for systems installed with the
"workstation" configuration.

#2 - patch the kernel source tree to allow the driver to be built as a module
with kernel pcmcia support.
This requires the presence of compilation tools, gcc etc., but does not
require the complete compilation/replacement of the installed kernel.

#3 - re-configure the kernel to not use built in pcmcia support, and
install pcmcia-cs.3.1.26 as usual.
This requires a complete kernel rebuild and installation.
This is probably the most advanced installation method.

For non-Red Hat 7.1 systems, or Red Hat 7.1 systems that will be disabling
kernel based pcmcia support, the standard method of building with
pcmcia-cs support will be used.

Assuming that the driver will be built along with the latest version of
pcmcia-cs card and socket services, the two driver files need to be copied
to the "wireless" subdirectory in the pcmcia-cs source tree.

Ex.  cp airo.c airo_cs.c pcmcia-cs-3.1.26/wireless

The installation scripts should handle this for you.
If the installation script does not work properly on your distribution
(unfortunately not all distributions have been tested)
you will need to manually compile the driver.

Normally - all that is needed is to copy the files as instructed above,
and then return to the root directory of the card and socket services
package and do a 

make all

If no errors were reported - then do a 
make install

Note:  versions of pcmcia-cs older than 3.1.26 did not have an entry
in /etc/pcmcia/config that recognizes the newer 350 Series radios.

If an older version of pcmcia-cs is used, the for those radios to be
recognized, after executing the "make install", copy config.350 in place of
the /etc/pcmcia/config file that is installed by default.

ex. cp config.350 /etc/pcmcia/config

This step will have to be repeated if another "make install" is done
in the pcmcia-cs source tree.


>PCMCIA
If you are using a pcmcia radio - the driver should automatically load
upon inserting the card.
However - the radio will be using a factory default configuration until
it is re-configured.  (See "bcard")

>PCI Carrier cards
RedHat and other distributions that use "linuxconf" should use that
utility to tell the OS that "airo.o" is to be loaded for the PCI card.

Users of other distributions should follow their distributions recommendations
on which startup files should load the driver.
Slackware distributions prior to 7.2 should probably add a line to the
end of /etc/rc.d/rc.modules to load the driver:

Ex.
cd /etc/rc.d
cp rc.modules rc.modules.bak
echo /sbin/modprobe airo >> rc.modules

Slackware 7.2 users can add that same line to /etc/rc.d/rc.netdevice.

Part 3) - Utilities:

* NOTE * The previous /etc/ethX.cfg files are not compatible with this version
of ACU and can cause problems if ACU finds them and tries to load them.
Please remove any old /etc/ethX.cfg files prior to running ACU for the
first time.


A total of five utilities are included with the driver:

acu - a close approximation in functionality of the windows setup utility
acu saves the current configuration of your radio as /etc/ethX.cfg, where
the X is the Ethernet adapter number of your wireless card.
The supplied default ethX.cfg file contains a power setting of 30mw for
compatability between 340 and 350 series radios.
This can result in an initial configuration error on 4500, 4800 and 4800A
radios, since they do not support 30mw operation.
In those cases, simply use ACU to select a legal power configuration.
350 Series users will also probably want to select a power setting other
than 30mw.
Commands->Edit Properties->RF Network->Transmit Power
(current version 1.6.7)

leaplogin - An X Window application for configuring LEAP credentials.
A graphical dialogue box will prompt you for your LEAP username and password.
(current version 1.5.1)

leapset - An interactive command line utility for configuring LEAP credentials.
This utility will prompt you for your LEAP username and password.
(current version 1.5.1)

leapscript - A non-interactive utility for configuring LEAP credentials
	designed for inclusion in shell scripts.
	* NOTE * In the shell script, the LEAP password will be in cleartext
	so ensure the permissions on the script are appropriate.
(current version 1.5.1)

bcard - this utility has no comparable windows equivalent, it's purpose is
to read the radio configuration(s) from the /etc/ethX.cfg file(s)
and configure the radio(s).
"bcard" has no required paramters, it will attempt to configure all detected
Aironet cards at once.
(current version 1.5.1)

This is most useful when inserted in a startup script such as:
/etc/pcmcia/network on a Red Hat system.
A slight delay to give the radio time to be properly powered up maybe
required.

An example of such usage is shown here in a snippet from a modified
Red Hat /etc/pcmcia/network file:


case "${action:?}" in
'start')
    #
    # We don't do *anything* here. We get a hotplug event when the ethX device
    # is registered, and we bring the device up there
    #
    # need to delay slightly to allow radio to stabilize
    sleep 2
    # now re-load the previous saved configuration
    /opt/cisco/bin/bcard
    ;;

Where is CEM?

CEM is no longer being shipped, it's functionality has been incorporated
into ACU.  Also, as with the Windows version of CEM, it now requires a password
to alter the WEP key configuration.
The default password, just like Windows, is "Cisco"

NOTE:  If you are using LEAP authentication - the LEAP credentials (username
and password) are volatile.  The credentials are NOT stored in the
/etc/ethX.cfg files and even though the radio maybe configured via
bcard to associate to an appropriate LEAP enabled AP - the radio will
not LEAP authenticate.

In this case, you will need to either manually re-run ACU and enter your
LEAP credentials via "command->Set Leap Information"
or use one of the LEAP credential utilities.
A good match for the "bcard" example above would be to add a line after
the call to "bcard" that calls "leapscript" with your LEAP username and
password.
Please observe the security notice above about file permissions.

Note - the LEAP username and password does not need to be the same as
a Linux user account ones - they may in fact be different.
See your LEAP admin for specifics.

Part 4) What's New?

CEM's functionality is now incorporated in ACU.

ACU has HTML help pages for almost every dialogue page.
(The help pages are contained in helpml.tar.gz which should be unpacked
in /opt/cisco by the installation scripts)

3 new LEAP credential utilities so running X is no longer required
simply to reconfigure your radio with a previous configuration.

What's been fixed?  Lots of major and minor bugs...

Not all of the minor bugs were ddts'd, these are/were the major ones.

CSCdu23206 - Can not do power saving in Ad hoc (firmware bug)
CSCdu26046 - No WEP = No Home Mode  (fixed)
CSCdu21973 - Ad hoc + LEAP = LEGAL (firmware bug)
CSCdu23096 - Could not start Ad hoc cell properly (fixed)
CSCdu24711 - No WEP = No LEAP (firmware bug)
CSCdt50553 - CEM corrupts WEP keys (fixed)
CSCdt50567 - ACU can not be configured to use shared keys (fixed)
CSCdt11136 - no online help (fixed)
CSCdt11139 - no LEAP credential setting outside of ACU
CSCdu03163 - 128-bit KEY not taking in Linux (fixed? see below)
CSCdt13558 - Linux driver will not compile/function under 2.4 (fixed)
CSCdt50574 - ACU defaults to shared key authentication in home mode (fixed)
CSCdu27714 - ACU Ghosts home encryption in ON position (fixed)
CSCdu27710 - ACU Ghosts shared key encryption in ON position (fixed)

(CSCdu3163, this bug report indicates a problem with setting WEP keys
via the /proc interface. At Cisco, we always use ACU/CEM for these
purposes, and recommend our utilities over the /proc interface configuration.
The /proc interface is not tested and very well maybe a problem with 128bit
keys)

The fact that the previously released utilities did not work
on a system running a 2.4.x kernel was ever ddts'd, but that
has been fixed, everything now works under 2.2.xxx systems and 2.4.xx ones.
Unfortunately they have been tested on 2.0.xx systems due to time constraints.

The firmware bugs apply to any OS that uses our cards, and their resolution
is dependent on a new release of client firmware in the near future.

What is still broken/missing?

* Inability to initially generate a /etc/ethX.cfg file w/out requiring X.

* Inability to configure the card for other than CAM mode.
(via ACU)

* ACU does not prompt you for LEAP credentials when they are missing.

* ACU does not display in the status window whether you are in "home" or
"enterprise" mode.

* ACU can not determine the version of the driver you are running and
display it in the status window like the Windows version can.
To determine what version of driver you are currently running,
use one of the following command lines:

For 2.2.xx systems:
cat /proc/aironet/ethX/Status | grep "Driver Version"

for 2.4.xx systems
cat /proc/driver/aironet/ethX/Status | grep "Driver Version"
(X = Ethernet adapter number of your wireless card)

* ACU does not have the Window's version's "auto profile select".

* Switching from LEAP to non-LEAP w/WEP enabled is a two step process
currently, since while in LEAP mode, ACU does not detect if the client
card contains permanent keys or not.
You currently must disable LEAP mode, "OK" out of the properties page,
re-enter the properties page, and then if you have keys, select "WEP".
But at least you don't have to reboot like you do in Windows ;-)

* A 4500 card can be attempted to configure for rates other than 1 & 2
mbit/sec, receiving a config error from the firmware.

* The help system currently can not determine if a browser is already
launched, and will always attempt to launch one itself.
However, it can detect an instance of the browser launched by itself, which
is why it does not open a new browser for every help document.

* ACU stores various configuration settings (not for the card) in
"/opt/cisco/ACU.PRFS".
ACU does NOT verify that this file was created by the current version of ACU.
When upgrading to newer versions of ACU, it is best to delete this file
(if it exists) prior to running the new version of ACU.

When in doubt, to ensure the radio is reset to default known state:
Exit ACU
rm /etc/ethX.cfg
if using a PCI carrier card, reboot your system, if using a pcmcia
card eject and re-insert the card.

This will ensure that your card is in it's initial power-up state when
you next run ACU.

(ethX.cfg, X = Ethernet adapter number of your wireless card)

