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