Packet Sniffing using Extcap

This guide covers how to configure extcap for Wireshark to sniff packets from a Thread network.

To use Pyspinel for packet sniffing without extcap, refer to Packet Sniffing with Pyspinel.

Set up the sniffer environment

Before you begin, complete the following steps:

This guide was verified with the Zolertia Firefly (Texas Instruments CC2538 SoC) on the following host systems:

Build and flashing instructions vary based on platform.

For instructions on building and flashing the CC2538, refer to the CC2538 example README on GitHub.

For general build instructions, refer to How to build OpenThread.

The Wireshark capture screen is displayed when Wireshark is first launched. It should list hardware interfaces connected to an OpenThread sniffer.

If this is your first time using an interface, click the Options button to the left of the interface:

OT Sniffer Wireshark Extcap Capture

Set the Channel to the desired value.
Check IEEE 802.15.4 TAP to ensure that the channel information is included in the pcap output and can be displayed in the Wireshark GUI.
Check Save parameters on capture start to ensure that these parameters are saved after the start of the capture, to avoid having to set it again the next time you use the interface (unless you need to change the channel).
Click Start.

OT Sniffer Wireshark Extcap Options

If your parameters are already saved, start sniffing by selecting the hardware interface and clicking the Wireshark icon in the top left.

Select all hardware interfaces listed in the capture screen and click the Wireshark icon on the top left.

Use these fields to identify individual sniffers when capturing from multiple interfaces:

Interface ID (frame.interface_id) — Interface Identifier used by Wireshark to identify a capture interface
Interface name (frame.interface_name) — Interface name used by Wireshark to identify a capture interface
Channel (wpan-tap.ch_num) — IEEE 802.15.4 capture channel (range: 11-26)

OT Sniffer Wireshark Extcap Packets

If you have multiple Python interpreters installed, ensure that Python 3 interpreter is used by the extcap script. Pyspinel doesn't support Python 2.
Check if the hardware is enumerated on USB and the drivers are loaded.
Check that the correct firmware (NCP or RCP) has been flashed to the hardware.
Verify that the Python script located in the extcap path is executable.
- For OS X and Linux:
  1. Verify that the execute permission is present for the extcap_ot.py file:
```
ls -l extcap_ot.py
```
  2. If the execute (x) permission is missing, modify the permissions:
```
chmod +x extcap_ot.py
```
  3. Verify the interface is listed:
```
extcap_ot.py --extcap-interfaces
```
- For Windows:
  1. Verify the interface is listed:
```
extcap_ot.bat --extcap-interfaces
```
  2. If this exits with a Python error, verify the Python version is 3.x:
```
py -3 --version
```

During Wireshark installation on Ubuntu the user will be prompted to choose one of the following options:

Create the wireshark user group and allow all members of that group to capture packets.
Only allow the root user to capture packets.

Using Wireshark as the root user is strongly discouraged. If you chose that option, change the setting:

sudo dpkg-reconfigure wireshark-common

If Wireshark was configured to restrict the capture to members of the wireshark group, you may need to add the correct user to the group:

sudo usermod -a -G wireshark user

Also add the correct user to the dialout group:

sudo usermod -a -G dialout user

Close and restart Wireshark to apply the new user group settings.

This is a known issue for some old versions of Wireshark. Make sure you are using Wireshark 3.0.6 or later.