wireless_tools/iwconfig.8

   1 .\" Jean II - HPLB - 96
   2 .\" iwconfig.8
   3 .\"
   4 .TH IWCONFIG 8 "31 October 1996" "net-tools" "Linux Programmer's Manual"
   5 .\"
   6 .\" NAME part
   7 .\"
   8 .SH NAME
   9 iwconfig \- configure a wireless network interface
  10 .\"
  11 .\" SYNOPSIS part
  12 .\"
  13 .SH SYNOPSIS
  14 .BI "iwconfig [" interface ]
  15 .br
  16 .BI "iwconfig " interface " [essid " X "] [nwid " N "] [freq " F "] [channel " C ]
  17 .br
  18 .BI "                   [sens " S "] [mode " M "] [ap " A "] [nick " NN ]
  19 .br
  20 .BI "                   [rate " R "] [rts " RT "] [frag " FT "] [txpower " T ]
  21 .br
  22 .BI "                   [enc " E "] [key " K "] [power " P "] [retry " R ]
  23 .br
  24 .BI "                   [commit]
  25 .br
  26 .BI "iwconfig --help"
  27 .br
  28 .BI "iwconfig --version"
  29 .\"
  30 .\" DESCRIPTION part
  31 .\"
  32 .SH DESCRIPTION
  33 .B Iwconfig
  34 is similar to
  35 .IR ifconfig (8),
  36 but is dedicated to the wireless interfaces. It is used to set the
  37 parameters of the network interface which are specific to the wireless
  38 operation (for example : the frequency).
  39 .B Iwconfig
  40 may also be used to display those parameters, and the wireless
  41 statistics (extracted from
  42 .IR /proc/net/wireless ).
  43 .PP
  44 All these parameters and statistics are device dependant. Each driver
  45 will provide only some of them depending on the hardware support, and
  46 the range of value may change. Please refer to the man page of each
  47 device for details.
  48 .\"
  49 .\" PARAMETER part
  50 .\"
  51 .SH PARAMETERS
  52 .TP
  53 .B essid
  54 Set the ESSID (or Network Name - in some products it may also called
  55 Domain ID). The ESSID is used to identify cells which are part of the
  56 same virtual network.
  57 .br
  58 As opposed to the NWID which defines a single cell, the ESSID defines
  59 a group of cell connected via repeaters or infrastructure, where the
  60 user may roam.  With some card, you may disable the ESSID checking
  61 (ESSID promiscuous) with
  62 .IR off " or " any " (and " on
  63 to reenable it).
  64 .br
  65 .B Examples :
  66 .br
  67 .I "    iwconfig eth0 essid any"
  68 .br
  69 .I "    iwconfig eth0 essid ""My Network""
  70 .TP
  71 .BR nwid / domain
  72 Set the Network ID (in some products it is also called Domain ID). As
  73 all adjacent wireless networks share the same medium, this parameter
  74 is used to differenciate them (create logical colocated networks) and
  75 identify nodes belonguing to the same cell. With some card, you may
  76 disable the Network ID checking (NWID promiscuous) with
  77 .IR off " (and " on
  78 to reenable it).
  79 .br
  80 .B Examples :
  81 .br
  82 .I "    iwconfig eth0 nwid AB34
  83 .br
  84 .I "    iwconfig eth0 nwid off"
  85 .TP
  86 .BR freq / channel
  87 Set the operating frequency or channel in the device. Value below 1000
  88 are the channel number, value over this is the frequency in Hz. You
  89 must append the suffix k, M or G to the value (for example, "2.46G"
  90 for 2.46 GHz frequency), or add enough '0'.
  91 .br
  92 Channels are usually numbered starting at 1,
  93 and you may use
  94 .IR iwpriv (8)
  95 to get the total number of channels and list the available
  96 frequencies. Depending on regulations, some frequencies/channels may
  97 not be available.
  98 .br
  99 .B Examples :
 100 .br
 101 .I "    iwconfig eth0 freq 2.422G"
 102 .br
 103 .I "    iwconfig eth0 channel 3"
 104 .TP
 105 .B sens
 106 Set the sensitivity threshold. This is the lowest signal level for
 107 which we attempt a packet reception, signal lower than this are not
 108 received. This is used to avoid receiving background noise, so you
 109 should set it according to the average noise level. Positive values
 110 are assumed to be the raw value used by the hardware or a percentage,
 111 negative values are assumed to be dBm.
 112 .br
 113 With some hardware, this parameter also control the defer threshold
 114 (lowest signal level for which we consider the channel busy) and the
 115 handover threshold (lowest signal level where we stay associated with
 116 the current access point).
 117 .br
 118 .B Example :
 119 .br
 120 .I "    iwconfig eth0 sens -80"
 121 .TP
 122 .B mode
 123 Set the operating mode of the device, which depends on the network
 124 topology. The mode can be
 125 .I Ad-hoc
 126 (network composed of only one cell and without Access Point),
 127 .I Managed
 128 (node connects to a network composed of many Access Points, with roaming),
 129 .I Master
 130 (the node is the synchronisation master or act as an Access Point),
 131 .I Repeater
 132 (the node forward packets between other wireless nodes),
 133 .I Secondary
 134 (the node act as a backup master/repeater),
 135 .I Monitor
 136 (the node act as a passive monitor and only receives packets) or
 137 .IR Auto .
 138 .br
 139 .B Example :
 140 .br
 141 .I "    iwconfig eth0 mode Managed"
 142 .br
 143 .I "    iwconfig eth0 mode Ad-Hoc"
 144 .TP
 145 .B ap
 146 Force the card to register to the Access Point given by the address,
 147 if it is possible. When the quality of the connection goes too low,
 148 the driver may revert back to automatic mode (the card finds the best
 149 Access Point in range).
 150 .br
 151 You may also use
 152 .I off
 153 to re-enable automatic mode without changing the current Access Point,
 154 or you may use
 155 .I any
 156 or
 157 .I auto
 158 to force the card to reassociate with the current best Access Point.
 159 .br
 160 .B Example :
 161 .br
 162 .I "    iwconfig eth0 ap 00:60:1D:01:23:45"
 163 .br
 164 .I "    iwconfig eth0 ap any"
 165 .br
 166 .I "    iwconfig eth0 ap off"
 167 .TP
 168 .BR nick [name]
 169 Set the nickname, or the station name. Most 802.11 products do define
 170 it, but this is not used as far as the protocols (MAC, IP, TCP) are
 171 concerned and completely accessory as far as configuration goes. In
 172 fact only some diagnostic tools may use it.
 173 .br
 174 .B Example :
 175 .br
 176 .I "    iwconfig eth0 nickname ""My Linux Node""
 177 .TP
 178 .BR rate / bit [rate]
 179 For cards supporting multiple bit rates, set the bit-rate in b/s. The
 180 bit-rate is the speed at which bits are transmitted over the medium,
 181 the user speed of the link is lower due to medium sharing and
 182 overhead.
 183 .br
 184 You must append the suffix k, M or G to the value (decimal multiplier
 185 : 10^3, 10^6 and 10^9 b/s), or add enough '0'. Values below 1000 are
 186 card specific, usually an index in the bit-rate list. Use
 187 .I auto
 188 to select the automatic bit-rate mode (fallback to lower rate on noisy
 189 channels), which is the default for most cards, and
 190 .I fixed
 191 to revert back to fixed setting. If you specify a bit-rate value and append
 192 .IR auto ,
 193 the driver will use all bit lower and equal than this value.
 194 .br
 195 .B Examples :
 196 .br
 197 .I "    iwconfig eth0 rate 11M"
 198 .br
 199 .I "    iwconfig eth0 rate auto"
 200 .br
 201 .I "    iwconfig eth0 rate 5.5M auto"
 202 .TP
 203 .BR rts [_threshold]
 204 RTS/CTS adds a handshake before each packet transmission to make sure
 205 that the channel is clear. This adds overhead, but increase
 206 performance in case of hidden nodes or large number of active
 207 nodes. This parameters set the size of the smallest packet for which
 208 the node sends RTS, a value equal to the maximum packet size disable
 209 the scheme. You may also set this parameter to
 210 .IR auto ", " fixed " or " off .
 211 .br
 212 .B Examples :
 213 .br
 214 .I "    iwconfig eth0 rts 250"
 215 .br
 216 .I "    iwconfig eth0 rts off"
 217 .TP
 218 .BR frag [mentation_threshold]
 219 Fragmentation allow to split a IP packet in a burst of smaller
 220 fragments transmitted on the medium. In most cases this adds overhead,
 221 but in very noisy environment this reduce the error penalty. This
 222 parameter set the maximum fragment size, a value equal to the maximum
 223 packet size disable the scheme. You may also set this parameter to
 224 .IR auto ", " fixed " or " off .
 225 .br
 226 .B Examples :
 227 .br
 228 .I "    iwconfig eth0 frag 512"
 229 .br
 230 .I "    iwconfig eth0 frag off"
 231 .TP
 232 .BR key / enc [ryption]
 233 Used to manipulate encryption or scrambling keys and security mode.
 234 .br
 235 To set the current encryption key, just enter the key in hex digits as
 236 .IR XXXX-XXXX-XXXX-XXXX " or " XXXXXXXX .
 237 To set a key other than the current key, prepend or append
 238 .I [index]
 239 to the key itself (this won't change which is the active key). You can
 240 also enter the key as an ASCII string by using the
 241 .I s:
 242 prefix. Passphrase is currently not supported.
 243 .br
 244 To change which key is the current active key, just enter
 245 .I [index]
 246 (without entering any key value).
 247 .br
 248 .IR off " and " on
 249 disable and reenable encryption.
 250 .br
 251 The security mode may be
 252 .I open
 253 or
 254 .IR restricted ,
 255 and its meaning depend on the card used. With most card, in
 256 .I open
 257 mode no authentication is used and the card may also accept
 258 non-encrypted sessions, whereas in
 259 .I restricted
 260 mode only encrypted sessions are accepted and the card will use
 261 authentication if available.
 262 .br
 263 If you need to set multiple keys, or set a key and change the active
 264 key, you need to use multiple
 265 .B key
 266 directives. Arguments can be put in any order, the last one will take
 267 precendence.
 268 .br
 269 .B Examples :
 270 .br
 271 .I "    iwconfig eth0 key 0123-4567-89"
 272 .br
 273 .I "    iwconfig eth0 key s:password [2]"
 274 .br
 275 .I "    iwconfig eth0 key [2] open"
 276 .br
 277 .I "    iwconfig eth0 key off"
 278 .br
 279 .I "    iwconfig eth0 key restricted [3] 0123456789"
 280 .br
 281 .I "    iwconfig eth0 key 01-23 key 45-67 [4] key [4]"
 282 .TP
 283 .BR power
 284 Used to manipulate power management scheme parameters and mode.
 285 .br
 286 To set the period between wake up, enter
 287 .IR "period `value'" .
 288 To set the timeout before going back to sleep, enter
 289 .IR "timeout `value'" .
 290 You can also add the
 291 .IR min " and " max
 292 modifiers. By defaults, those values are in seconds, append the
 293 suffix m or u to specify values un milliseconds or
 294 microseconds. Sometimes, those values are without units (number of
 295 dwell or the like).
 296 .br
 297 .IR off " and " on
 298 disable and reenable power management. Finally, you may set the power
 299 management mode to
 300 .I all
 301 (receive all packets),
 302 .I unicast
 303 (receive unicast packets only, discard multicast and broadcast) and
 304 .I multicast
 305 (receive multicast and broadcast only, discard unicast packets).
 306 .br
 307 .B Examples :
 308 .br
 309 .I "    iwconfig eth0 power period 2"
 310 .br
 311 .I "    iwconfig eth0 power 500m unicast"
 312 .br
 313 .I "    iwconfig eth0 power timeout 300u all"
 314 .br
 315 .I "    iwconfig eth0 power off"
 316 .br
 317 .I "    iwconfig eth0 power min period 2 power max period 4"
 318 .TP
 319 .BR txpower
 320 For cards supporting multiple transmit powers, set the transmit power in dBm. If
 321 .I W
 322 is the power in Watt, the power in dBm is
 323 .IR "P = 30 + 10.log(W)" .
 324 If the value is postfixed by
 325 .IR mW ,
 326 it will be automatically converted to dBm.
 327 .br
 328 In addition,
 329 .IR on " and " off
 330 enable and disable the radio, and
 331 .IR auto " and " fixed
 332 enable and disable power control (if those features are available).
 333 .br
 334 .B Examples :
 335 .br
 336 .I "    iwconfig eth0 txpower 15"
 337 .br
 338 .I "    iwconfig eth0 txpower 30mW"
 339 .br
 340 .I "    iwconfig eth0 txpower auto"
 341 .br
 342 .I "    iwconfig eth0 txpower off"
 343 .TP
 344 .BR retry
 345 Most cards have MAC retransmissions, and some allow to set the
 346 behaviour of the retry mechanism.
 347 .br
 348 To set the maximum number of retries, enter
 349 .IR "limit `value'" .
 350 This is an absolute value (without unit).
 351 The set the maximum length of time the MAC should retry, enter
 352 .IR "lifetime `value'" .
 353 By defaults, this value in in seconds, append the suffix m or u to
 354 specify values un milliseconds or microseconds.
 355 .br
 356 You can also add the
 357 .IR min " and " max
 358 modifiers. If the card support automatic mode, they define the bounds
 359 of the limit or lifetime. Some other cards define different values
 360 depending on packet size, for example in 802.11
 361 .I min limit
 362 is the short retry limit (non RTS/CTS packets).
 363 .br
 364 .B Examples :
 365 .br
 366 .I "    iwconfig eth0 retry 16"
 367 .br
 368 .I "    iwconfig eth0 retry lifetime 300m"
 369 .br
 370 .I "    iwconfig eth0 retry min limit 8"
 371 .TP
 372 .BR commit
 373 Some cards may not apply changes done through Wireless Extensions
 374 immediately (they may wait to agregate the changes or apply it only
 375 when the card is brought up via ifconfig). This command (when
 376 available) force the card to apply all pending changes.
 377 .br
 378 This is normally not needed, because the card will eventually apply
 379 the changes, but can be usefull for debugging.
 380 .\"
 381 .\" DISPLAY part
 382 .\"
 383 .SH DISPLAY
 384 For each device which support wireless extensions,
 385 .I iwconfig
 386 will display the name of the
 387 .B MAC protocol
 388 used (name of device for proprietary protocols), the
 389 .B ESSID
 390 (Network Name), the
 391 .BR NWID ,
 392 the
 393 .B frequency
 394 (or channel), the
 395 .BR sensitivity ,
 396 the
 397 .B mode
 398 of operation, the
 399 .B Access Point
 400 address, the
 401 .B bit-rate
 402 the
 403 .BR "RTS threshold" ", the " "fragmentation threshold" ,
 404 the
 405 .B encryption key
 406 and the
 407 .B power management
 408 settings (depending on availability).
 409 .br
 410 See above for explanations of what these parameters mean.
 411 .br
 412 If the label for some values (such as bitrate) is followed by
 413 .RB ` = ',
 414 it means that the parameter is fixed and forced to that value, if it
 415 is followed by
 416 .RB ` : '
 417 it is only the current value (device in normal auto mode).
 418 .PP
 419 If
 420 .I /proc/net/wireless
 421 exists,
 422 .I iwconfig
 423 will also display its content. Note that those values will depend on
 424 the driver and the hardware specifics, so you need to refer to your
 425 driver documentation for proper interpretation of those values.
 426 .TP
 427 .B Link quality
 428 Overall quality of the link. May be based on the level of contention
 429 or interference, the bit or frame error rate, how good the received
 430 signal is, some timing synchronisation, or other hardware metric. This
 431 is an aggregate value, and depend totally on the driver and hardware.
 432 .TP
 433 .B Signal level
 434 Received signal strength (RSSI - how strong the received signal
 435 is). May be arbitrary units or dBm,
 436 .I iwconfig
 437 uses driver meta information to interpret the raw value given by
 438 .I /proc/net/wireless
 439 and display the proper unit or maximum value (using 8 bit arithmetic). In
 440 .I Ad-Hoc
 441 mode, this may be undefined and you should use
 442 .IR iwspy .
 443 .TP
 444 .B Noise level
 445 Background noise level (when no packet is transmited). Similar
 446 comments as for
 447 .BR "Signal level" .
 448 .TP
 449 .B Rx invalid nwid
 450 Number of packets received with a different NWID or ESSID. Used to
 451 detect configuration problems or adjacent network existence (on the
 452 same frequency).
 453 .TP
 454 .B Rx invalid crypt
 455 Number of packets that the hardware was unable to decrypt. This can be
 456 used to detect invalid encryption settings.
 457 .TP
 458 .B Rx invalid frag
 459 Number of packets for which the hardware was not able to properly
 460 re-assemble the link layer fragments (most likely one was missing).
 461 .TP
 462 .B Tx excessive retries
 463 Number of packets that the hardware failed to deliver. Most MAC
 464 protocol will retry the packet a number of time before giving up.
 465 .TP
 466 .B Invalid misc
 467 Other packets lost in relation with specific wireless operations.
 468 .TP
 469 .B Missed beacon
 470 Number of periodic beacons from the Cell or the Access Point we have
 471 missed. Beacons are sent at regular interval to maintain the cell
 472 coordination, failure to receive them usually indicate that we are out
 473 of range.
 474 .\"
 475 .\" AUTHOR part
 476 .\"
 477 .SH AUTHOR
 478 Jean Tourrilhes \- jt@hpl.hp.com
 479 .\"
 480 .\" FILES part
 481 .\"
 482 .SH FILES
 483 .I /proc/net/wireless
 484 .\"
 485 .\" SEE ALSO part
 486 .\"
 487 .SH SEE ALSO
 488 .BR ifconfig (8),
 489 .BR iwspy (8),
 490 .BR iwlist (8),
 491 .BR iwevent (8),
 492 .BR iwpriv (8),
 493 .BR wireless (7).