Linux Certif

Toute la documentation sur la certification Linux LPI

wifiroamd

NAME

wifiroamd - Daemon to manage WiFi network connections automatically.

SYNOPSIS

wifiroamd [options]

DESCRIPTION

The wifiroamd program is used to make wireless Internet connections easier to manage and more automatic. It uses a set of scripts in /etc/wifiroamd to that specify actions to take when resetting the interface and bringing it up and down. Lists of preferred access points are specified by files within the /etc/wifiroamd/connections directory.

There are many control variables that may be set in your connection or custom scripts which control how the network is configured and managed. See the /etc/wifiroamd/config-defaults file for more information on these values. Note that these values may be set in /etc/wifiroamd/config to override them as a default, or may be set in any of the connection or up, down, or other scripts to control how the network is configured.

QUICK START

See the "README" file for a quickstart set of instructions.

REQUIREMENTS

You must have a wireless device which supports "iwlist DEV scan", where "DEV" is the name of your wireless device. This must respond with a list of access points, not a message saying that scanning is not supported.

OPTIONS

These programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

-v

Increase the verbosity of information logged to syslog during operation. This option may be specified up to 9 times to increase logging verbosity.

OPERATION

Scripts that are run exist under the /etc/wifiroamd directory. Scripts which end in ".d" are directories, and scripts within the directory are run in order based on file name. Typically, the file names would start with two digits, in order to force a sequence to the run files.

These scripts are run with "start" when bringing up the network, "stop" when bringing it down, and "monitor" when monitoring.

When wifiroamd starts up, it first runs scripts from /etc/wifiroamd/scripts/reset.d. These scripts are meant to reset the the wireless and possible other devices to a known state. If you have problems that require re-loading the wireless drivers, you may add a custom script in this directory which handles the restart.

Next, "iwlist scan" is used to search for wireless access points. The scan is run several times, to make sure that all available access points are found. Sometimes access points are not available during a single scan.

Next, scripts are searched for in /etc/wifiroamd/connections which match any of the available access points. The list is searched from the strongest access point to the weakest, and scripts are looked for first based on matching the access point MAC address, (either all uppercase or all lowercase), then matches are looked for with matching ESSID.

Script file names must begin with "mac:" followed by the MAC address of the AP, or "essid:" followed by the AP ESSID. The MAC address is encoded so that non-alphanumeric characters are encoded as in HTTP URLs, for example space is encoded as the percent character followed by the number 20. Space is ASCII character code 32, which is 20 in hexadecimal.

If a matching script is found, it is run. If no matching script is found, the scripts in the "default.d" directory are run.

If no access points are discovered by the scan process, scripts from the "nowireless.d" directory are run.

Next, scripts from the /etc/wifiroamd/scripts/up.d directory are run. These scripts implement DHCP, bonding, and other features of the system.

The connect script is run again, with the argument "up". This is where you would put static IP addressing commands or the like.

Now that the network is up, it goes into monitoring by running the scripts in /etc/wifiroamd/scripts/monitor.d" every 10 seconds. If any of these scripts set the variable WIFIROAMD_SCRIPTEXITCODE=1, then monitoring is considered to have failed. When monitoring fails, the wireless is brought down and the process starts over. Currently, monitoring works by pinging the default gateway with fping, and fails after 30 packets have not been returned.

Monitoring also runs the AP specific script (including "default.d" or "nowireless.d" with the argument "monitor" during the monitoring.

When sent the TERM signal, or monitoring fails, the scripts in /etc/wifiroamd/scripts/down.d are run to shut down the interface.

SCRIPT INSTRUCTIONS

Scripts are run in a very special way. They are bash scripts, but setting any environment variable starting with WIFIROAMD_ will persist across the different scripts that are run, and will control the operation of the system as a whole. Standard variables are documented in the /etc/wifiroamd/config-defaults file.

Because of the special way these scripts are run, you cannot use exit or exec within the script. You also cannot redirect stdout unless you redirect it back to normal before the script is complete.

EXAMPLES

To set it up so that you prefer an access point with the ESSID "mynetwork", and set a WEP key, you would create the file /etc/wifiroamd/connections/essid:mynetwork with:

WIFIROAMD_IWCONFIG_KEY=0123456789abcdef

To prefer an AP with the MAC address 0a:00:00:01:02:03, with no special WEP or other settings, you can touch /etc/wifiroamd/connections/mac:0a:00:00:01:02:03

SEEN FILES

Files in /etc/wifiroamd/seen are create if you connect to an AP for which you do not have a normal script. This way, you can periodically look at APs that you have connected to, and if you would like to make them a preferred connection, or tune the values associated with it, you can simply move this script into the "connections" directory and edit it.

BONDING

Bonding is supported by this program. Bonding is where both your wireless and wired connections are tied together such that plugging in the wired network will seamlessly cause your traffic to go wired (for more bandwidth) and then unplugging causes you to switch back to wired.

However, bonding is restricted in that it must know your IP address before the interface is up. To use bonding, you must set the WIFIROAMD_BONDING_IPADDRESS variable to your IP address. You can then use DHCP to get gateway, DNS, NTP and other settings. You would need to configure the DHCP server to always give you the IP address matching what you have set in this variable. This is a limitation of the Linux bonding driver.

Bonding also requires that you are running as an Access Point, not as a router, between the wired and wireless networks. The same IP address must be usable on either network segment. So, either you need to have a traditional access point plugged into your wired network, or you need an AP+Router device like the Linksys WRT-54G which has 4 ports on the same network as the wireless. You can then plug in to these ports for higher speed transfers.

COMMUNICATION

There are currently two ways to communicate with wifiroamd: touching a file named /etc/wifiroamd/disabled and sending a TERM signal.

If a file named /etc/wifiroamd/disabled is found, wifiroamd will shut down the wireless connection, exactly as if monitoring had failed. wifiroamd will then sit idle, waiting for that file to be removed. The init.d scripts remove that file.

A TERM signal sent to wifiroamd via the kill system call will cause wifiroamd to shut down the wireless connection gracefully, and then will exit.

SEE ALSO

iwconfig(8), iwlist(8).

AUTHOR

wifiroamd was written by Sean Reifschneider <jafo@tummy.com>.

This manual page was written by Sean Reifschneider <jafo@tummy.com>, based on the manpage template from Debian's package helper.