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