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


Popular posts from this blog

The 5GHz “Problem” For Wi-Fi Networks: DFS

-
Image
Wi-Fi networking provides us with 2 bands for the operation of wireless LAN networks: the 2.4Ghz band and the 5GHz band. The 2.4GHz band has a reputation of being something of a “sewer” of a band, due to its limited number of usable channels, the number of Wi-Fi devices already using the band, and the high levels of non-Wi-Fi interference that it experiences. Many wireless LAN professionals will generally advise that you put your “important stuff” on the 5GHz band whenever possible. 5GHz has far more channels available, a corresponding lower number of devices per channel, and generally suffers much lower non-Wi-Fi interference. However, beneath the headline of “2.4Ghz = bad, 5Ghz = good”, there lurks a shadowy figure that can be troublesome if you’re not aware of its potential impact: DFS. Background Wi-Fi networks operate in areas of RF spectrum that require no licence to operate. This is in contrast to many other areas of the radio spectrum that generally require some form of (p...
Read more

What Are Sticky Clients?

-
Image
One term you'll often hear banded about when talking with Wi-Fi professionals is "sticky clients". I thought it might be worth spending a few moments exploring what is meant by "sticky clients", why they are generally considered to be a bad thing in Wi-Fi networks and some approaches to mitigate them. Background Many folks dealing with Wi-Fi networks often talk about the "sticky" characteristics of wireless clients when discussing client roaming within a W-iFi network. In an ideal world, we'd like to have access points providing ubiquitous coverage across our desired area providing high-quality, consistent client coverage where-ever we go. In this wonderful land of rainbows and unicorns, our clients would gracefully roam from AP to AP, detecting and associating with their closest AP throughout the coverage area to ensure their best connection speed at all times. Unfortunately, the real world doesn’t quite reflect this roaming-client...
Read more

Microsoft NPS as a RADIUS Server for WiFi Networks: SSID Filtering

-
Image
The Microsoft Network Policy Server (NPS) is often used as a  RADIUS server for WiFi networks. It can provide authentication and authorization services for devices and users on a wireless network in a Windows Active Directory environment. In this article we look at how we can use NPS to provide authentication for WiFi users across a number of SSIDs. We have previously discussed how to authenticate groups of users using the same SSID and then assign them to a VLAN that is appropriate to their security authorization. However, there may still be instances where two or more SSIDs are in-use on a wireless network and we would like to base policy decisions on the SSID that the authentication request is being generated from. As an example, if we consider a school, perhaps we would like students to only be able to authenticate if they connected to the SSID: "Student_Net". Similarly,  staff should only be able to connect using the SSID: "Staff_Net". This would ...
Read more