Contents
- About iw
- Getting iw
- Build requirements
- Help
- Getting device capabilities
- Scanning
- Listening to events
- Getting station statistics
- Getting station statistics against a peer
- Adding interfaces with iw
- Deleting interfaces with iw
- Setting frequency with iw
- Setting channel with iw
- Updating your regulatory domain
- Creating and inspecting Mesh Point interfaces with iw
About iw
iw is a new nl80211 based CLI configuration utility for wireless devices. Currently you can only use this utility to configure devices which use a mac80211 driver as these are the new drivers being written – only because most new wireless devices being sold are now SoftMAC. Please see our list of mac80211 drivers.
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
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 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.
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 out 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
Setting frequency with iw
The command line is:
iw dev wlan0 set freq 2412
Setting channel with iw
The command line is:
iw dev wlan0 set channel 1
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 is similar to an SSID on an infrastructure network. 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 attempt to create Peer Links with other Mesh Points having the same mesh ID. To see a list of such peer links, issue a station dump:
iw dev mesh0 station dump
After sending traffic (ex: pinging another mesh node), you may wish to see a list of mpaths:
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.