From 1c21d58786e11abe05a9632def2ffb087d6447c4 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 16 Oct 2003 23:00:13 +0000 Subject: documentation added git-svn-id: file:///home/lennart/svn/public/waproamd/trunk@22 022f378f-78c4-0310-b860-d162c87e6274 --- doc/README.html.in | 192 ++++++++++++++++++----------------------------------- doc/style.css | 10 +-- 2 files changed, 70 insertions(+), 132 deletions(-) (limited to 'doc') diff --git a/doc/README.html.in b/doc/README.html.in index c218746..05b04a7 100644 --- a/doc/README.html.in +++ b/doc/README.html.in @@ -42,21 +42,51 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

News

-
Fri Sep 13 2003:

Fri Oct 17 2003:

Version 0.3 released, -changes include: split aeswepd into its +changes include: split aeswepd into its own package, add documentation, several bug fixes.

Overview

+

waproamd is a roaming daemon for wireless IEEE 802.11 NICs supporting the +Linux wireless extensions. It is intended to configure the WEP +keys according to the networks found.

+ +

waproamd is intended to be used together with ifplugd. Whenever +an association succeeds, ifplugd detects it and runs further +configuration commands for it.

+

Status

-

Version 0.3 works fine on hostap 0.0.4 and airolan.

+

Version 0.3 works fine on hostap 0.0.4 and airolan. Other driver/card combinations not tested, but may work too.

Documentation

-

Have a look on the man pages waproamd(8), waproamd.conf(5). (A XSLT capable browser is required)

+

Have a look on the man pages waproamd(8), waproamd.conf(5). (An XSLT capable browser is required)

+ +

Mode of Operation

+ +

As long as the local NIC is not associated to any wireless +network waproamd scans iteratively for them. If one is detected, a +script in @sysconfdir@/waproamd/scripts/ named after +the MAC address of the access point is called. If this script is +not existent, @sysconfdir@/waproamd/scripts/default +is called instead. The first argument to this script is +"start". If the association is lost, the same script is run with +the argument "stop". While the NIC is associated no scans are +issued.

+ +

If multiple WLANs are detected at the same time, the network +which is detected by the hardware first is selected. However, +networks where a matching script exists take precedence.

+ +

waproamd requires a network driver supporting the Linux +wireless extensions v15 or newer. The driver needs to support scanning +for wireless networks, which may be tested by running "iwlist +scan". If the driver supports the wireless event subsystem, +waproamd may use it to improve latency behaviour. It is not required, +however.

Configuration

@@ -67,123 +97,43 @@ one ethernet interface in INTERFACES. For each interface a seperate instance of waproamd is spawned. The arguments specified in ARGS are append to waproamd's command line. Have a look on waproamd -h or man waproamd for further information -about the available options.

+about the options available.

-

The network interface which is controlled by waproamd -should not be configured automatically by your distribution's network -subsystem, since waproamd will do this for you if needed. On -Debian remove interface names beginning with eth or -wlan from the auto option line in -/etc/network/interfaces.

+

Put your WEP keys in /etc/waproamd/keys/ in files named +after the AP's MAC address with an appended .wep. If the AP +uses aeswepd +for automatic rekeying, you may put the AES key into a file with the +suffix .aes instead.

-

Troubleshooting

+

The configuration is similar to ifplugd.

-

When you are using the hotplug subsystem (Debian package -hotplug) you may notice that the network device is configured -even when it is not listed on an auto line in -/etc/network/interface. This may be due to hotplug -being configured to ifup the network interface when it -becomes available. This was the default behavior in the Debian -hotplug package prior to release 0.0.20030117-1, for -example. To prevent this you should either upgrade your -hotplug package or comment out the ifup call in -/etc/hotplug/net.agent.

- -

When using waproamd together with APM (and probably ACPI) -suspends, strange things may happen: some network devices fail to -detect the network cable for a short period of time before and after -the suspend. When using the -f switch, this will be treated -as "no link beat", thus the network is shutdown after a -timeout. During this timeout the machine changes to suspended -state. When it is resumed again, the timeout will be run out, the -network is deconfigured, however, as the next cable detection -succeeds, the network is configured again immediately. To fix this -problem, waproamd should be disabled before the APM suspend -and enabled back after the suspend. This may be done by using -apmd and adding a script to -/etc/apm/{suspend,resume}.d which simply calls -/etc/init.d/waproamd suspend, resp. /etc/init.d/waproamd -resume. It might even be a good idea to shut down the network -completely during suspend, this may be achieved by calling -/etc/init.d/waproamd stop and /etc/init.d/waproamd -start in the appropriate places. I strongly urge the packagers of -this software for the Linux distributions to add such scripts to their -packages.

- -

FAQ

- -
    -

  1. Q: I want to use waproamd with my PCMCIA device, but waproamd quits - when it doesn't find eth0, when I have not inserted the - card. What can I do?

    - -

    A: Use the -f switch. This is not very clean however, - since modprobe is called on each cable detection query of waproamd to - load a module for the network device. This is suboptimal. You should - probably run waproamd only when the card is really inserted.

    -
    2. - -

  2. Q: I am using the -f switch, but the kernel logs are getting filled - with messages like "modprobe: modprobe: Can't locate module - eth0". What can I do?

    - -

    A: Make sure you have a line like alias eth0 off in your /etc/modules.conf

    -
    3. - -

  3. Q: When the cable is unplugged and the interface shut down it is - still available with ifconfig and markes as UP. Why this?

    - -

    A: waproamd cannot detect the link beat with a shut down interface on - certain (most as of kernel 2.4.19) network drivers. Thus waproamd - enables the interface before querying the link status. This may - be switched off with -a flag. You might want to use it if you - have a sane network driver (e.g. eepro100). The subdirectory - patches/ in the waproamd distribution includes a patch for the - 8139too 0.9.26 driver, which makes the driver compatible with - -a. Don't ask me how to apply this patch. If you don't know, you - won't need it.

    4. - -

  4. Q: Does it work with anything else than plain ethernet or wireless LAN?

    - -

    A: Certainly not, since the MII and -ETHTOOL ioctl()s and the wireless extension don't -exist on - other network device types.

    5. - -

  5. Q: I have a Realtek 8139 based network card. Everytime waproamd - starts on bootup my machine freezes. What can I do?

    - -

    A: This is a bug in the 8139too driver 0.9.25 (at least) shipped - with Linux 2.4.19, please upgrade to 8139too 0.9.26 (Linux 2.4.20 - or seperately at http://www.sourceforge.net/projects/gkernel/).

    6. - - -

  6. Q: There are already laptop-net's ifd and miid, why did you write - your own daemon?

    - -

    A: laptop-net simply sucks and I didn't know of miid when I wrote - waproamd. However, waproamd is far better than miid. For a - comparison of miid and waproamd, have a look on - - http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=162763&repeatmerged=yes

    7. -
+

Troubleshooting

+

Not all drivers/cards support the wireless event subsystem of the +Linux wireless extensions. Its support on your machine cannot be +detected automatically, you have to test it yourself with "iwlist +scan". See man 8 iwlist for more information. If your +driver/card combination does not support this, you have to enable +polling of association status by passing -e on the command +line. This will increase the reaction latency of waproamd.

Requirements

-

A newer Linux Kernel (I think 2.2 is good enough, alltough I tested it -only with 2.4) with a compatible device driver and -ethernet card. Most modern cards and drivers are compatible, like mine -which works with the 8139too driver.

+

A newer Linux Kernel with a compatible device driver and WLAN NIC +(Wireless extensions v15 or newer). Most modern cards and drivers are +compatible, like mines which work with the hostap driver, version +0.0.3 and above. The driver has to support the scanning interface, +wireless event support ist nice to have.

waproamd was developed and tested on Debian GNU/Linux -"testing" from July 2003, it should work on most other Linux -distributions (and maybe Unix versions) since it uses GNU autoconf and -GNU libtool for source code configuration and shared library -management.

+"testing" from October 2003, it should work on most other Linux +distributions since it uses GNU autoconf for source code +configuration.

-

The machine used was a Medion 9580-F laptop with a Realtek 8139 -network card and a PRISM1 PCMCIA wireless LAN card.

+

The machines used for development are a Medion 9580-F laptop with a +TEAC and a ZONET PCMCIA WLAN NIC. Both cards feature a PRISM2 chipset. hostap 0.0.4 was used as driver.

waproamd needs libdaemon.

@@ -202,15 +152,7 @@ for it.

Acknowledgements

-

For the developers of mii-diag, ethtool and laptop-net, since I looked -on their source codes for learning how to use the link beat ioctls.

- -

Oliver Kurth for packaging waproamd for Debian and waproamd's -manpage

- -

Asgeir Nilsen, Sean Reifschneider, R. Steve McKown, David Mitchell for patches

- -

Frederic Lepied for integrating waproamd into Mandrake Linux

+

None so far

Download

@@ -220,13 +162,9 @@ manpage

Get waproamd's development sources from the Subversion repository.

-

You may find a mostly up to date Debian package of waproamd on the Debian package repository.

- -

Packages for Mandrake Linux may be found in the Cooker distribution; Gentoo packages are available as well

-
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, Oct 2003
-
$Id: README.html.in 48 2003-09-13 11:36:11Z lennart $
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, October 2003
+
$Id$
diff --git a/doc/style.css b/doc/style.css index 090bbc7..f71e501 100644 --- a/doc/style.css +++ b/doc/style.css @@ -1,20 +1,20 @@ -/* $Id: style.css 43 2003-09-13 11:25:11Z lennart $ */ +/* $Id$ */ /*** - * This file is part of ifplugd. + * This file is part of waproamd. * - * ifplugd is free software; you can redistribute it and/or modify it + * waproamd is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * - * ifplugd is distributed in the hope that it will be useful, but + * waproamd is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with ifplugd; if not, write to the Free Software Foundation, + * along with waproamd; if not, write to the Free Software Foundation, * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. ***/ -- cgit