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 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
 304 .Dq Li FreeBSD .
 305 .It Fl i Ar iface Fl m Ar mac address
 306 Set the station address for the specified interface.
 307 The
 308 .Ar mac address
 309 is specified as a series of six hexadecimal values separated by colons,
 310 e.g.: 00:60:1d:12:34:56.
 311 This programs the new address into the card
 312 and updates the interface as well.
 313 .It Xo
 314 .Fl i Ar iface
 315 .Op Fl v Ar 1|2|3
 316 .Fl n Ar SSID
 317 .Xc
 318 Set the desired SSID (network name).
 319 There are three SSIDs which allows
 320 the NIC to work with access points at several locations without needing
 321 to be reconfigured.
 322 The NIC checks each SSID in sequence when searching
 323 for a match.
 324 The SSID to be changed can be specified with the
 325 .Fl v
 326 modifier option.
 327 If the
 328 .Fl v
 329 flag isn't used, the first SSID in the list is set.
 330 .It Fl i Ar iface Fl o Ar 0|1
 331 Set the operating mode of the Aironet interface.
 332 Valid selections are
 333 .Ar 0
 334 for ad-hoc mode and
 335 .Ar 1
 336 for infrastructure mode.
 337 The default driver setting is for infrastructure
 338 mode.
 339 .It Fl i Ar iface Fl p Ar tx power
 340 Set the transmit power level in milliwatts.
 341 Valid power settings
 342 vary depending on the actual NIC and can be viewed by dumping the
 343 device capabilities with the
 344 .Fl I
 345 flag.
 346 Typical values are 1, 5, 20, 50 and 100mW.
 347 Selecting 0 sets
 348 the factory default.
 349 .It Fl i Ar iface Fl c Ar channel
 350 Set the radio frequency of a given interface.
 351 The
 352 .Ar frequency
 353 should be specfied as a channel ID as shown in the table below.
 354 The
 355 list of available frequencies is dependent on radio regulations specified
 356 by regional authorities.
 357 Recognized regulatory authorities include
 358 the FCC (United States), ETSI (Europe), France and Japan.
 359 Frequencies
 360 in the table are specified in Mhz.
 361 .Bl -column "Channel ID " "FCC " "ETSI " "France " "Japan " -offset indent
 362 .Em "Channel ID FCC     ETSI    France  Japan"
 363 1       2412    2412    -       -
 364 2       2417    2417    -       -
 365 3       2422    2422    -       -
 366 4       2427    2427    -       -
 367 5       2432    2432    -       -
 368 6       2437    2437    -       -
 369 7       2442    2442    -       -
 370 8       2447    2447    -       -
 371 9       2452    2452    -       -
 372 10      2457    2457    2457    -
 373 11      2462    2462    2462    -
 374 12      -       2467    2467    -
 375 13      -       2472    2472    -
 376 14      -       -       -       2484
 377 .El
 378 .Pp
 379 If an illegal channel is specified, the
 380 NIC will revert to its default channel.
 381 For NICs sold in the United States
 382 and Europe, the default channel is 3.
 383 For NICs sold in France, the default
 384 channel is 11.
 385 For NICs sold in Japan, the only available channel is 14.
 386 Note that two stations must be set to the same channel in order to
 387 communicate.
 388 .It Fl i Ar iface Fl f Ar fragmentation threshold
 389 Set the fragmentation threshold in bytes.
 390 This threshold controls the
 391 point at which outgoing packets will be split into multiple fragments.
 392 If a single fragment is not sent successfully, only that fragment will
 393 need to be retransmitted instead of the whole packet.
 394 The fragmentation
 395 threshold can be anything from 64 to 2312 bytes.
 396 The default is 2312.
 397 .It Fl i Ar iface Fl r Ar RTS threshold
 398 Set the RTS/CTS threshold for a given interface.
 399 This controls the
 400 number of bytes used for the RTS/CTS handhake boundary.
 401 The
 402 .Ar RTS threshold
 403 can be any value between 0 and 2312.
 404 The default is 2312.
 405 .It Fl h
 406 Prints a list of available options and sample usage.
 407 .El
 408 .Sh SECURITY NOTES
 409 WEP ("wired equivalent privacy") is based on the RC4 algorithm,
 410 using a 24 bit initialization vector.
 411 .Pp
 412 RC4 is supposedly vunerable to certain known plaintext attacks,
 413 especially with 40 bit keys.
 414 So the security of WEP in part depends on how much known plaintext
 415 is transmitted.
 416 .Pp
 417 Because of this, although counter-intuitive, using "shared key"
 418 authentication (which involves sending known plaintext) is less
 419 secure than using "open" authentication when WEP is enabled.
 420 .Pp
 421 Devices may alternate among all of the configured WEP keys when
 422 tranmitting packets.
 423 Therefore, all configured keys (up to four) must agree.
 424 .Sh EXAMPLES
 425 .Bd -literal -offset indent
 426 ancontrol -i an0 -v 0 -k 0x12345678901234567890123456
 427 ancontrol -i an0 -K 2
 428 ancontrol -i an0 -W 1
 429 ancontrol -i an0 -e 0
 430 .Ed
 431 .Pp
 432 Sets a WEP key 0, enables "Shared Key" authentication, enables full WEP
 433 and uses transmit key 0.
 434 .Sh SEE ALSO
 435 .Xr an 4 ,
 436 .Xr ifconfig 8
 437 .Sh HISTORY
 438 The
 439 .Nm
 440 command first appeared in
 441 .Fx 4.0 .
 442 .Sh BUGS
 443 The statistics counters do not seem to show the amount of transmit
 444 and received frames as increasing.
 445 This is likely due to the fact that
 446 the
 447 .Xr an 4
 448 driver uses unmodified packet mode instead of letting the NIC perform
 449 802.11/ethernet encapsulation itself.
 450 .Pp
 451 Setting the channel does not seem to have any effect.
 452 .Sh AUTHORS
 453 The
 454 .Nm
 455 command was written by
 456 .An Bill Paul Aq wpaul@ee.columbia.edu .