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