iwspy

iwspy interface [ command [ arguments... ] ]

Common commands include:
iwspy interface stats
iwspy interface qual
iwspy interface scan
iwspy interface ap [ address ]
iwspy interface freq [ frequency ]
iwspy interface get_range
iwspy interface set_threshold type value

interface
    The name of the wireless network interface to monitor (e.g., wlan0, wifi0).

stats
    Displays detailed statistics about the wireless interface, including link quality, signal level, noise level, and various discarded packet counts.

qual
    Reports the current link quality, signal level, and noise level for the specified interface.

scan
    Initiates a scan for nearby wireless access points (APs) and displays their signal quality and other relevant information.

ap [ address ]
    If an address (MAC address) is provided, displays statistics for that specific Access Point. If no address is given, it lists known APs and their current signal quality.

freq [ frequency ]
    If a frequency (in Hz, or as a channel number with 'ch') is provided, displays statistics related to that specific frequency. If no frequency is given, it lists known frequencies and their current signal quality.

get_range
    Displays the range of acceptable values for various quality and level metrics that the driver supports.

set_threshold type value
    Sets a threshold for a specific metric (type) to a given value. type can be: signal, noise, quality, rts, frag, crypt, retry, misc. This can be used for monitoring or logging purposes.

iwspy is a command-line utility used to monitor and report statistics from wireless network interfaces. It's part of the older wireless-tools suite, which was designed to interact with the Linux kernel's Wireless Extensions API. The command allows users to inspect various aspects of a wireless connection, including signal quality, noise levels, and discarded packet counts (fragment, crypt, misc). It can also be used to scan for nearby access points or retrieve statistics about specific frequencies or access points.

While still available on many Linux distributions, iwspy and the wireless-tools package have largely been superseded by the more modern iw command and the nl80211 kernel subsystem. However, it remains a useful tool for diagnosing basic wireless connectivity issues, such as poor signal strength, excessive noise, or packet loss, particularly on systems using older wireless drivers or for quick, snapshot-based diagnostics.

iwspy is part of the older wireless-tools package and is largely superseded by the iw command, which works with the more modern nl80211 kernel subsystem. It may not function correctly or at all with newer wireless drivers or kernel versions that exclusively rely on nl80211. Running iwspy typically requires root privileges. The interpretation of its output, particularly for signal and noise levels, can sometimes be device-specific or require understanding of dBm values.

Here are some common usage examples of iwspy:

1. Display current link quality:
iwspy wlan0 qual

2. Show extended interface statistics:
iwspy wlan0 stats

3. Scan for nearby access points:
iwspy wlan0 scan

4. Get range of possible values for metrics:
iwspy wlan0 get_range

5. Set a threshold for signal quality (e.g., 50 units):
iwspy wlan0 set_threshold quality 50

When using commands like stats or qual, iwspy typically outputs fields such as:

Link Quality: An abstract value indicating the overall quality of the connection, often a percentage or a fraction (e.g., 70/100). Higher is better.

Signal Level: The strength of the received radio signal, usually in dBm (decibel-milliwatts). More negative values indicate weaker signals (e.g., -50 dBm is stronger than -80 dBm).

Noise Level: The amount of background electrical noise detected, also in dBm. More negative values indicate less noise, which is better.

Discarded Packets: Various counters for packets dropped due to fragmentation issues (frag), encryption errors (crypt), retransmissions (retry), or other miscellaneous reasons (misc).

Understanding these values is crucial for diagnosing wireless performance issues.

iwspy emerged as part of the wireless-tools suite, developed by Jean Tourrilhes. This collection of utilities was designed to provide user-space control and information retrieval for wireless devices leveraging the Linux kernel's Wireless Extensions API. It was a foundational tool for wireless management before the advent of the nl80211 kernel subsystem, which brought a more unified and robust API for wireless device management. While its development has largely ceased in favor of iw, iwspy remains available on many systems for compatibility with older hardware or for specific diagnostic needs.

iwconfig(8), iwlist(8), iw(8), ip(8)