-.\" Jean II - HPLB - 96
+.\" Jean II - HPLB - 1996 => HPL - 2004
.\" iwconfig.8
.\"
-.TH IWCONFIG 8 "31 October 1996" "net-tools" "Linux Programmer's Manual"
+.TH IWCONFIG 8 "30 March 2006" "wireless-tools" "Linux Programmer's Manual"
.\"
.\" NAME part
.\"
.SH SYNOPSIS
.BI "iwconfig [" interface ]
.br
-.BI "iwconfig " interface " [essid " X "] [nwid " N "] [freq " F "] [channel " C ]
+.BI "iwconfig " interface " [essid " X "] [nwid " N "] [mode " M "] [freq " F "]
.br
-.BI " [sens " S "] [mode " M "] [ap " A "] [nick " NN ]
+.BI " [channel " C ] [sens " S "] [ap " A "] [nick " NN ]
.br
-.BI " [rate " R "] [rts " RT "] [frag " FT ]
+.BI " [rate " R "] [rts " RT "] [frag " FT "] [txpower " T ]
.br
-.BI " [enc " E "] [key " K "] [power " P ]
+.BI " [enc " E "] [key " K "] [power " P "] [retry " R ]
+.br
+.BI " [modu " M "] [commit]
+.br
+.BI "iwconfig --help"
+.br
+.BI "iwconfig --version"
.\"
.\" DESCRIPTION part
.\"
statistics (extracted from
.IR /proc/net/wireless ).
.PP
-All these parameters and statistics are device dependant. Each driver
-will provide only some of them depending on the hardware support, and
-the range of value may change. Please refer to the man page of each
+All these parameters and statistics are device dependent. Each driver
+will provide only some of them depending on hardware support, and the
+range of values may change. Please refer to the man page of each
device for details.
.\"
.\" PARAMETER part
.SH PARAMETERS
.TP
.B essid
-Set the ESSID (or Network Name - in some products it may also called
-Domain ID). The ESSID is used to identify cells which are part of the
-same virtual network.
-.br
-As opposed to the NWID which defines a single cell, the ESSID defines
-a group of cell connected via repeaters or infrastructure, where the
-user may roam. With some card, you may disable the ESSID checking
-(ESSID promiscuous) with
+Set the ESSID (or Network Name - in some products it may also be
+called Domain ID). The ESSID is used to identify cells which are part
+of the same virtual network.
+.br
+As opposed to the AP Address or NWID which define a single cell, the
+ESSID defines a group of cells connected via repeaters or
+infrastructure, where the user may roam transparently.
+.br
+With some cards, you may disable the ESSID checking (ESSID
+promiscuous) with
.IR off " or " any " (and " on
to reenable it).
.br
+If the ESSID of your network is one of the special keywords
+.RI ( off ", " on " or " any ),
+you should use
+.I --
+to escape it.
+.br
.B Examples :
.br
.I " iwconfig eth0 essid any"
.br
.I " iwconfig eth0 essid ""My Network""
+.br
+.I " iwconfig eth0 essid -- ""ANY""
.TP
-.BR nwid / domain
-Set the Network ID (in some products it is also called Domain ID). As
-all adjacent wireless networks share the same medium, this parameter
-is used to differenciate them (create logical colocated networks) and
-identify nodes belonguing to the same cell. With some card, you may
-disable the Network ID checking (NWID promiscuous) with
+.BR nwid
+Set the Network ID. As all adjacent wireless networks share the same
+medium, this parameter is used to differentiate them (create logical
+colocated networks) and identify nodes belonging to the same cell.
+.br
+This parameter is only used for pre-802.11 hardware, the 802.11
+protocol uses the ESSID and AP Address for this function.
+.br
+With some cards, you may disable the Network ID checking (NWID
+promiscuous) with
.IR off " (and " on
to reenable it).
.br
.br
.I " iwconfig eth0 nwid off"
.TP
-.BR freq / channel
-Set the operating frequency or channel in the device. Value below 1000
-are the channel number, value over this is the frequency in Hz. You
-must append the suffix k, M or G to the value (for example, "2.46G"
-for 2.46 GHz frequency), or add enough '0'.
-.br
-Channels are usually numbered starting at 1,
-and you may use
-.IR iwpriv (8)
-to get the total number of channels and list the available
-frequencies. Depending on regulations, some frequencies/channels may
-not be available.
-.br
-.B Examples :
-.br
-.I " iwconfig eth0 freq 2.422G"
-.br
-.I " iwconfig eth0 channel 3"
-.TP
-.B sens
-Set the sensitivity threshold. This is the lowest signal level for
-which we attempt a packet reception, signal lower than this are not
-received. This is used to avoid receiving background noise, so you
-should set it according to the average noise level. Positive values
-are assumed to be the raw value used by the hardware or a percentage,
-negative values are assumed to be dBm.
-.br
-With some hardware, this parameter also control the defer threshold
-(lowest signal level for which we consider the channel busy) and the
-handover threshold (lowest signal level where we stay associated with
-the current access point).
+.BR nick [name]
+Set the nickname, or the station name. Some 802.11 products do define
+it, but this is not used as far as the protocols (MAC, IP, TCP) are
+concerned and completely useless as far as configuration goes. Only
+some wireless diagnostic tools may use it.
.br
.B Example :
.br
-.I " iwconfig eth0 sens -80"
+.I " iwconfig eth0 nickname ""My Linux Node""
.TP
.B mode
Set the operating mode of the device, which depends on the network
topology. The mode can be
-.I Ad-hoc
+.I Ad-Hoc
(network composed of only one cell and without Access Point),
.I Managed
-(network composed of many cells, with roaming or with an Access Point),
+(node connects to a network composed of many Access Points, with roaming),
.I Master
-(the node is the synchronisation master or act as an Access Point),
+(the node is the synchronisation master or acts as an Access Point),
.I Repeater
-(the node forward packets on the air),
+(the node forwards packets between other wireless nodes),
.I Secondary
-(the node act as a backup master/repeater) or
+(the node acts as a backup master/repeater),
+.I Monitor
+(the node is not associated with any cell and passively monitor all
+packets on the frequency) or
.IR Auto .
.br
.B Example :
.br
.I " iwconfig eth0 mode Managed"
+.br
+.I " iwconfig eth0 mode Ad-Hoc"
+.TP
+.BR freq / channel
+Set the operating frequency or channel in the device. A value below
+1000 indicates a channel number, a value greater than 1000 is a
+frequency in Hz. You may append the suffix k, M or G to the value (for
+example, "2.46G" for 2.46 GHz frequency), or add enough '0'.
+.br
+Channels are usually numbered starting at 1, and you may use
+.IR iwlist (8)
+to get the total number of channels, list the available frequencies,
+and display the current frequency as a channel. Depending on
+regulations, some frequencies/channels may not be available.
+.br
+When using Managed mode, most often the Access Point dictates the
+channel and the driver may refuse the setting of the frequency. In
+Ad-Hoc mode, the frequency setting may only be used at initial cell
+creation, and may be ignored when joining an existing cell.
+.br
+You may also use
+.I off
+or
+.I auto
+to let the card pick up the best channel (when supported).
+.br
+.B Examples :
+.br
+.I " iwconfig eth0 freq 2422000000"
+.br
+.I " iwconfig eth0 freq 2.422G"
+.br
+.I " iwconfig eth0 channel 3"
+.br
+.I " iwconfig eth0 channel auto"
.TP
.B ap
-Register to the Access Point given by the address, if it is
-possible. When the quality of the connection goes too low, the driver
-may revert back to automatic mode.
+Force the card to register to the Access Point given by the address,
+if it is possible. This address is the cell identity of the Access
+Point, as reported by wireless scanning, which may be different from
+its network MAC address. If the wireless link is point to point, set
+the address of the other end of the link. If the link is ad-hoc, set
+the cell identity of the ad-hoc network.
+.br
+When the quality of the connection goes too low, the driver may revert
+back to automatic mode (the card selects the best Access Point in
+range).
+.br
+You may also use
+.I off
+to re-enable automatic mode without changing the current Access Point,
+or you may use
+.I any
+or
+.I auto
+to force the card to reassociate with the currently best Access Point.
.br
.B Example :
.br
.I " iwconfig eth0 ap 00:60:1D:01:23:45"
-.TP
-.BR nick [name]
-Set the nickname, or the station name. Most 802.11 products do define
-it, but this is not used as far as the protocols (MAC, IP, TCP) are
-concerned and completely accessory as far as configuration goes. In
-fact only some diagnostic tools may use it.
.br
-.B Example :
+.I " iwconfig eth0 ap any"
.br
-.I " iwconfig eth0 nickname ""My Linux Node""
+.I " iwconfig eth0 ap off"
.TP
.BR rate / bit [rate]
For cards supporting multiple bit rates, set the bit-rate in b/s. The
bit-rate is the speed at which bits are transmitted over the medium,
the user speed of the link is lower due to medium sharing and
-overhead.
+various overhead.
.br
-You must append the suffix k, M or G to the value (decimal multiplier
-: 10^3, 10^6 and 10^9 b/s), or add enough '0'. Values below 1000 are
+You may append the suffix k, M or G to the value (decimal multiplier :
+10^3, 10^6 and 10^9 b/s), or add enough '0'. Values below 1000 are
card specific, usually an index in the bit-rate list. Use
.I auto
-to select the automatic bit-rate mode (fallback to lower rate on noisy
+to select automatic bit-rate mode (fallback to lower rate on noisy
channels), which is the default for most cards, and
.I fixed
to revert back to fixed setting. If you specify a bit-rate value and append
.IR auto ,
-the driver will use all bit lower and equal than this value.
+the driver will use all bit-rates lower and equal than this value.
.br
.B Examples :
.br
.I " iwconfig eth0 rate 11M"
.br
.I " iwconfig eth0 rate auto"
+.br
+.I " iwconfig eth0 rate 5.5M auto"
+.TP
+.BR txpower
+For cards supporting multiple transmit powers, sets the transmit power
+in dBm. If
+.I W
+is the power in Watt, the power in dBm is
+.IR "P = 30 + 10.log(W)" .
+If the value is postfixed by
+.IR mW ,
+it will be automatically converted to dBm.
+.br
+In addition,
+.IR on " and " off
+enable and disable the radio, and
+.IR auto " and " fixed
+enable and disable power control (if those features are available).
+.br
+.B Examples :
+.br
+.I " iwconfig eth0 txpower 15"
+.br
+.I " iwconfig eth0 txpower 30mW"
+.br
+.I " iwconfig eth0 txpower auto"
+.br
+.I " iwconfig eth0 txpower off"
+.TP
+.B sens
+Set the sensitivity threshold. This define how sensitive is the card
+to poor operating conditions (low signal, interference). Positive
+values are assumed to be the raw value used by the hardware or a
+percentage, negative values are assumed to be dBm. Depending on the
+hardware implementation, this parameter may control various functions.
+.br
+On modern cards, this parameter usually control handover/roaming
+threshold, the lowest signal level for which the hardware remains
+associated with the current Access Point. When the signal level goes
+below this threshold the card starts looking for a new/better Access
+Point. Some cards may use the number of missed beacons to trigger
+this. For high density of Access Points, a higher threshold make sure
+the card is always associated with the best AP, for low density of
+APs, a lower threshold minimise the number of failed handoffs.
+.br
+On more ancient card this parameter usually controls the defer
+threshold, the lowest signal level for which the hardware considers
+the channel busy. Signal levels above this threshold make the hardware
+inhibits its own transmission whereas signals weaker than this are
+ignored and the hardware is free to transmit. This is usually strongly
+linked to the receive threshold, the lowest signal level for which the
+hardware attempts packet reception. Proper setting of these thresholds
+prevent the card to waste time on background noise while still
+receiving weak transmissions. Modern designs seems to control those
+thresholds automatically.
+.br
+.br
+.B Example :
+.br
+.I " iwconfig eth0 sens -80"
+.br
+.I " iwconfig eth0 sens 2"
+.TP
+.BR retry
+Most cards have MAC retransmissions, and some allow to set the
+behaviour of the retry mechanism.
+.br
+To set the maximum number of retries, enter
+.IR "limit `value'" .
+This is an absolute value (without unit), and the default (when
+nothing is specified).
+To set the maximum length of time the MAC should retry, enter
+.IR "lifetime `value'" .
+By defaults, this value is in seconds, append the suffix m or u to
+specify values in milliseconds or microseconds.
+.br
+You can also add the
+.IR short ", " long ", " min " and " max
+modifiers. If the card supports automatic mode, they define the bounds
+of the limit or lifetime. Some other cards define different values
+depending on packet size, for example in 802.11
+.I min limit
+is the short retry limit (non RTS/CTS packets).
+.br
+.B Examples :
+.br
+.I " iwconfig eth0 retry 16"
+.br
+.I " iwconfig eth0 retry lifetime 300m"
+.br
+.I " iwconfig eth0 retry short 12"
+.br
+.I " iwconfig eth0 retry min limit 8"
.TP
.BR rts [_threshold]
RTS/CTS adds a handshake before each packet transmission to make sure
-that the channel is clear. This adds overhead, but increase
-performance in case of hidden nodes or large number of active
-nodes. This parameters set the size of the smallest packet for which
-the node sends RTS, a value equal to the maximum packet size disable
-the scheme. You may also set this parameter to
+that the channel is clear. This adds overhead, but increases
+performance in case of hidden nodes or a large number of active
+nodes. This parameter sets the size of the smallest packet for which
+the node sends RTS ; a value equal to the maximum packet size disables
+the mechanism. You may also set this parameter to
.IR auto ", " fixed " or " off .
.br
.B Examples :
.I " iwconfig eth0 rts off"
.TP
.BR frag [mentation_threshold]
-Fragmentation allow to split a IP packet in a burst of smaller
+Fragmentation allows to split an IP packet in a burst of smaller
fragments transmitted on the medium. In most cases this adds overhead,
-but in very noisy environment this reduce the error penalty. This
-parameter set the maximum fragment size, a value equal to the maximum
-packet size disable the scheme. You may also set this parameter to
+but in a very noisy environment this reduces the error penalty and
+allow packets to get through interference bursts. This parameter sets
+the maximum fragment size which is always lower than the maximum
+packet size.
+.br
+This parameter may also control Frame Bursting available on some
+cards, the ability to send multiple IP packets together. This
+mechanism would be enabled if the fragment size is larger than the
+maximum packet size.
+.br
+You may also set this parameter to
.IR auto ", " fixed " or " off .
.br
.B Examples :
.I " iwconfig eth0 frag off"
.TP
.BR key / enc [ryption]
-Used to manipulate encryption or scrambling keys and encryption mode.
+Used to manipulate encryption or scrambling keys and security mode.
.br
To set the current encryption key, just enter the key in hex digits as
.IR XXXX-XXXX-XXXX-XXXX " or " XXXXXXXX .
-To set a key other than the current key, append
+To set a key other than the current key, prepend or append
.I [index]
-to the key itself. You can also enter the key as an ASCII string by
-using the
+to the key itself (this won't change which is the active key). You can
+also enter the key as an ASCII string by using the
.I s:
-prefix.
+prefix. Passphrase is currently not supported.
.br
-To change which key is the current active key, just enter
+To change which key is the currently active key, just enter
.I [index]
(without entering any key value).
.br
.IR off " and " on
-disable and reenable encryption,
+disable and reenable encryption.
+.br
+The security mode may be
+.I open
+or
+.IR restricted ,
+and its meaning depends on the card used. With most cards, in
.I open
-set the system in open mode (accept non-encrypted packets) and
+mode no authentication is used and the card may also accept
+non-encrypted sessions, whereas in
.I restricted
-discard non-encrypted packets.
+mode only encrypted sessions are accepted and the card will use
+authentication if available.
+.br
+If you need to set multiple keys, or set a key and change the active
+key, you need to use multiple
+.B key
+directives. Arguments can be put in any order, the last one will take
+precedence.
.br
.B Examples :
.br
.I " iwconfig eth0 key 0123-4567-89"
.br
+.I " iwconfig eth0 key [3] 0123-4567-89"
+.br
.I " iwconfig eth0 key s:password [2]"
.br
-.I " iwconfig eth0 key [2] open"
+.I " iwconfig eth0 key [2]"
+.br
+.I " iwconfig eth0 key open"
.br
.I " iwconfig eth0 key off"
+.br
+.I " iwconfig eth0 key restricted [3] 0123456789"
+.br
+.I " iwconfig eth0 key 01-23 key 45-67 [4] key [4]"
.TP
.BR power
Used to manipulate power management scheme parameters and mode.
.br
-To set the period between wake up, enter
+To set the period between wake ups, enter
.IR "period `value'" .
To set the timeout before going back to sleep, enter
.IR "timeout `value'" .
-By defaults, those values are in seconds, append the suffix m or u to
-specify values un milliseconds or microseconds.
+To set the generic level of power saving, enter
+.IR "saving `value'" .
+You can also add the
+.IR min " and " max
+modifiers. By default, those values are in seconds, append the suffix
+m or u to specify values in milliseconds or microseconds. Sometimes,
+those values are without units (number of beacon periods, dwell,
+percentage or similar).
.br
.IR off " and " on
disable and reenable power management. Finally, you may set the power
.br
.I " iwconfig eth0 power timeout 300u all"
.br
+.I " iwconfig eth0 power saving 3"
+.br
.I " iwconfig eth0 power off"
+.br
+.I " iwconfig eth0 power min period 2 power max period 4"
+.TP
+.BR modu [lation]
+Force the card to use a specific set of modulations. Modern cards
+support various modulations, some which are standard, such as 802.11b
+or 802.11g, and some proprietary. This command force the card to only
+use the specific set of modulations listed on the command line. This
+can be used to fix interoperability issues.
+.br
+The list of available modulations depend on the card/driver and can be
+displayed using
+.IR "iwlist modulation" .
+Note that some card/driver may not be able to select each modulation
+listed independently, some may come as a group. You may also set this
+parameter to
+.IR auto
+let the card/driver do its best.
+.br
+.B Examples :
+.br
+.I " iwconfig eth0 modu 11g"
+.br
+.I " iwconfig eth0 modu CCK OFDMa"
+.br
+.I " iwconfig eth0 modu auto"
+.TP
+.BR commit
+Some cards may not apply changes done through Wireless Extensions
+immediately (they may wait to aggregate the changes or apply it only
+when the card is brought up via
+.IR ifconfig ).
+This command (when available) forces the card to apply all pending
+changes.
+.br
+This is normally not needed, because the card will eventually apply
+the changes, but can be useful for debugging.
.\"
.\" DISPLAY part
.\"
.SH DISPLAY
-For each device which support wireless extensions,
+For each device which supports wireless extensions,
.I iwconfig
will display the name of the
.B MAC protocol
of operation, the
.B Access Point
address, the
-.B bit-rate
+.BR bit-rate ,
the
.BR "RTS threshold" ", the " "fragmentation threshold" ,
the
and the
.B power management
settings (depending on availability).
+.PP
+The parameters displayed have the same meaning and values as the
+parameters you can set, please refer to the previous part for a
+detailed explanation of them.
.br
-See above for explanations of what these parameters mean.
+Some parameters are only displayed in short/abbreviated form (such as
+encryption). You may use
+.IR iwlist (8)
+to get all the details.
.br
-If the label for bitrate is followed by
+Some parameters have two modes (such as bitrate). If the value is
+prefixed by
.RB ` = ',
it means that the parameter is fixed and forced to that value, if it
-is followed by
-.RB ` : '
-it is only the current value (device in normal auto mode).
+is prefixed by
+.RB ` : ',
+the parameter is in automatic mode and the current value is shown (and
+may change).
+.TP
+.BR "Access Point" / Cell
+An address equal to 00:00:00:00:00:00 means that the card failed to
+associate with an Access Point (most likely a configuration
+issue). The
+.B Access Point
+parameter will be shown as
+.B Cell
+in ad-hoc mode (for obvious reasons), but otherwise works the same.
.PP
If
.I /proc/net/wireless
exists,
.I iwconfig
-will also display its content :
+will also display its content. Note that those values will depend on
+the driver and the hardware specifics, so you need to refer to your
+driver documentation for proper interpretation of those values.
.TP
.B Link quality
-Quality of the link or the modulation (what is the level of contention
-or interference, or how good the received signal is).
+Overall quality of the link. May be based on the level of contention
+or interference, the bit or frame error rate, how good the received
+signal is, some timing synchronisation, or other hardware metric. This
+is an aggregate value, and depends totally on the driver and hardware.
.TP
.B Signal level
-Received signal strength (how strong the received signal is).
+Received signal strength (RSSI - how strong the received signal
+is). May be arbitrary units or dBm,
+.I iwconfig
+uses driver meta information to interpret the raw value given by
+.I /proc/net/wireless
+and display the proper unit or maximum value (using 8 bit arithmetic). In
+.I Ad-Hoc
+mode, this may be undefined and you should use
+.IR iwspy .
.TP
.B Noise level
-Background noise level (when no packet is transmited).
+Background noise level (when no packet is transmitted). Similar
+comments as for
+.BR "Signal level" .
+.TP
+.B Rx invalid nwid
+Number of packets received with a different NWID or ESSID. Used to
+detect configuration problems or adjacent network existence (on the
+same frequency).
.TP
-.B invalid nwid
-Number of packets received with a different NWID. Used to detect
-configuration problems or adjacent network existence.
+.B Rx invalid crypt
+Number of packets that the hardware was unable to decrypt. This can be
+used to detect invalid encryption settings.
.TP
-.B invalid crypt
-Number of packets that the hardware was unable to decrypt.
+.B Rx invalid frag
+Number of packets for which the hardware was not able to properly
+re-assemble the link layer fragments (most likely one was missing).
.TP
-.B invalid misc
+.B Tx excessive retries
+Number of packets that the hardware failed to deliver. Most MAC
+protocols will retry the packet a number of times before giving up.
+.TP
+.B Invalid misc
Other packets lost in relation with specific wireless operations.
+.TP
+.B Missed beacon
+Number of periodic beacons from the Cell or the Access Point we have
+missed. Beacons are sent at regular intervals to maintain the cell
+coordination, failure to receive them usually indicates that the card
+is out of range.
.\"
.\" AUTHOR part
.\"
.SH SEE ALSO
.BR ifconfig (8),
.BR iwspy (8),
+.BR iwlist (8),
+.BR iwevent (8),
.BR iwpriv (8),
-.BR wavelan (4),
-.BR wavelan_cs (4),
-.BR xircnw_cs (4).
+.BR wireless (7).