waproamd - Wireless Access Point Roaming Daemon for WLAN IEEE 802.11

waproamd [options]

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

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 /etc/waproamd/scripts/ named after the MAC address of the access point is called. (First lowercase, than uppercase is checked) If a script like this is not found a script named essid:<ESSID> in the same directory is used. Special characters are escape in an HTTP URL like fashion. If this script is not existent, /etc/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.

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

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.

waproamd supports the host_roaming ioctl() defined by the hostap driver.

-n | --no-daemon

Do not daemonize (for debugging) (default: off)

-s | --no-syslog

Do not use syslog, use stdout instead (for debugging) (default: off).

-i | --iface=IFACE

Specify the wireless network interface (default: wlan0)

-w | --wait-on-fork

When daemonizing, wait until the background process finished with the initial association detection.

-W | --wait-on-kill

When killing a running daemon (with -k) wait until the daemon died.

-M | --monitor

Don't fail when the network interface is not available, instead use NETLINK to monitor device avaibility. The is useful for PCMCIA devices and similar.

-e | --no-event

Don't use the wireless event API (as used by iwevent(8)), instead poll for association information. Some network drivers do not support this relatively new feature of the Linux wireless extension. Sadly the support of this feature cannot be detected automatically.

-t | --scan-interval=SECS

Specify the time between scans for wireless networks.

-p | --poll-intervall=SECS

When using -e, specify the time between association status polls.

-h | --help

Show help

-k | --kill

Kill a running daemon (Specify -i to select the daemon instance to kill)

-c | --check-running

Check if a daemon is running for a given network interface. Sets the return value to 0 if a daemon is already running or to 255 if not.

-S | --supend

Suspend a running daemon. The daemon will no longer check the link status until it is resumed (-R) again. (Specify -i to select the daemon instance to suspend.)

-R | --resume

Resume a suspended daemon. (Specify -i to select the daemon instance to resume.)

-v | --version

Show version

-r | --issue-scan

Tell a running daemon to issue an immediate scan for new networks

-U | --no-userspace-roaming

Don't enable userspace roaming as supported by certain drivers (e.g. hostap). Normaly, waproamd tries to enable this special feature, doing effectively the same as "iwpriv wlan0 host_roaming 2". If the driver supports this private ioctl the robustness of waproamd's operation is increased. However, it is not required for successful use. See your driver documentation for mor information on this topic.

/etc/waproamd/waproamd.conf: this file is sourced by the init script /etc/init.d/waproamd and contains the interface to be monitored and the options to be used.

/etc/waproamd/scripts/<AP MAC address>: this is called whenever a wireless network controlled by an AP with a matching address is detected. The file is first tried with the MAC address formatted lowercase. If no script with that name exists waproamd looks for a file with the MAC address formatted uppercase. Only scripts marked executable are considered. Networks with non-executable scripts are always ignored. You may use this to "disable" specific networks from being selected. Takes the same arguments as the following script:

/etc/waproamd/scripts/essid:<ESSID>: This is called whenever a wireless AP is detected but no script named after the AP MAC exists (See above). If the ESSID contains special chracters (ASCII code < 32, >= 127, '/', '%') they are replaced by a character % and the hexadecimal ASCII number of the character in uppercase. This is similar to the HTTP URL encoding. Only scripts marked executable are considered. Takes the same arguments as the following script:

/etc/waproamd/scripts/default: this is the script which is called when neither a script named after the AP MAC address, nor a script named after the ESSID is found. It takes a single argument: either "start" or "stop". An environment variable AP is set to the MAC address of the access point found. An environment variable IFACE is set to the network interface name. An environment variable ESSID contains the ESSID of the WLAN network. ESSID_ESCAPED contains the ESSID with all special chracters escaped the same way as described above. The default implementation of this script looks for a file /etc/waproamd/keys/<AP MAC address>.wep (or named after the ESSID, following the same scheme as the script selection described above). If it exists its contents is used to set the WEP key of the NIC. Otherwise the script looks for a file /etc/waproamd/keys/<AP MAC address>.aes. If it exists the AES WEP rekeying daemon aeswepd(8) is called. Otherwise WEP encryption is disabled.

/var/run/waproamd.<iface>.pid: the pid file for waproamd.

SIGINT, SIGTERM, SIGQUIT waproamd will quit. This is issued by passing -k to waproamd.

SIGHUP waproamd will rescan for available networks immediately.

waproamd was written by Lennart Poettering <mzjncebnzq (at) 0pointer (dot) de>. waproamd is available at http://0pointer.de/lennart/projects/waproamd/

ifplugd(8), aeswepd(8), iwconfig(8), iwlist(8)

This man page was written using xmltoman(1) by Oliver Kurth.