IWSPY(8)

💖 IWSPY(8) — the wireless-stats girlies' manual 💖

okay bestie, so this is iwspy, a little legend from the Linux Programmer's Manual, section 8 (that's the sysadmin/root-adjacent girlies section, iykyk). Her whole job? Get wireless statistics from specific nodes. That's it. That's the gig. She's a spy 🕵️♀️💅 and she's watching your link quality fr fr.

✨ SYNOPSIS ✨

iwspy [interface]
iwspy interface [+] DNSNAME | IPADDR | HWADDR [...]
iwspy interface off
iwspy interface setthr low high
iwspy interface getthr

no cap, that's the whole vibe. five little ways to summon her 🎀

🌸 DESCRIPTION 🌸

So iwspy is literally used to set a list of addresses to monitor on a wireless network interface, and then to read back the quality-of-link information for each one of those addresses. The tea she gives you is exactly the same as what's sitting in /proc/net/wireless: the quality of the link, the signal strength, and the noise level. Three lil stats. That's her whole personality. 💜

Here's the thing though — this info updates each time a new packet is received, so every single address you add to that list adds some overhead in the driver. She's not free, bestie. She's got a cost. 🫶

🚨 Also important, and I need you to hear me: this functionality works only for nodes that are part of the current wireless cell. You can NOT monitor Access Points you are not associated with (for that, go use Scanning instead), and you can't monitor nodes in other cells either. Periodt. ✋

And in Managed mode, in most cases the packets are relayed by the Access Point, so what you'll actually be getting is the signal strength of the Access Point, not of the node you thought you were spying on. 🙈 The way that Managed mode just lies to you a little bit.

For those exact reasons, this functionality is mostly useful in Ad-Hoc and Master mode. That's where she eats. 🔥

🦋 PARAMETERS 🦋

okay so first things first: you may set any number of addresses, up to 8. Eight. That's the cap. The limit. The ceiling. The 8 girlies. 💀

• DNSNAME | IPADDR — Sets an IP address, or in some cases a DNS name (she'll use the name resolver for that). But here's the drama: the hardware works with hardware addresses, so iwspy has to translate that IP address through ARP. And in some cases that address might not be in the ARP cache yet, and then iwspy will just fail. 😭 In those cases: go ping(8) that name/address first and then retry. Works every time, bestie. 🎀
• HWADDR — Sets a hardware (MAC) address. Note that this address is not translated & checked the way the IP one is — she takes it at face value, main character energy. The address must contain a colon (:) to be recognised as a hardware address. That colon is the whole passport. 💅
• + — Adds the new set of addresses at the end of the current list instead of replacing it. The address list is unique for each device, so every user should really use this option to avoid conflicts. Sharing is caring, bestie. 🫶
• off — Removes the current list of addresses and disables the spy functionality entirely. She's clocking out. 👋✨
• setthr — Sets the low and high signal strength threshold for the iwspy event (for the drivers that support it, obviously, not everyone's built like that). Every time the signal strength for any of the addresses monitored with iwspy goes lower than the low threshold, or goes higher than the high threshold, a Wireless Event gets generated. 🌈 This is the one for monitoring link outages without having to run iwspy periodically. She works smarter, not harder. 👑
• getthr — Retrieves the current low and high signal strength threshold for the iwspy event. Reading, not writing. Just vibing and reporting. 🍓

🎀 FILES 🎀

• /proc/net/wireless

that's the file, that's the source of truth, that's where the quality/signal/noise trio lives. ⭐

💜 SEE ALSO 💜

• iwconfig(8)
• iwlist(8)
• iwevent(8)
• iwpriv(8)
• wireless(7)

the whole friend group honestly, go say hi 🌸🧚

net-tools · 31 October 1996 — yes bestie, this page is a 1996 baby and she is still absolutely serving. iconic, honestly. 🎀💖✨ slay.