2817a82b7de3239e9fff78d997bb75ba233bd202
[dragonfly.git] / usr.sbin / ancontrol / ancontrol.8
1 .\" Copyright (c) 1997, 1998, 1999
2 .\"     Bill Paul <wpaul@ee.columbia.edu> All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by Bill Paul.
15 .\" 4. Neither the name of the author nor the names of any co-contributors
16 .\"    may be used to endorse or promote products derived from this software
17 .\"   without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
29 .\" THE POSSIBILITY OF SUCH DAMAGE.
30 .\"
31 .\" $FreeBSD: src/usr.sbin/ancontrol/ancontrol.8,v 1.3.2.17 2003/02/01 03:25:12 ambrisko Exp $
32 .\" $DragonFly: src/usr.sbin/ancontrol/ancontrol.8,v 1.2 2003/06/17 04:29:52 dillon Exp $
33 .\"
34 .Dd September 10, 1999
35 .Dt ANCONTROL 8
36 .Os
37 .Sh NAME
38 .Nm ancontrol
39 .Nd configure Aironet 4500/4800 devices
40 .Sh SYNOPSIS
41 .Nm
42 .Fl i Ar iface Fl A
43 .Nm
44 .Fl i Ar iface Fl N
45 .Nm
46 .Fl i Ar iface Fl S
47 .Nm
48 .Fl i Ar iface Fl I
49 .Nm
50 .Fl i Ar iface Fl T
51 .Nm
52 .Fl i Ar iface Fl C
53 .Nm
54 .Fl i Ar iface Fl Q
55 .Nm
56 .Fl i Ar iface Fl Z
57 .Nm
58 .Fl i Ar iface Fl R
59 .Nm
60 .Fl i Ar iface Fl t Cm 0 Ns - Ns Cm 4
61 .Nm
62 .Fl i Ar iface Fl s Cm 0 Ns - Ns Cm 3
63 .Nm
64 .Fl i Ar iface
65 .Op Fl v Cm 1 Ns - Ns Cm 4
66 .Fl a Ar AP
67 .Nm
68 .Fl i Ar iface Fl b Ar beacon_period
69 .Nm
70 .Fl i Ar iface
71 .Op Fl v Cm 0 | 1
72 .Fl d Cm 0 Ns - Ns Cm 3
73 .Nm
74 .Fl i Ar iface Fl e Cm 0 Ns - Ns Cm 4
75 .Nm
76 .Fl i Ar iface
77 .Op Fl v Cm 0 Ns - Ns Cm 8
78 .Fl k Ar key
79 .Nm
80 .Fl i Ar iface
81 .Fl K Cm 0 Ns - Ns Cm 2
82 .Nm
83 .Fl i Ar iface
84 .Fl W Cm 0 Ns - Ns Cm 2
85 .Nm
86 .Fl i Ar iface
87 .Fl L Ar user_name
88 .Nm
89 .Fl i Ar iface Fl j Ar netjoin_timeout
90 .Nm
91 .Fl i Ar iface Fl l Ar station_name
92 .Nm
93 .Fl i Ar iface Fl m Ar mac_address
94 .Nm
95 .Fl i Ar iface
96 .Op Fl v Cm 1 Ns - Ns Cm 3
97 .Fl n Ar SSID
98 .Nm
99 .Fl i Ar iface Fl o Cm 0 | 1
100 .Nm
101 .Fl i Ar iface Fl p Ar tx_power
102 .Nm
103 .Fl i Ar iface Fl c Ar frequency
104 .Nm
105 .Fl i Ar iface Fl f Ar fragmentation_threshold
106 .Nm
107 .Fl i Ar iface Fl r Ar RTS_threshold
108 .Nm
109 .Fl i Ar iface Fl M Cm 0 Ns - Ns Cm 15
110 .Nm
111 .Fl h
112 .Sh DESCRIPTION
113 The
114 .Nm
115 utility controls the operation of Aironet wireless networking
116 devices via the
117 .Xr an 4
118 driver.
119 Most of the parameters that can be changed relate to the
120 IEEE 802.11 protocol which the Aironet cards implement.
121 This includes such things as
122 the station name, whether the station is operating in ad-hoc (point
123 to point) or infrastructure mode, and the network name of a service
124 set to join.
125 The
126 .Nm
127 utility can also be used to view the current NIC status, configuration
128 and to dump out the values of the card's statistics counters.
129 .Pp
130 The
131 .Ar iface
132 argument given to
133 .Nm
134 should be the logical interface name associated with the Aironet
135 device
136 .Li ( an0 , an1 ,
137 etc.).
138 If one isn't specified the device
139 .Dq Li an0
140 will be assumed.
141 .Pp
142 The
143 .Nm
144 utility is not designed to support the combination of arguments from different
145 .Sx SYNOPSIS
146 lines in a single
147 .Nm
148 invocation, and such combinations are not recommended.
149 .Sh OPTIONS
150 The options are as follows:
151 .Bl -tag -width indent
152 .It Fl i Ar iface Fl A
153 Display the preferred access point list.
154 The AP list can be used by
155 stations to specify the MAC address of access points with which it
156 wishes to associate.
157 If no AP list is specified (the default) then
158 the station will associate with the first access point that it finds
159 which serves the SSID(s) specified in the SSID list.
160 The AP list can
161 be modified with the
162 .Fl a
163 option.
164 .It Fl i Ar iface Fl N
165 Display the SSID list.
166 This is a list of service set IDs (i.e., network names)
167 with which the station wishes to associate.
168 There may be up to three SSIDs
169 in the list: the station will go through the list in ascending order and
170 associate with the first matching SSID that it finds.
171 .It Fl i Ar iface Fl S
172 Display NIC status information.
173 This includes the current operating
174 status, current BSSID, SSID, channel, beacon period and currently
175 associated access point.
176 The operating mode indicates the state of
177 the NIC, MAC status and receiver status.
178 When the
179 .Qq Li synced
180 keyword
181 appears, it means the NIC has successfully associated with an access
182 point, associated with an ad-hoc
183 .Dq master
184 station, or become a
185 .Dq master
186 itself.
187 The beacon period can be anything between 20 and 976 milliseconds.
188 The default is 100.
189 .It Fl i Ar iface Fl I
190 Display NIC capability information.
191 This shows the device type,
192 frequency, speed and power level capabilities and firmware revision levels.
193 .It Fl i Ar iface Fl T
194 Display the NIC's internal statistics counters.
195 .It Fl i Ar iface Fl C
196 Display current NIC configuration.
197 This shows the current operation mode,
198 receive mode, MAC address, power save settings, various timing settings,
199 channel selection, diversity, transmit power and transmit speed.
200 .It Fl i Ar iface Fl Q
201 Display the cached signal strength information maintained by the
202 .Xr an 4
203 driver.
204 The driver retains information about signal strength and
205 noise level for packets received from different hosts.
206 The signal strength and noise level values are displayed in units of dBms by
207 default.
208 The
209 .Va machdep.an_cache_mode
210 .Xr sysctl 8
211 variable can be set to
212 .Cm raw , dbm
213 or
214 .Cm per .
215 .It Fl i Ar iface Fl Z
216 Clear the signal strength cache maintained internally by the
217 .Xr an 4
218 driver.
219 .It Fl i Ar iface Fl R
220 Display RSSI map that converts from the RSSI index to percent and dBm.
221 .It Fl i Ar iface Fl t Cm 0 Ns - Ns Cm 4
222 Select transmit speed.
223 The available settings are as follows:
224 .Bl -column ".Em TX rate" -offset indent
225 .Em "TX rate    NIC speed"
226 .It Cm 0 Ta "Auto -- NIC selects optimal speed"
227 .It Cm 1 Ta "1Mbps fixed"
228 .It Cm 2 Ta "2Mbps fixed"
229 .It Cm 3 Ta "5.5Mbps fixed"
230 .It Cm 4 Ta "11Mbps fixed"
231 .El
232 .Pp
233 Note that the 5.5 and 11Mbps settings are only supported on the 4800
234 series adapters: the 4500 series adapters have a maximum speed of 2Mbps.
235 .It Fl i Ar iface Fl s Cm 0 Ns - Ns Cm 3
236 Set power save mode.
237 Valid selections are as follows:
238 .Bl -column ".Em Selection" -offset indent
239 .Em "Selection  Power save mode"
240 .It Cm 0 Ta "None - power save disabled"
241 .It Cm 1 Ta "Constantly awake mode (CAM)"
242 .It Cm 2 Ta "Power Save Polling (PSP)"
243 .It Cm 3 Ta "Fast Power Save Polling (PSP-CAM)"
244 .El
245 .Pp
246 Note that for IBSS (ad-hoc) mode, only PSP mode is supported, and only
247 if the ATIM window is non-zero.
248 .It Fl i Ar iface Oo Fl v Cm 1 Ns - Ns Cm 4 Oc Fl a Ar AP
249 Set preferred access point.
250 The
251 .Ar AP
252 is specified as a MAC address consisting of 6 hexadecimal values
253 separated by colons.
254 By default, the
255 .Fl a
256 option only sets the first entry in the AP list.
257 The
258 .Fl v
259 modifier can be used to specify exactly which AP list entry is to be
260 modified.
261 If the
262 .Fl v
263 flag is not used, the first AP list entry will be changed.
264 .It Fl i Ar iface Fl b Ar beacon_period
265 Set the ad-hoc mode beacon period.
266 The
267 .Ar beacon_period
268 is specified in milliseconds.
269 The default is 100ms.
270 .It Fl i Ar iface Oo Fl v Cm 0 | 1 Oc Fl d Cm 0 Ns - Ns Cm 3
271 Select the antenna diversity.
272 Aironet devices can be configured with up
273 to two antennas, and transmit and receive diversity can be configured
274 accordingly.
275 Valid selections are as follows:
276 .Bl -column ".Em Selection" -offset indent
277 .Em "Selection  Diversity"
278 .It Cm 0 Ta "Select factory default diversity"
279 .It Cm 1 Ta "Antenna 1 only"
280 .It Cm 2 Ta "Antenna 2 only"
281 .It Cm 3 Ta "Antenna 1 and 2"
282 .El
283 .Pp
284 The receive and transmit diversity can be set independently.
285 The user
286 must specify which diversity setting is to be modified by using the
287 .Fl v
288 option: selection
289 .Cm 0
290 sets the receive diversity and
291 .Cm 1
292 sets the transmit diversity.
293 .It Fl i Ar iface Fl e Cm 0 Ns - Ns Cm 4
294 Set the transmit WEP key to use.
295 Note that until this command is issued, the device will use the
296 last key programmed.
297 The transmit key is stored in NVRAM.
298 Currently
299 set transmit key can be checked via
300 .Fl C
301 option.
302 Selection
303 .Cm 4
304 sets the card in
305 .Dq "Home Network Mode"
306 and uses the home key.
307 .It Fl i Ar iface Oo Fl v Cm 0 Ns - Ns Cm 8 Oc Fl k Ar key
308 Set a WEP key.
309 For 40 bit prefix 10 hex character with 0x.
310 For 128 bit prefix 26 hex character with 0x.
311 Use
312 .Qq
313 as the key to erase the key.
314 Supports 4 keys; even numbers are for permanent keys
315 and odd number are for temporary keys.
316 For example,
317 .Fl v Cm 1
318 sets the first temporary key.
319 (A
320 .Dq permanent
321 key is stored in NVRAM; a
322 .Dq temporary
323 key is not.)
324 Note that the device will use the most recently-programmed key by default.
325 Currently set keys can be checked via
326 .Fl C
327 option, only the sizes of the
328 keys are returned.
329 The value of
330 .Cm 8
331 is for the home key.
332 Note that the value for the home key can be read back from firmware.
333 .It Fl i Ar iface Fl K Cm 0 Ns - Ns Cm 2
334 Set authorization type.
335 Use
336 .Cm 0
337 for none,
338 .Cm 1
339 for
340 .Dq Open ,
341 .Cm 2
342 for
343 .Dq "Shared Key" .
344 .It Fl i Ar iface Fl W Cm 0 Ns - Ns Cm 2
345 Enable WEP.
346 Use
347 .Cm 0
348 for no WEP,
349 .Cm 1
350 to enable full WEP,
351 .Cm 2
352 for mixed cell.
353 .It Fl i Ar iface Fl L Ar user_name
354 Enable LEAP and query for password.
355 It will check to see if it has authenticated for up to 60s.
356 To disable LEAP, set WEP mode.
357 .It Fl i Ar iface Fl j Ar netjoin_timeout
358 Set the ad-hoc network join timeout.
359 When a station is first activated
360 in ad-hoc mode, it will search out a
361 .Dq master
362 station with the desired
363 SSID and associate with it.
364 If the station is unable to locate another
365 station with the same SSID after a suitable timeout, it sets itself up
366 as the
367 .Dq master
368 so that other stations may associate with it.
369 This
370 timeout defaults to 10000 milliseconds (10 seconds) but may be changed
371 with this option.
372 The timeout should be specified in milliseconds.
373 .It Fl i Ar iface Fl l Ar station_name
374 Set the station name used internally by the NIC.
375 The
376 .Ar station_name
377 can be any text string up to 16 characters in length.
378 The default name
379 is set by the driver to
380 .Dq Li FreeBSD .
381 .It Fl i Ar iface Fl m Ar mac_address
382 Set the station address for the specified interface.
383 The
384 .Ar mac_address
385 is specified as a series of six hexadecimal values separated by colons,
386 e.g.:
387 .Li 00:60:1d:12:34:56 .
388 This programs the new address into the card
389 and updates the interface as well.
390 .It Fl i Ar iface Oo Fl v Cm 1 Ns - Ns Cm 3 Oc Fl n Ar SSID
391 Set the desired SSID (network name).
392 There are three SSIDs which allows
393 the NIC to work with access points at several locations without needing
394 to be reconfigured.
395 The NIC checks each SSID in sequence when searching
396 for a match.
397 The SSID to be changed can be specified with the
398 .Fl v
399 modifier option.
400 If the
401 .Fl v
402 flag isn't used, the first SSID in the list is set.
403 .It Fl i Ar iface Fl o Cm 0 | 1
404 Set the operating mode of the Aironet interface.
405 Valid selections are
406 .Cm 0
407 for ad-hoc mode and
408 .Cm 1
409 for infrastructure mode.
410 The default driver setting is for infrastructure
411 mode.
412 .It Fl i Ar iface Fl p Ar tx_power
413 Set the transmit power level in milliwatts.
414 Valid power settings
415 vary depending on the actual NIC and can be viewed by dumping the
416 device capabilities with the
417 .Fl I
418 flag.
419 Typical values are 1, 5, 20, 50 and 100mW.
420 Selecting 0 sets
421 the factory default.
422 .It Fl i Ar iface Fl c Ar frequency
423 Set the radio frequency of a given interface.
424 The
425 .Ar frequency
426 should be specified as a channel ID as shown in the table below.
427 The
428 list of available frequencies is dependent on radio regulations specified
429 by regional authorities.
430 Recognized regulatory authorities include
431 the FCC (United States), ETSI (Europe), France and Japan.
432 Frequencies
433 in the table are specified in MHz.
434 .Bl -column ".Em Channel ID" ".Em FCC" ".Em ETSI" ".Em France" ".Em Japan" -offset indent
435 .Em "Channel ID FCC     ETSI    France  Japan"
436 .It Cm 1 Ta 2412 Ta 2412 Ta - Ta -
437 .It Cm 2 Ta 2417 Ta 2417 Ta - Ta -
438 .It Cm 3 Ta 2422 Ta 2422 Ta - Ta -
439 .It Cm 4 Ta 2427 Ta 2427 Ta - Ta -
440 .It Cm 5 Ta 2432 Ta 2432 Ta - Ta -
441 .It Cm 6 Ta 2437 Ta 2437 Ta - Ta -
442 .It Cm 7 Ta 2442 Ta 2442 Ta - Ta -
443 .It Cm 8 Ta 2447 Ta 2447 Ta - Ta -
444 .It Cm 9 Ta 2452 Ta 2452 Ta - Ta -
445 .It Cm 10 Ta 2457 Ta 2457 Ta 2457 Ta -
446 .It Cm 11 Ta 2462 Ta 2462 Ta 2462 Ta -
447 .It Cm 12 Ta - Ta 2467 Ta 2467 Ta -
448 .It Cm 13 Ta - Ta 2472 Ta 2472 Ta -
449 .It Cm 14 Ta - Ta - Ta - Ta 2484
450 .El
451 .Pp
452 If an illegal channel is specified, the
453 NIC will revert to its default channel.
454 For NICs sold in the United States
455 and Europe, the default channel is 3.
456 For NICs sold in France, the default
457 channel is 11.
458 For NICs sold in Japan, the only available channel is 14.
459 Note that two stations must be set to the same channel in order to
460 communicate.
461 .It Fl i Ar iface Fl f Ar fragmentation_threshold
462 Set the fragmentation threshold in bytes.
463 This threshold controls the
464 point at which outgoing packets will be split into multiple fragments.
465 If a single fragment is not sent successfully, only that fragment will
466 need to be retransmitted instead of the whole packet.
467 The fragmentation
468 threshold can be anything from 64 to 2312 bytes.
469 The default is 2312.
470 .It Fl i Ar iface Fl r Ar RTS_threshold
471 Set the RTS/CTS threshold for a given interface.
472 This controls the
473 number of bytes used for the RTS/CTS handshake boundary.
474 The
475 .Ar RTS_threshold
476 can be any value between 0 and 2312.
477 The default is 2312.
478 .It Fl i Ar iface Fl M Cm 0 Ns - Ns Cm 15
479 Set monitor mode via bit mask, meaning:
480 .Pp
481 .Bl -tag -width indent -offset indent -compact
482 .It Em Bit
483 .Em Meaning
484 .It 0
485 to not dump 802.11 packet.
486 .It 1
487 to enable 802.11 monitor.
488 .It 2
489 to monitor any SSID.
490 .It 4
491 to not skip beacons, monitor beacons produces a high system load.
492 .It 8
493 to enable full Aironet header returned via BPF.
494 Note it appears that a SSID must be set.
495 .El
496 .It Fl h
497 Print a list of available options and sample usage.
498 .El
499 .Sh SECURITY NOTES
500 WEP
501 .Pq Dq "wired equivalent privacy"
502 is based on the RC4 algorithm,
503 using a 24 bit initialization vector.
504 .Pp
505 RC4 is supposedly vulnerable to certain known plaintext attacks,
506 especially with 40 bit keys.
507 So the security of WEP in part depends on how much known plaintext
508 is transmitted.
509 .Pp
510 Because of this, although counter-intuitive, using
511 .Dq "shared key"
512 authentication (which involves sending known plaintext) is less
513 secure than using
514 .Dq open
515 authentication when WEP is enabled.
516 .Pp
517 Devices may alternate among all of the configured WEP keys when
518 transmitting packets.
519 Therefore, all configured keys (up to four) must agree.
520 .Sh EXAMPLES
521 .Bd -literal -offset indent
522 ancontrol -i an0 -v 0 -k 0x12345678901234567890123456
523 ancontrol -i an0 -K 2
524 ancontrol -i an0 -W 1
525 ancontrol -i an0 -e 0
526 .Ed
527 .Pp
528 Sets a WEP key 0, enables
529 .Dq "Shared Key"
530 authentication, enables full WEP
531 and uses transmit key 0.
532 .Sh SEE ALSO
533 .Xr an 4 ,
534 .Xr ifconfig 8
535 .Sh HISTORY
536 The
537 .Nm
538 utility first appeared in
539 .Fx 4.0 .
540 .Sh BUGS
541 The statistics counters do not seem to show the amount of transmit
542 and received frames as increasing.
543 This is likely due to the fact that
544 the
545 .Xr an 4
546 driver uses unmodified packet mode instead of letting the NIC perform
547 802.11/ethernet encapsulation itself.
548 .Pp
549 Setting the channel does not seem to have any effect.
550 .Sh AUTHORS
551 The
552 .Nm
553 utility was written by
554 .An Bill Paul Aq wpaul@ee.columbia.edu .