1WIFIROAMD(8) System Manager's Manual WIFIROAMD(8)
2
6 wifiroamd - Daemon to manage WiFi network connections automatically.
7
9 wifiroamd [options]
10
12 The wifiroamd program is used to make wireless Internet connections
13 easier to manage and more automatic. It uses a set of scripts in
14 /etc/wifiroamd to that specify actions to take when resetting the
15 interface and bringing it up and down. Lists of preferred access
16 points are specified by files within the /etc/wifiroamd/connections
17 directory.
18 There are many control variables that may be set in your connection or
20 custom scripts which control how the network is configured and managed.
21 See the /etc/wifiroamd/config-defaults file for more information on
22 these values. Note that these values may be set in /etc/wifiroamd/con‐
23 fig to override them as a default, or may be set in any of the connec‐
24 tion or up, down, or other scripts to control how the network is con‐
25 figured.
26
28 See the "README" file for a quickstart set of instructions.
29
31 You must have a wireless device which supports "iwlist DEV scan", where
32 "DEV" is the name of your wireless device. This must respond with a
33 list of access points, not a message saying that scanning is not sup‐
34 ported.
35
37 These programs follow the usual GNU command line syntax, with long
38 options starting with two dashes (`-'). A summary of options is
39 included below.
40 -v Increase the verbosity of information logged to syslog during
42 operation. This option may be specified up to 9 times to
43 increase logging verbosity.
44
46 Scripts that are run exist under the /etc/wifiroamd directory. Scripts
47 which end in ".d" are directories, and scripts within the directory are
48 run in order based on file name. Typically, the file names would start
49 with two digits, in order to force a sequence to the run files.
50 These scripts are run with "start" when bringing up the network, "stop"
52 when bringing it down, and "monitor" when monitoring.
53 When wifiroamd starts up, it first runs scripts from
55 /etc/wifiroamd/scripts/reset.d. These scripts are meant to reset the
56 the wireless and possible other devices to a known state. If you have
57 problems that require re-loading the wireless drivers, you may add a
58 custom script in this directory which handles the restart.
59 Next, "iwlist scan" is used to search for wireless access points. The
61 scan is run several times, to make sure that all available access
62 points are found. Sometimes access points are not available during a
63 single scan.
64 Next, scripts are searched for in /etc/wifiroamd/connections which
66 match any of the available access points. The list is searched from
67 the strongest access point to the weakest, and scripts are looked for
68 first based on matching the access point MAC address, (either all
69 uppercase or all lowercase), then matches are looked for with matching
70 ESSID.
71 Script file names must begin with "mac:" followed by the MAC address of
73 the AP, or "essid:" followed by the AP ESSID. The MAC address is
74 encoded so that non-alphanumeric characters are encoded as in HTTP
75 URLs, for example space is encoded as the percent character followed by
76 the number 20. Space is ASCII character code 32, which is 20 in hexa‐
77 decimal.
78 If a matching script is found, it is run. If no matching script is
80 found, the scripts in the "default.d" directory are run.
81 If no access points are discovered by the scan process, scripts from
83 the "nowireless.d" directory are run.
84 Next, scripts from the /etc/wifiroamd/scripts/up.d directory are run.
86 These scripts implement DHCP, bonding, and other features of the sys‐
87 tem.
88 The connect script is run again, with the argument "up". This is where
90 you would put static IP addressing commands or the like.
91 Now that the network is up, it goes into monitoring by running the
93 scripts in /etc/wifiroamd/scripts/monitor.d" every 10 seconds. If any
94 of these scripts set the variable WIFIROAMD_SCRIPTEXITCODE=1, then mon‐
95 itoring is considered to have failed. When monitoring fails, the wire‐
96 less is brought down and the process starts over. Currently, monitor‐
97 ing works by pinging the default gateway with fping, and fails after 30
98 packets have not been returned.
99 Monitoring also runs the AP specific script (including "default.d" or
101 "nowireless.d" with the argument "monitor" during the monitoring.
102 When sent the TERM signal, or monitoring fails, the scripts in
104 /etc/wifiroamd/scripts/down.d are run to shut down the interface.
105
107 Scripts are run in a very special way. They are bash scripts, but set‐
108 ting any environment variable starting with WIFIROAMD_ will persist
109 across the different scripts that are run, and will control the opera‐
110 tion of the system as a whole. Standard variables are documented in
111 the /etc/wifiroamd/config-defaults file.
112 Because of the special way these scripts are run, you cannot use exit
114 or exec within the script. You also cannot redirect stdout unless you
115 redirect it back to normal before the script is complete.
116
118 To set it up so that you prefer an access point with the ESSID "mynet‐
119 work", and set a WEP key, you would create the file /etc/wifiroamd/con‐
120 nections/essid:mynetwork with:
121 WIFIROAMD_IWCONFIG_KEY=0123456789abcdef
122 To prefer an AP with the MAC address 0a:00:00:01:02:03, with no special
125 WEP or other settings, you can touch /etc/wifiroamd/connec‐
126 tions/mac:0a:00:00:01:02:03
127
129 Files in /etc/wifiroamd/seen are create if you connect to an AP for
130 which you do not have a normal script. This way, you can periodically
131 look at APs that you have connected to, and if you would like to make
132 them a preferred connection, or tune the values associated with it, you
133 can simply move this script into the "connections" directory and edit
134 it.
135
137 Bonding is supported by this program. Bonding is where both your wire‐
138 less and wired connections are tied together such that plugging in the
139 wired network will seamlessly cause your traffic to go wired (for more
140 bandwidth) and then unplugging causes you to switch back to wired.
141 However, bonding is restricted in that it must know your IP address
143 before the interface is up. To use bonding, you must set the
144 WIFIROAMD_BONDING_IPADDRESS variable to your IP address. You can then
145 use DHCP to get gateway, DNS, NTP and other settings. You would need
146 to configure the DHCP server to always give you the IP address matching
147 what you have set in this variable. This is a limitation of the Linux
148 bonding driver.
149 Bonding also requires that you are running as an Access Point, not as a
151 router, between the wired and wireless networks. The same IP address
152 must be usable on either network segment. So, either you need to have
153 a traditional access point plugged into your wired network, or you need
154 an AP+Router device like the Linksys WRT-54G which has 4 ports on the
155 same network as the wireless. You can then plug in to these ports for
156 higher speed transfers.
157
159 There are currently two ways to communicate with wifiroamd: touching a
160 file named /etc/wifiroamd/disabled and sending a TERM signal.
161 If a file named /etc/wifiroamd/disabled is found, wifiroamd will shut
163 down the wireless connection, exactly as if monitoring had failed.
164 wifiroamd will then sit idle, waiting for that file to be removed. The
165 init.d scripts remove that file.
166 A TERM signal sent to wifiroamd via the kill system call will cause
168 wifiroamd to shut down the wireless connection gracefully, and then
169 will exit.
170
172 iwconfig(8), iwlist(8).
173
175 wifiroamd was written by Sean Reifschneider <jafo@tummy.com>.
176 This manual page was written by Sean Reifschneider <jafo@tummy.com>,
178 based on the manpage template from Debian's package helper.
179 January 21, 2006 WIFIROAMD(8)