About iw

iw is a new nl80211 based CLI configuration utility for wireless devices. It supports almost all new drivers that have been added to the kernel recently.

iw is still under development. Features are added 'as we go'. The only documentation that exists for iw is this page. Please help expand it.

There is a page listing use cases with iwconfig and iw: replacing iwconfig.

Getting iw

Release tarballs of iw are available from http://wireless.kernel.org/download/iw/.

Alternatively, you can download iw from git: http://git.sipsolutions.net/iw.git, the web interface can also create tarballs for arbitrary revisions.

Build requirements

• libnl >= libnl1

• libnl-dev >= libnl-dev-1

• pkg-config

Using iw requires you to have libnl, the first working version is 1.0 pre8 as this release introduced genl, Generic Netlink, which nl80211 relies on. Most distributions are shipping 1.1 these days. If your distribution's libnl is a wrong version then you'll have to download and compile libnl yourself for now (http://git.kernel.org/?p=libs/netlink/libnl.git;a=summary).

Help

Just enter

iw help

on your command line and it will print out the commands it supports.

Getting device capabilities

Use the following to get device capabilities for all devices, such as band information (2.4 GHz, and 5 GHz), and 802.11n information:

iw list

Scanning

iw dev wlan0 scan

Listening to events

Just use

iw event

When debugging, it can be useful to see the auth/assoc/deauth/disassoc frames, use

iw event -f

and sometimes timing information is also useful:

iw event -t

Getting link status

To determine if you are connected to an AP or not and if you are the last TX rate used you can use the command below.

Example output when associated to a legacy (non-802.11n) AP:

iw dev wlan0 link
Connected to 04:21:b0:e8:c8:8b (on wlan0)
        SSID: attwifi
        freq: 2437
        RX: 2272 bytes (18 packets)
        TX: 232 bytes (3 packets)
        signal: -57 dBm
        tx bitrate: 36.0 MBit/s

Example output when associated to an 802.11n AP:

iw dev wlan0 link
Connected to 68:7f:74:3b:b0:01 (on wlan0)
        SSID: tesla-5g-bcm
        freq: 5745
        RX: 30206 bytes (201 packets)
        TX: 4084 bytes (23 packets)
        signal: -31 dBm
        tx bitrate: 300.0 MBit/s MCS 15 40Mhz short GI

Example output when not connected to an AP:

iw dev wlan0 link
Not connected.

This would happen if you are not connected to an AP. To connect to an AP you can use iw connect if the connection requires:

• No encryption
• Uses WEP for encryption

If you need to connect to an AP with WPA or WPA2 encryption requirements then you must use wpa_supplicant.

Establishing a basic connection

You can use iw to connect to an AP directly if and only if the AP has:

• No encryption
• Uses WEP for encryption

It however should be noted that if you disconnect from the AP, which can happen quite frequently on a busy environment, you will need to reissue the command. If you do not want to do this you can just use wpa_supplicant which will automatically try to reconnect you when you get disconnected.

If you do choose to deal with disconnects yourself you can use iw connect as follows.

To connect to an AP that has encryption disabled, where its SSID is foo:

iw wlan0 connect foo

Suppose you have two APs with the SSID foo, and you know the one you want to connect to is on the frequency 2432, you can specify the frequency to use:

iw wlan0 connect foo 2432

To connect to an AP that uses WEP, you can use:

iw wlan0 connect foo keys 0:abcde d:1:0011223344

Getting station statistics

To get station statistic information such as the amount of tx/rx bytes, the last TX bitrate (including MCS rate) you can do:

$ iw dev wlan1 station dump
Station 12:34:56:78:9a:bc (on wlan0)
        inactive time:  304 ms
        rx bytes:       18816
        rx packets:     75
        tx bytes:       5386
        tx packets:     21
        signal:         -29 dBm
        tx bitrate:     54.0 MBit/s

Getting station statistics against a peer

If you want to get specific statistics against a peer you station is communicating with you can use the following:

sudo iw dev wlan1 station get <peer-MAC-address>

In the case of a STA the above <peer-MAC-address> would be the MAC address of your AP.

Modifying transmit bitrates

You can set preference for transmitting using only certain legacy bitrates. For example:

iw wlan0 set bitrates legacy-2.4 12 18 24

Setting preference for transmitting using MCS rates is not yet supported.

Setting TX power

You can set the txpower by using either the device interface name of the respective phy.

iw dev <devname> set txpower <auto|fixed|limit> [<tx power in mBm>]
iw phy <phyname> set txpower <auto|fixed|limit> [<tx power in mBm>]

Power save

To enable power save by default you can use:

sudo iw dev wlan0 set power_save on

For mac80211 drivers this means Dynamic Power Save gets enabled.

To query the current power save settings you can use:

iw dev wlan0 get power_save

Adding interfaces with iw

There are several modes supported. The modes supported are:

• monitor
• managed [also station]
• wds
• mesh [also mp]
• ibss [also adhoc]

To see a description of these please read our modes documentation.

For example to add a monitor interface:

iw phy phy0 interface add moni0 type monitor

where you can replace monitor by anything else and moni0 by the interface name, and need to replace phy0 by the PHY name for your hardware (usually phy0 will be correct unless you hotplugged or reloaded any modules.) If your udev is configured incorrectly, the newly created virtual interface may be renamed by it right away, use ip link to list all interfaces.

Note that in case you want to monitor 802.11n you will need to specify channel width (20 or 20/40MHz) and in case of 20/40MHz if the upper or lower channel is being used. To do so you would use:

iw dev <devname> set freq <freq> [HT20|HT40+|HT40-]

or

iw phy <phyname> set freq <freq> [HT20|HT40+|HT40-]

You can also specify channel instead of frequency:

iw phy <phyname> set channel <channel> [HT20|HT40+|HT40-]
iw dev <devname> set channel <channel> [HT20|HT40+|HT40-]

To create a new managed mode interface you would use:

iw phy phy0 interface add wlan10 type managed

Note that the interface is automatically put into AP mode when using hostapd.

Modifying monitor interface flags

You can customize the type of monitor interface you create. This can be very useful for debugging purposes on end user systems. For example suppose you want to help a user you can take advantage of the fact that a monitor interface in mac80211 uses radiotap to pass up to userspace additional data. Say we want to help a user fish out data without affecting the device's performance by setting it it to a full monitor interface an monitor interface with no additional monitor flags can be created as follows:

iw dev wlan0 interface add fish0 type monitor flags none

You can then request the user to use tcpdump on a session:

tcpdump -i fish0 -s 65000 -p -U -w  /tmp/fishing.dump

The nice thing about these type of alternative monitor interfaces is you can further extend radiotap even with vendor extensions to add more data to radiotap to help debug device specific features.

Keep in mind this requires drivers to honor mac80211's flag requests strictly, so drivers like ath5k and ath9k which still enable flags based on operation mode need to be fixed to take advantage of this.

Monitor flags possible

The following are flags you can specify:

• none
• fcsfail
• plcpfail
• control
• otherbss
• cook

Deleting interfaces with iw

The command line is:

iw dev moni0 del

Where "moni0" was the virtual interface interface that was created with the first command

Virtual vif support

There is a dedicated section for virtual vif support, see the iw vif page.

Setting frequency with iw

The command line is:

iw dev wlan0 set freq 2412 [HT20|HT40+|HT40-]

Setting channel with iw

The command line is:

iw dev wlan0 set channel 1 [HT20|HT40+|HT40-]

Updating your regulatory domain

The command line is:

iw reg set alpha2

Where "alpha2" is the ISO/IEC 3166 alpha2 country code. The information used and set comes from our regulatory infrastructure.

You can also use the latest wpa_supplicant (as of 0.6.7) now to change your regulatory domain, to do so just add a "COUNTRY=US" entry into your configuration for example.

Creating and inspecting Mesh Point interfaces with iw

You may add a mesh interface to drivers that support Mesh Point operation. Mesh Point interfaces have a mesh_id parameter which may be up to 32 bytes long. For example, to add an interface "mesh0" to device phy0 with mesh_id "mymesh",

iw phy phy0 interface add mesh0 type mp mesh_id mymesh

Mesh Point interfaces, by default, are configured on Channel 1. Mesh Point operation begins when the interface is brought up. In the default configuration, Mesh Point interfaces will automatically detect and attempt to create Peer Links with other Mesh Points (peers) having the same mesh ID. Use the station list and station statistics to see the peer list and Peer Link status.

After sending traffic (ex: pinging another mesh node), you may wish to see a list of Mesh Paths:

iw dev mesh0 mpath dump

Please see the open80211s.org HOWTO for further details on Mesh Point related commands and their output, as well as more examples. iw also provides commands for advanced Mesh Point configuration. These are documented in the Advanced Tinkering section of the open80211s HOWTO.

Setting up a WDS peer

To create a WDS peer you will first need to create an interface of WDS type, and then set the peer:

iw phy phy0 interface add wds0 type wds
iw dev wds0 set peer <MAC address>

In order for this to work the driver must implement the cfg80211 callback set_wds_peer(). mac80211 implements this callback, so the respective mac80211 driver would just need to support WDS type interfaces. What WDS will do is replace the first address on the 802.11 header with the peer address when TXing frames.