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