A big FAT warning:
-----------------

A bugreport (see http://bugs.debian.org/367790) says that the driver
leaks some memory if put to monitor mode and stressed by kismet.
This can be done only by the root user, so this should not worry most users.

A quick FAQ:
-----------

Q: Where are precompiled module packages for this new kernel image released
   yesterday?
A: Every set of new precompiled module packages for a new kernel release
   must be manually approved by the ftp masters. This process may take up
   to one week. Please do not pester them or me in the meantime. 
   
   I do occasionally miss kernel releases so if it seems that I have not
   noticed a new kernel release and built drivers for it, check the bug
   tracking system at <http://bugs.debian.org/linux-wlan-ng> and if there
   is not yet a bug, file one.

   Failing all else, you can use the instructions later in this file to
   build linux-wlan-ng modules for your kernel.

Q: Why do I get messages from /etc/network/if-pre-up.d/wireless-tools
   when I bring up the interface?
A: The warning messages, such as this one, are harmless:

    Error for wireless request "Set ESSID" (8B1A) :
      SET failed on device wlan0 ; Invalid argument.
      run-parts: /etc/network/if-pre-up.d/wireless-tools exited with return code 251
    
   See bug #154367 for details. You can apply this patch to shut up
   /etc/network/if-pre-up.d/wireless-tools, this patch will hopefully be
   applied by the maintainer of wireless-tools in the near future.

--- wireless-tools.orig 2003-03-06 13:22:32.000000000 -0500
+++ wireless-tools      2003-03-06 13:30:08.000000000 -0500
@@ -7,6 +7,14 @@
   exit 0
 fi

+# Detect and do nothing for linux-wlan-ng interfaces;
+# which are configured by their own if-pre-up script.
+if [ -x /sbin/wlancfg ]; then
+  if /sbin/wlancfg show $IFACE >/dev/null 2>&1; then
+    exit 0
+  fi
+fi
+
 if [ -n "$IF_WIRELESS_SENS" ]
 then
   ARGS="$ARGS sens $IF_WIRELESS_SENS"

Q: How can I set the "nick" displayed by iwconfig?
A: You cannot, linux-wlan-ng does not have a concept of a "nick".
   iwconfig will always show it being set to your ESSID.
   Don't worry, it's fairly useless anyway.

Q: Who do I get unresolved symbol/depmod warnings/errors when I install the
   package or boot?
A: If is is complaining about prism2_cs, you probably don't have a ds.o
   module available. You can ignore this if you don't need PCMCIA support
   for linux-wlan-ng. If you do need it, you should try installing
   whichever kernel-pcmcia-modules-* package is Suggested by the 
   linux-wlan-ng-modules-* package you've installed. If it is complaining
   about unresolved symbols in something else, and you are using the
   precompiled modules packages, file a bug report.

Q: Where is the rest of the documentation?
A: A lot of the documentation, including the main FAQ and README file is in
   the linux-wlan-ng-doc package, in the directory
   /usr/share/doc/linux-wlan-ng-doc

Kernel modules:
--------------

To get linux-wlan-ng working on your system, you need to install the
linux-wlan-ng kernel modules. I try to provide precompiled kernel modules
for the stock debian kernels, but these may from time to time be out of
date. The precompiled packages are named
linux-wlan-ng-modules-<kernel-version>-<cputype>, for example,
linux-wlan-ng-modules-2.4.25-1-k7, and will depend on the particular kernel
image they were built for.


Building kernel modules for stock debian kernels:
------------------------------------------------

Run m-a in order to build linux-wlan-ng-modules.

If you want to choose which type of modules will be built. You have to :

$cp /usr/src/modules/linux-wlan-ng-source/debian/config-for-lwng /usr/src/modules/linux-wlan-ng-source/debian/config-foo

Edit this new file choosing the modules you want to build, for example, if 
you want to build only the usb driver:

# /usr/src/modules/linux-wlan-ng-source/debian/config-foo 
# This script is sourced by the Configure script, when running in
# noninteractive mode.

if [ "$BUILD_MODULES" = "n" -o "$BUILD_UTILS" = "n" ] ; then
        # Just building the utilities. Kernel source may not be present;
        # don't fail.
        fail () {
                echo "Not failing since we are building only the utilities"
        }
fi

LINUX_SRC=$KSRC
PCMCIA_SRC=$PSRC
PRISM2_PCMCIA="n"
PRISM2_PLX="n"
PRISM2_PCI="n"
PRISM2_USB=$BUILD_MODULES
UTILS=$BUILD_UTILS
TARGET_ROOT_ON_HOST=$(pwd)/debian/tmp/
#EOF 

Configuring linux-wlan-ng:
--------------------------

Once you have the kernel modules built and installed, you must configure
linux-wlan-ng to bring up your network interface with the proper wireless
parameters for your network. The way this is done currently depends on the
type of wireless device you have, be it a pcmcia device, a USB device, or
a built-in PCI device.

In most cases you can use a network configuration GUI tool provided by your
desktop environment, for instance network-manager or network-admin in GNOME.
If you however want to configure the network interfaces manually, read on.

Configuring a pcmcia device:
---------------------------

Debian is moving away from using the old pcmcia scripts, and toward using
/etc/network/interfaces to set up pcmcia interfaces as well. Therefore,
unless you edit /etc/pcmcia/network.opts and set an IP address or tell it
to use a dhcp client or bootp, it uses ifup and ifdown to configure the
interface. The same holds true for wlan-ng, and you can follow the
instructions below for setting up /etc/network/interfaces.

However, if you do choose to configure /etc/pcmcia/network.opts, you should
also edit /etc/pcmcia/wlan-ng.opts.

Note that a few cards that are supported by the regular pcmcia drivers are
commented out in wlan-ng.conf, to make sure that installing this does not
break existing set-ups. If you're brave you can try uncommenting them to
use the wlan-ng drivers for them.

Configuring a PCI or USB device (or a pcmcia device) with /etc/network/interfaces:
--------------------------------------------------------------------------

Edit /etc/network/interfaces, and add a stanza for your network device.
Here is a sample stanza, for the simplest possible configuration -- bring
the device up, associating with any available wireless access point, and
use dhcp to get on the network:

auto wlan0
iface wlan0 inet dhcp
	wireless_mode managed

Once you've edited this into /etc/network/interfaces, the command 
"ifup wlan0" should bring up your wireless.

More complex configurations are of course possible. For a ad-hoc network,
using static IP addresses:

auto wlan0
iface wlan0 inet static
	address 192.168.1.5
	gateway 192.168.1.1
	netmask 255.255.255.0
	wireless_mode ad_hoc
	wireless_essid mywlan
	wireless_channel 1

Here is an annotated list of all the available options (also see
interfaces(5) for more details):

# Should be either ad_hoc or managed. Used managed if you have an AP.
	wireless_mode managed
# Leave this unset to associate with any access point. Set to pick an
# access point, or in ad-hoc mode.
#	wireless_essid
# For ad-hoc mode, you must specify a channel.
#	wireless_channel 1
#
# To enable WEP, uncomment the next line.
#	wireless_enc on
# To set a WEP key, either use a string, which will be converted to a key:
#	wlan_ng_priv_genstr foo
# (Using the specified key length.)
#	wlan_ng_priv_key128 false
# Or give a file that contains such a string:
#	wlan_ng_keyfile /etc/network/wlan
# Or set keys explicitly.
#	wlan_ng_key0 xx:xx:xx:xx:xx
#	wlan_ng_key1 xx:xx:xx:xx:xx
#	wlan_ng_key2 xx:xx:xx:xx:xx
#	wlan_ng_key3 xx:xx:xx:xx:xx
# If you set a key, remember to make the file mode 600!
#
# In managed mode, set to "sharedkey" if a shared key is required.
#	wlan_ng_authtype opensystem
# If you are serving as an AP, uncomment this to require WEP for all STAs.
#	wlan_ng_exclude_unencrypted true
#
# Some extra ah-hoc mode settings:
# Beacon interval (in Kus)
#	wlan_ng_bcint 100
# Rates for mgmt&ctl frames (in 500Kb/s)
#	wlan_ng_basicrates 2 4
# Supported rates in BSS (in 500Kb/s)
#	wlan_ng_oprates 2 4 11 22
#
# You can set arbitrary MIB items with this directive, separated by
# whitespace. Each will then be set.
#	wlan_ng_user_mibs p2CnfRoamingMode=1

Configuring things the upstream way:
-----------------------------------

Some of the above is Debian specific. If you prefer to do things the way
it's documented in the non-Debian-specific documentation (which is in the
linux-wan-ng-doc package), you can do that too. The init script is shipped
in /usr/share/doc/linux-wlan-ng/examples/; copy it to /etc/init.d/wlan and
the result should be nearly identical to installing this package manually
from source.
