Sunday, 3 November 2019

Wireshark Plugin To Capture Wireless Frames Using a WLANPi (Windows 10)

Want to be able to capture wireless frames via a WLANPi using just Wireshark on your Windows 10 machine? ...And be able to configure the capture configuration on the WLANPi using just Wireshark too?  Read on...



Earlier this year, I put out a command-line script called WLANPiShark that allowed Windows 10 users to configure a WLANPi and initiate a frame capture stream in to Wireshark. Though a little clunky, it worked quite reliably for most of the time and, judging by feedback I received, was quite popular.

As Windows users, we've always been the poor cousins to our Apple brethren who are able to use their Macbook to capture over the air using the internal NIC card of their Mac in monitor mode. Getting a low cost adapter that could be put in to monitor mode on a Windows machine was as rare as hen's teeth.

Having access to the WLANPi and being able to fire up WLANPiShark opened up wireless capturing to many folks who have to use Windows machines, but were unable to easily get a wireless capture (without investing in some quite expensive tools).

With the arrival of Wireshark 3.0.x, new options became available that allow us even better ways to capture in Windows using a WLANPi. SSHDump was a newly introduced package that allows a easy method of initiating an SSH session in to a remote device and firing up commands to initiate a tcpdump capture stream (in a far less clunky way that we did in WLANPiShark).

Adrian Granados kicked off a project called wlan-extcap on GitHub, based on a Python script, that leveraged the new SSHDump Wireshark package via a plugin that he created. It also added new functions directly it to the Wireshark GUI to allow configuration of a WLANPi (...yes, the guy's a genius coder!). The project was primarily aimed at Mac users, but could potentially be used by Windows users if they installed Python on their Windows machine.

Inspired by his amazing work on his project, I decided to take the principles of his project and write a similar utility written in native Windows batch-file format. This would allow Windows users to simply copy a batch file in to their Wireshark directory to obtain the same functions as Adrian's plugin and not have to worry about adding any supporting software packages.

The result is my own project called: wlan-extcap-win

Rather than documenting the plugin on my blog, I have created a fairly lengthy ReadMe on the GitHub site where the script has been developed so that you can download the script and give it a try.

I hope you find this just as much fun as WLANPiShark and even easier and more convenient to use.

References



Friday, 23 August 2019

Wireless Analysis Resources



Wireless traffic capture and analysis can be a tricky business and is often seen as something of a dark art to newcomers to the world of Wi-Fi. There are a huge variety of options when considering how to capture wireless traffic over the air, with many of the solutions being paid-for options that may be out of reach for many individuals.

Many people approaching wireless analysis may already be familiar with Wireshark, based on their previous experience on wired networks, where they may have used it for troubleshooting and analysis purposes.  They may wonder if they can use Wireshark for their initial foray into wireless analysis.  Using Wireshark for wireless capture and analysis on Wi-Fi networks can be a little tricky and presents the newcomer with a whole new slew of frame types to learn.

There are many good articles, videos and podcasts out there looking at wireless analysis, particularly if Wireshark is your tool of choice. I thought it would be good to pull them together in one place to make it easier for the newcomer to find the resources they may need. I've grouped together various resources below that will hopefully help those on their Wireshark/wireless analysis journey.

Please let me know if you have other resources that you find or have found useful yourself (wifinigel@gmail.com)

Wireless Capture:

Wireshark Customization:

Wireless Analysis Podcasts:

CWAP Study Notes:

Books:

Paid-for Online Training:

Online (Cloud) Capture Analysis Tools:




Tuesday, 11 June 2019

Metageek Wi-Spy Air Review

In this article, I take a look at the recently released Metageek “Wi-Spy Air” wireless analysis module and its accompanying “Air Viewer” smartphone application. Metageek supplied me with a beta unit a couple of months ago to help with some initial testing of the product. I’ll take a look at some of the features of the product, together with some observations of my testing of the product to date.

Fig 1: Spectrum Analysis in Air Viewer (Smartphone (Landscape)  Screenshot)

Background

Having the right tool for the job when supporting Wi-Fi networks is essential. Those tools may come in many shapes and sizes, with each having its place depending on the task at hand.

Whichever tool is chosen, it needs to be  “professional” grade to ensure it can provide the depth and quality of data required to support the mission critical infrastructures that Wi-Fi networks have become. To date, professional wireless tools for both IOS and Android smartphones have been thin on the ground (in my experience), with many being few low-grade applications that offer rudimentary Wi-Fi scanning capabilities. This is, in part, due to the lack of access to Wi-Fi related data being available to software developers on both platforms.

Given the fact that the majority of IT support staff will be equipped with a smartphone of some type, it makes a lot of sense to have an option that allows them to perform Wi-Fi network diagnostics using the smartphone in their pocket. Metageek have stepped in to this area of the market with their new Metageek “Wi-Spy Air” module and its accompanying “Air Viewer” smartphone application. The solution allows the Wi-Spy Air module to be plugged in to the smartphone lightning (Apple) connector or micro-USB (Android) connector and gather Wi-Fi “over-the-air” data, presenting it in the AirView smartphone app. And, by Wi-Fi data, we’re not talking just lightweight lists of SSIDs and signal level you might get off a freebie app store wireless scanner, this thing is pulling packets out of the air for analysis, as well as providing RF spectrum analysis data!

What Does The Wi-Spy Air Look Like?

Here’s a quick overview of the hardware: the Wi-Spy Air unit is a plastic moulded case with an external (detachable) antenna and a mini-USB connector to attach the cable that hooks up to the smartphone. A mini-USB to micro-USB cable is provided for Android phones/tablets, and a  mini-USB to Lightning connector for Apple phones/tablets.

The unit is self-powered by 4 x AA batteries, so that it won’t drain your phone battery. They probably account for around 50% of the unit’s size.

The images below provide an overview of the physical aspects of the Wi-Spy unit:

Fig 2: Wi-Spy Air Component Parts

Fig 3: Wi-Spy Air Battery Compartment

Fig 4: Wi-Spy Air Hooked Up To Android Phone (Samsung S7)

The Wi-Spy Air unit has no on/off switch, it simply needs to be connected to the smartphone to activate it. There is a red LED that illuminates on the unit to indicate it is active. On my Android phone, the Air Viewer app automatically launches as the Wi-Spy Air is plugged in to the phone (I have not tested the Apple version of the app).

What Does The Air Viewer App Look Like?

Once the Wi-Spy Air is connected to a smartphone the Air Viewer App provides visibility of the data it collects. The interface is simple to use and initially looks pretty much like your average Wi-Fi scanner app. But, don’t be fooled, it actually gives access to very detailed information about both wireless networks and clients. Due to the limited real-estate of the smartphone or tablet screen, it relies on scrolling and drilling down from screen to screen to reveal the true depths of detailed network data it collects. It took me some time to get used to using it as I’m so used to laptop-based apps, but I was impressed with the detailed data available once I started digging around and became familiar with the app navigation.

At the bottom of each screen is a navigation bar to access the 3 main app areas:

  • Networks : the Wi-Fi scanner (on steroids) showing SSID details
  • Channels: the spectrum analysis area (with network a details overlay if required)
  • Setup: stop/start, channel selection & scan rates

We’ll take a quick look at each of these areas below:

Networks

On the face of it, the “Networks” area is a simple Wi-Fi scanner application. It scans the bands configured in the “Settings” section (both 2.4 & 5GHz are supported) and shows the familiar channel occupancy of various SSIDs overlaid on each channel. However, thanks to the Wi-Spy Air module, this is far more sophisticated than a simple Wi-Fi scanning app. The Wi-Spy Air module performs the channel scanning, rather than relying on the Wi-Fi chipset of the phone. It has the capability to capture and decode 802.11 frames, which provides far deeper analysis capabilities than a simple smartphone scanner.

Scrolling down, an information panel for each SSID is shown, showing summary details for each one. By tapping the panel, all instances of the selected SSID are highlighted in the spectrum display - the example below shows my home SSID highlighted, with 3 BSSIDs shown:


Fig 5: Air Viewer > Networks tab with my home network selected

Each SSID allows a drill-down to reveal more detail about the underlying BSSIDs and clients. Drilling down into the SSID shown above reveals a wealth of information, including security methods, client counts, PHY types and BSSID summary information:

Fig 6: Air Viewer > Networks tab > drill down in to my home network

Fig 7: Air Viewer > Networks tab > scroll down to BSSID summary of home network

Drilling down in to one of the BSSIDs starts to show the real power of the app and the depth of the collected data.

In addition to the usual suspects of BSSID MAC, security method, channel details, PHY type etc., we also get access to data that relies on frame analysis. Details such as retry rates, channel utilization, client counts and even AP names are made available if present in the 802.11 beacon frames. The screenshot below shows the BSSID data available. It’s also good to see an SNR value shown - another value you won’t see in a standard scanner app:

Fig 8: Air Viewer > Networks tab > drill down in to BSSID

Once you’ve looked through the BSSID data, you can scroll down to see the clients that have been detected as associated with the BSSID. This is an amazing level of detail for a smartphone app, which, again, relies on the 802.11 frame decode capabilities that the Wi-Spy Air provides. A high level summary of the clients is initially shown, with the option to drill down. Note that this summary includes client utilization and retry information to highlight potential problem clients:

Fig 9: Air Viewer > Networks tab > drill down in to BSSID, scroll down to clients

Each client has the option to drill down even further to reveal client-specific detail including the AP it is connected to (if its name is broadcast by the AP), its signal level (observed from the Wi-SPy Air), manufacturer, phy type,  retry rate and utilization. A summary of the client’s roaming history is also shown by the Air Viewer app:

Fig 10: Air Viewer > Networks tab > drill down in to BSSID, drill down to specific client


Channels 

The “Channels” area of the app is where we see the spectrum analysis capabilities provided by the Wi-Spy Air. For those less familiar with spectrum analyser tools, the role of this tool is to report the levels of RF energy detected across the Wi-Fi bands. It’s job is not to collect and decode Wi-Fi (802.11 frames), but to detect raw RFenergy. This is the only way to detect if your Wi-Fi network is suffering interference from non-Wi-Fi RF sources, which can be very disruptive to Wi-Fi network performance.

A spectrum analyser is an essential tool for maintaining Wi-FI networks and definitely falls into the “professional level tool” category. This functionality is only provided by specialist wireless tools - the existing Metageek Chanalyzer/DB3 solution for Windows provides similar functionality.

When the “Channels” area is selected, the Wi-Spy Air scans the band selected to show the  RF energy levels across that band. Wi-Fi networks detected by Wi-Spy Air can be turned on or off as an overlay via the “Networks On” button. This can provide some context for the RF energy levels observed by the spectrum analysis scanning. The spectrum plot itself is shown as a spectrum density graph, with the colouration of the plot indicating the relative utilization level across each part of the band. As the level of RF airtime occupancy rises, the colours change from a “background/low ” level of purple through to green, yellow and red to indicate increasing density (and possibly interference for non-Wi-Fi sources).

The screenshot below shows the 2.4Ghz band with low levels of spectral activity and channel 6 highlighted in the networks overlay:

Fig 11: Air Viewer > Channels tab > select a specific channel (6)

To show the impact of an interfering device, I fired up a cheap 2.4Ghz video camera near to my laptop and the Wi-Spy Air. The resulting spectrum plot is shown in the screenshot below. Note the waveform with 3 peaks that indicates the area of 2.4Ghz affected by this interferer. Also, note the red colouration due to the high duty cycle of the interfering device. For anyone investigating wireless network issues, this would be invaluable information:

Fig 12: Air Viewer > Channels tab > video camera interferer

In addition to detecting interferers, a spectrum analyser may be used to indicate areas where Wi-Fi networks may be causing higher levels of spectrum utilization (which may be an indicator of capacity issues). In the next example, I associated my laptop with an AP on channel 11. The SSIDs on channel 11 are highlighted below by selecting the channel in Air Viewer:

Fig 13: Air Viewer > Channels tab > channel 11 selected to show SSIDs

Next, I fired up a speed test on my laptop to generate some Wi-Fi traffic on channel 11 and observed the change in spectral density on Air Viewer that was reported by the Wi-Spy Air. You can see the green and yellow colouration that resulted from the increase in traffic (and hence airtime/spectral density) on channel 11:

Fig 14: Air Viewer > Channels tab > client running a speedtest on channel 11

As well as the spectrum plots discussed above, it is also possible to observe much of the SSID/BSSID/Client information that is presented in the Networks section of the app. This is achieved by scrolling down to the channel summaries below the spectrum plots shown above.

Settings

The settings areas provides simple controls to allow control of channel scanning of Wi-Spy Air and adjustment of scan rates. A sample screenshot is shown below.

Fig 15: Air Viewer > Settings tab

Conclusion

I think I have been guilty of initially underestimating this product. My initial impressions were based on the (incorrect) assumption that it was similar to a basic Wi-Fi scanner app with maybe a little spectrum analysis thrown in for good measure. I’m also guilty of looking at this through the eyes of someone who has been a long-time user of a variety of laptop spectrum analyser tools, with their larger screen real-estate and a variety of supporting hardware platforms.

As I said at the beginning of this article, maintaining Wi-Fi networks requires professional level tools. This is a professional level tool. Metageek have succeeded in packing a lot of functionality in to a small package that provides the convenience of both detailed Wi-Fi network analysis, together with spectrum analysis, and making it available via a smartphone app.

In my opinion, the obvious sweet spot for this product is going to be for organizations who have technicians who need a device that can provide detailed diagnostic information in a small, convenient form factor. Obvious sectors would be service providers and large Enterprises who may have teams of technicians covering a number of technology areas who need to convenience of whipping out a small device from their toolbox and hooking it up to their phone to perform detailed wireless diagnostics.

I can also see the smaller form factor of the Wi-Spy Air being useful in some instances for Wi-Fi pros too. Occasionally, we all hit those instances where we have to travel uber-light, enter areas where laptops may not be allowed or just want to have a device to give to a colleague to “go get some data”. On those occasions, the Wi-Spy Air could be very useful.

Apart from the features I’ve seen and tested to date, I know that this is an evolving product. Given its already-impressive capabilities, I can imagine some exciting times ahead for this product. I would hope, at some stage, to see some type of reporting or data export capabilities, which raises all sorts of fascinating remote support options. Also, given the data that could be derived from the obvious frame capture capabilities of Wi-Spy Air, there is scope to provide even richer app information.

I think this tool is going to be well placed in a market segment that is almost certain to see continuing growth. I look forward to seeing the evolution of this innovation from Metageek.

References

List of references from this article & further reading:


Notes


  • The screenshots in this article were taken in May 2019 using a Samung S7 (Android) smartphone. The layout and content of the Air Viewer app is likely to change over time and between device types.
  • The review unit and application were provided to me free of charge by Metageek for support of their beta program. I have no commercial arrangement with Metageek for this article and am under no obligation to provide any opinions other than my own.


Friday, 4 January 2019

The Windows WMM User Priority Issue - A Fix?

There is a known issue with Windows clients when it comes to marking applications for QoS over wireless. In short, even if a Windows client application is configured to use DSCP 46 (EF), for example to mark voice traffic, it will translate this over the air to to use a layer 2 UP value of 5, rather than 6. This means that it will end up in the Video WMM queue rather than the Voice queue that we’d like. This has an impact on traffic prioritization over the air and could have a negative impact on our high priority traffic. This has been an issue that people have just “lived with” for quite a while, but I suspect there is a solution to this issue. I’m “putting this out there” for feedback as I can’t find any information about others using this technique. I’d like feedback from my peers to understand if the approach is viable or anyone else has used/tried it

Background

Generally in my articles, I like to provide plenty of background information about a topic to encourage others to research and learn. But, in this instance, I’ll get straight to the point as there is too much ground to cover. If you’d like to know more about this topic, then please have a look at the following references:

The issue is shown on slide 47 of the presentation from Cisco Live referenced above:


As you can see, Microsoft translate the 3 most significant bits of the DCSP value in to a UP value of 5, which means that packets that are correctly marked with DCSP for EF end up in the WMM video queue, rather than the voice queue. The slide below (also borrowed from the same presentation) demonstrates the point (hopefully my friends at Cisco will excuse this liberty I'm taking with their content):



This means that both voice and video traffic (marked with DSCP 46 and 34 respectively) end up in the same WMM queue over the air from the client to an access point. Ideally, we want traffic marked with DSCP 46 to end up in the WMM voice queue and traffic marked with DSCP 34 to end up in the WMM video queue. But, this doesn’t happen by default when assigning QoS marking via the group policy editor

QoS Marking Tests


Application Marking With Group Policy Editor


The traditional method of marking applications with QoS is to use the Windows group policy editor. I 'll run through a basic example to show the process and result. However, note that the settings shown are definitely not what you would use in production. I’ll mark all Skype traffic from my laptop to send with DSCP value 46. In the real world, voice, video signalling etc. would be marked individually, so don't take this as a config to use in the real world.

I’ll then make a test voice call and capture a data frame that contains a Skype packet. I’ll also use an open SSID so that we can see both layer 2 & layer 3 decodes.

Here is the policy in the Group Policy Editor, showing the QoS policy:


Here is the resulting Skype packet showing the layer 2 priority 5 marking, together with the layer 3 DSCP marked (as expected) with EF. As mentioned previously, note that the layer 2 marking is using UP 5, so will be using the video WMM queue over the air, rather than the voice WMM queue we’d like to use:



Application Marking With Powershell


Ok, now to get to point of this blog article…

If we repeat the previous exercise, but this time set the QoS policy via Powershell, we can actually specify the layer 2 QoS marking that we actually want (i.e. set it to 6).

This is achieved by using the command “New-NetQosPolicy” in a Powershell console on your Windows laptop. Note that you need to run the command in a Powershell console opened as an administrator.


Note that we have now removed our original QoS Policy applied via the  Group Policy Editor (see screenshot above)

Here is the syntax required, together with a screenshot of the command being applied in Powershell:

New-NetQosPolicy -Name "Skype" -AppPathNameMatchCondition "Skype.exe" -DSCPAction 46 -PriorityValue8021Action 6



One point to note here is that when applying policy by this method, it is not shown in the policy configuration of the Group Policy Editor.The only way to check the applied QoS policy is to the use the “Get-NetQosPolicy” in a Powershell console on the Windows machine.

Now, if we look at the Skype packets from my laptop during a test call, we see that layer 3 is still marked with EF, as expected, but layer 2 is now marked with UP 6. This means that our traffic will use the correct WMM queue (i.e. the voice queue) over the air.



Using the correct WMM queue will ensure that our voice traffic can leverage the additional advantage in ECDA that this provides, which could be quite important on a busy wireless network carrying a mix of voice, video & data.

Questions


OK, this seems to be a reasonable approach to technically achieve the desired outcome for improved QoS marking over the air for Microsoft Windows clients. However, I don’t see anyone recommending this approach…

So, my questions are:

  • Is this a valid approach? 
  • Has anyone else used this approach? 
  • What are the pitfalls of this approach (if any)? 
  • Are there any flaws in my logic here? It seem strange that I don't find any information anywhere about this

Just a couple of caveats:

  • I’ve only tried this on my personal WIndows 10 machine that runs Win 10 Pro 
  • I’ve no idea if this approach would be scalable or supportable in a large Enterprise environment
  • I’m not a Windows or AD “Expert”

Please...let me know your thoughts (comments section at the bottom of this blog page, or track me down on Twitter - @wifinigel)

References


List of references from article & further reading:



Wednesday, 2 January 2019

WLANPiShark: Wireless Capture With a WLANPi on Windows


*** Note this article is out of date. Please use the information on this page until I get this artcile updated: https://github.com/WLAN-Pi/WLANPiShark2 ***

One huge advantage that Apple Mac users have over owners of Windows 10 machines is the ability to perform a native 802.11 wireless packet capture direct from their built-in wireless NIC. This is extremely useful for wireless pros who want to take a quick over-the air-capture into Wireshark to analyze traffic for troubleshooting purposes. Windows users don’t have the luxury of this native wireless capture capability. In this article, we take a look at how we can use a WLANPi unit as an adapter to capture traffic over the air, straight into Wireshark on a Windows machine. With the WLANPi being powered from the USB of the laptop, this is a super convenient, portable and powerful capture method that gets Windows users a little closer to the capabilities of their cousins on Apple Macs.

Background


I’ve always felt really bad for Windows users who want to use their laptop for wireless packet capture purposes. I’ve been a long time Windows user and have often looked at how I might best use my Windows laptop to capture 802.11 frames over the air. This is a trivial exercise for Apple Mac users, as the native drivers on Macs allow their adapters to be put in to monitor mode and capture frames over the air. It’s been a goal of mine to find a low-cost solution to enable Windows users to be able to perform over the air captures. It was something I dreamed of the whole time I was studying for my CWAP in the days before I could afford a Mac!

Windows wireless NIC drivers, unfortunately, do not provide the required monitor mode capability to allow wireless packet capture. I’m guessing this is down to the huge variety of NICs that may be used by Windows devices. It simply isn’t worth the development costs for NIC manufacturers to code in the capability for their wireless NIC drivers to support monitor mode (as most users will never need it!). There are one or two software companies that provide specialist NIC drivers that they have developed for their own capture software for Windows, but these are only available with the purchase of specific packet capture software, which has a significant price tag.

There are a few lower cost software solutions that support Windows packet capture, but they rely on wireless NDIS drivers that have a number of compromises when capturing packets. I’m guessing this is because they aren’t operating directly at the NIC driver level. Limitations include the inability to select capture channel widths and limited/inaccurate RadioTap header information. These are OK(ish)...but they don’t provide the flexibility and depth of information I need to see for activities such as troubleshooting.

Earlier this year, I became interested in the “WLANPi “initiative started by Jerry Ola at the Phoenix 2018 WLAN Pros Conference. Jerry’s idea was to develop a single board computer platform equipped with a suite of free tools for wireless LAN pros to use in their testing and commissioning work. A number of excellent open source tools already exist, and were included in the distribution he created for the platform (find out more here). The WLANPi is a Linux-based (Debian), single board computer in the same vein as the Raspberry Pi, but is provided as a much smaller form factor. It also has low power requirements, so can be run from the USB port of a laptop. It has no onboard wireless adapter, but there is good driver support for the Comfast CF-912AC adapter, which is relatively low cost NIC that can be plugged in to the USB socket of the WLANPi. The WLANPi also has a Gig Ethernet port, which allows high speed data transfer between the WLANPi and a laptop. This combination of characteristics means that it can be used as a powerful wireless capture device, hooked up to a Windows laptop via its Ethernet port, and powered directly by the laptop’s USB port. Here is a picture to show you what it looks like. You can think of the WLANPi as a wireless adapter on steroids for your Windows laptop:



To allow the WLANPi to capture frames over the air, I have created a Windows batch file (a script file) that will set up the WLANPi to capture frames, then stream the capture over the Ethernet port of the WLANPi to a copy of Wireshark running on your laptop.

This might sound complicated, but trust me...after some initial setup, it’s really straightforward to use. Here is an overview diagram:



Quickstart Guide


For those of you in a bit of rush and who are comfortable with all of the concepts shown later in this article, here’s a very quick “get-you-going” setup guide. (For everyone else, I suggest you carry on to the next section of this article.)

  • Build/obtain a WLANPi with the latest image installed (unmodified) 
  • Plug in a Comfast CF-912AC adapter to a USB port on the WLANPi 
  • Install Wireshark on your Windows laptop - note the installation location 
  • Install Putty on your laptop (we need Plink which is installed along with Putty) - note its installation location 
  • Download the windows batch file from GitHub to your Windows laptop (use “Clone or Download” to download the zip archive) - https://github.com/wifinigel/WLANPiShark 
  • Place the WLANPiShark.bat file in a convenient directory on laptop (your home directory) 
  • Edit WLANPiShark.bat file with notepad to configure user-configurable variables 
  • Hook up the WLANPi to your laptop with a USB to microUSB cable (provides power) 
  • Hook up the WLANPi to your laptop with an Ethernet cable (streams capture data) 
    • Ethernet port of laptop must be set to use DHCP 
  • Wait for WLANPi display to show its 169.254.0.0/16 address - note this address for later (this may take around 30 secs to appear) 
  • Open Windows command shell (i.e. cmd), change to the directory where WLANPiShark.bat installed and type : WLANPiShark.bat -h (verify help screen shown) 
  • In the Windows command shell, start test capture with: WLANPiShark.bat -c 1 
  • You’re done...


What You’ll Need


You’re going to need a few component parts to get things set up to allow you to try out this packet capture method for yourself. If you’ve ever attended one of the WLAN Pro’s Conferences in the recent past, you may already already have most of these components. If not, I’ll give you a few pointers along the way.

WLANPi Hardware


To complete this exercise, you must have a WLANPi. These have been provided as part of the some the deep dive sessions at recent WLAN Pros conferences, so you may already be lucky enough to have one.

If you don’t have one, I’d advise you think about getting hold of one for a number of reasons: it comes packed with some useful free performance tools, it’s a great platform to practice your Linux and coding skills, and it will allow you to have a go at trying out various projects (such as the one in this article) that are being developed by enthusiasts in the WLAN community.

If you don’t have one, you have two options:

  • Buy one pre-built from the WLAN Pros store: https://www.wlanpros.com/shop/nanopi-neo2-kit-usb-nic/ 
  • Buy one direct from the supplier, but do the build and burning work yourself (full instructions on this site: http://www.wlanpi.com). Note that you will also need to buy a Comfast CF-912AC adapter and micro SD card reader if you use this option - the full parts list is available from WLANPi.com. (If you buy direct from the supplier, the platform is known as a NEO2, not a WLANPi)

Once you receive your WLANPi, ensure that it has the latest image from WLANPi.com installed. Some of the older images had NIC drivers issues, so go with the latest and greatest. Once installed, do not globally update the packages using ‘apt-get’ on the WLANPi CLI, as this may overwrite the install NIC drivers and stop things working as expected. I tend to just stick to the vanilla image as provided at WLANPi.com.

Windows 10 Laptop


I’m guessing you already have a Windows 10 laptop, otherwise you likely wouldn’t have got this far in your reading! I’ve only tested the batch file I created on Windows 10, so I’m not sure if this will work for any of you diehard Windows 7 users out there.

Software Packages


There are a couple of software packages you will need to install on your Windows laptop, if you don’t already have them:

Wireshark is our (free) packet capture and decode software, which hopefully needs no further explanation.

Putty is a free terminal emulation software that is used by many network engineers who want a robust, reliable piece of software to SSH to devices around their network. Putty software is installed with a number of supporting utilities. We are not interested in Putty itself, but in the accompanying utility: Plink. Plink allows us to send single commands to devices over an SSH session. You don’t need to install Plink separately - it is automatically installed as part of the standard Putty installation.

When installing Wireshark and Putty, make a note of the location in which they are installed. This will be useful to us later when configuring the batch file that ties everything together and performs the magic. If you already have both software packages installed you may need to use the search tools in Windows File Explorer, or poke about in some well known install locations such as “C:\Program Files\ or ”C:\Program Files (x86)” to find their installation location.

Networking


As we’ll be hooking up the Ethernet port of our laptop to the WLANPi, we need to configure the IP setup of our laptop Ethernet adapter. To keep things nice and simple, just set the laptop adapter to use DHCP - no static IP addressing is required.

The reason for doing this is that when connected to the WLANPi, it will fall back to using its RFC3927 address (169.254.0.0/16). The WLANPi will also do the same thing, so that they can communicate using their 169.254.0.0/16 addresses when directly connected. This keeps thing nice and simple and avoids having to keep configuring static addresses every time you need to use the WLANPi with your laptop.

Hooking it all Together


Once you’ve installed the required software on your Windows laptop, you’re ready to hook everything together.

To connect your laptop to the WLANPi, you’ll need 2 cables:

  • USB to micro-USB cable (supplied with the WLANPi) 
    • Connect this between your laptop USB port and the micro USB port of the WLANPi - this will power the WLANPi 
  • Standard Ethernet UTP cable 
    • Connect this between your laptop Ethernet port and the Ethernet port on the WLANPi

When the WLANPi is connected to the laptop, it will initially show a 127.0.0.1 address on its display. After 30 secs or so, it will fall back to a 169.254.x.x address, which will replace 127.0.0.1 on the WLANPi display.

Obtaining and Configuring the Batch File


The glue that pulls all of this together is a Windows batch file that I wrote that will automatically set up the WLANPi to start collecting data over its WLAN adapter, and then stream the captured data back to Wireshark on your laptop. Once you’ve got hold of the batch file, you need to do a one-time configuration exercise, then it’s good-to-go to run from the command line of your Windows laptop.

Lets step through what you need to do:

1. Get the Latest Batch File

Visit my Github repository and download the latest file archive that contains the batch file. If you go to the GitHub site and select “Clone or download”, then select the “Download Zip” option (see screenshot below)



You will then be prompted to download a zip archive which contains the batch file that you will need. Download the zip file to a suitable location on your laptop so that you can unzip it and access the files that it contains.

2. Extract the Batch File

Once you have downloaded the zip file, open Windows file explorer, right click on the downloaded file and hit the extract option - this will extract all files in the archive to a new directory.

There are several files included in the zip file that is downloaded. The only file we are interested in using is the file titled “WLANPiShark.bat”:



Using Windows file explorer, move the “WLANPiShark.bat” file to your home directory.To find your home directory, open up a Windows command shell and check out the directory path indicated before the command prompt (see below):



3. Configure the Batch File

The final step is to configure the batch file for your environment. Don’t worry, you should only need to do this once.

Using a plain text editor such as Notepad or (even better) Notepad++, open the WLANPiShark.bat file. (Sidenote: if you don’t already have Notepad++, get it. You can thank me later. There are so many things you can use it for.)

When you open the file, it can look a little overwhelming as there is a lot of stuff in there! Scroll down to around line 50 and you should see something that looks similar to this:



There are 6 variables that need to be configured. These are indicated by the “set” statements shown above. All that needs to be done is to edit the value shown after the “=” symbol with a value for your environment. Many of them likely won’t need changing if you have a default WLANPi setup. When making any edits, ensure that you don’t add any leading or trailing whitespace characters (yes, I got stuck for a long time trying to figure that out at one stage...)

Make sure you hit “Save” when you’ve made your edits!

Let’s take a look at each variable:
  • WLAN_PI_USER: this is the username used to login to your WLANPi via an SSH session. The default is “wlanpi”, so unless you’ve created new accounts on the WLANPi, you can leave this as-is. 
  • WLAN_PI_PWD: this is the password of the account name specified in the previous variable. Again, if you’ve left everything as default, this is also “wlanpi”. If you have changed the user account password from default, then put in the password value here. (Note: this could be a security worry for some people, but I don’t have a good workaround for this, sorry
  • WLAN_PI_IP: this is the IP address of the WLANPi itself. The IP address is shown on the display of the WLANPi. By default this will be a 169.254.x.x address unless you have previously assigned a static address to the WLANPi Ethernet adapter 
  • WIRESHARK.EXE: this is the full directory path to the Wireshark executable on your laptop - it must also include the Wireshark executable filename. Hopefully you made a note of this during installation.If not, you will need to find it using a tool such as Windows File Explorer 
  • PLINK: this is the full directory path to the Plink executable on your laptop - it must also include the Plink executable filename. Hopefully you made a note of this during the installation of Putty - it will be in the same directory as Putty. If not, you will need to find it using a tool such as Windows file Explorer 
  • WLAN_PI_IFACE: this is the name of the wireless LAN adapter interface on the WLANPi device. By default, if there is only one WLAN USB NIC attached, it will usually be “wlan0”. If you need to check this, simply SSH to your WLANPi and (with the WLAN adapter plugged in), run the command “sudo iwconfig” and inspect the output for the name of the WLAN interface: 



Testing


Assuming you have followed the instructions above, you should be good to go for a test to capture some frames over the air via your WLANPi and display them in Wireshark on your Windows laptop.

The required steps are:
  1. Open a command shell on your Windows laptop (i.e. Start > Cmd) 
  2. Type the following command at the command prompt: WLANPiShark.bat -c 1 
  3. Following a few status messages at the Windows command prompt, you should now see Wireshark open on your laptop and frames being captured on channel 1 (Note: the first time you do this, you may be prompted to accept a key at the Windows command prompt - accept this by hitting “y”. You will only prompted to do this once.
  4. When you have captured enough frames, use the usual Wireshark controls to stop your capture and perhaps save them off if you want to keep them

Here are a couple of screenshots showing typical output in the Windows command shell and the Wireshark capture window itself:





(want to know where all those crazy colours came from in the wireshark capture? See this article: http://wifinigel.blogspot.com/2014/02/wlan-packet-capture-frame-colorization.html)

Caveats & Limitations

As useful as this approach is, it has a few foibles and limitations of which you should be aware:

  • You should only use the latest WLANPi image from http://wlanpi.com. Don’t update the packages using “apt-get upgrade” as it will likely break the drivers supplied for the CF-912AC and break the capture capability.
  • Capture restrictions: 
    • Although the CF-912AC can capture 802.11ac frames, it can only capture 1 and 2 spatial stream fames. Data frames for 3 spatial stream devices will not be captured 
    • Capture is only possible for 20Mhz and 40Mhz width channels - this is a limitation of the ‘iw’ command in Linux (unless anyone has a clever work-around?) 
  • When installing Putty, remember that it is the Plink executable path you need to configure in the batch file, not Putty.exe 
  • This solution is bit clunky compared to native capture with an on-board adapter (though it is still quite powerful): 
    • It would probably be best written in another scripting language, but this adds another step of software to install to support that scripting language 
    • As ths is a Windows batch file, the CLI syntax checking is minimal. Check and double check the syntax you have used if you get strange results. It is easy to get Wireshark to fire up even though the entered CLI parameters are garbage. 
    • The batch file executes a number of remote commands on the WLANPi prior to firing up Wireshark. This means that there is a delay of a couple of seconds before Wireshark actually fires up. This could be possibly improved by adding a shell script on to the WLANPi itself, but I wanted to keep this as easy as possible to get going - hence I wrapped everything in to one file that runs on the Windows laptop 
  • Each time you need to do a capture, you have to run the batch file again - Wireshark does not run continually. You cannot just hit the stop/start button in Wireshark (sorry) 
  • In this article, I have shown how to run the capture using a direct Ethernet connection between the laptop and WLANPi. Obviously, by configuring IP addresses correctly, the laptop and WLANPi could be remote from each other. If you decide to try this approach, consider the bandwidth available between the laptop and the WLANPi and impact on other network infrastructure. Consider using the slicing option to keep the capture size down. 
  • Anything else you need is likely covered on the following GitHub page (inc full syntax and option details): https://github.com/wifinigel/WLANPiShark

References