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