Partnering with Sewio reduced our development time when creating a Wireshark dissector tool for our wireless protocol, SNAP. Their level of expertise in analyzing and capturing 802.15.4 packets accelerated our time to market, eliminated unexpected complexities and provided our team with a very valuable tool.
This tutorial describes how to compile a new dissector and how to insert it to the Wireshark software as a plugin. For more information about the dissector creation please follow How to Write Your Own Wireshark Dissector post.
There are two ways to add a new dissector:
- insert it directly to the Wireshark source code
- create a plugin.
Plugin type of the Wireshark dissector can be easily included to the Wireshark package at expense of the little degradation of execution speed. However, this is usually not big deal. Advantage lies in its simplicity. Wireshark is big piece of software and during a dissector development developer has to go through the tedious compilation process over and over. Plugin is much more flexible solution and compilation is fast. Note there is no difference between source code of standard dissector and plugin dissector.
All informations below are gained from Wireshark Developer’s Guide and from README.plugin (wireshark_src\doc).
First of all, you need to download tools and Wireshark source code. Please follow this tutorial How to Compile Wireshark. After you successfully complete all the steps, you are prepared to make the plugin.
Step 1: Prepare sources
- Create folder in Wireshark sources with short name of your dissector. Usually in folder \wireshark\plugins\. My dissector is named “lwm”, so the path is \wireshark\plugins\lwm\.
- Copy template files plugins/gryphon to your folder . Complete list is here: AUTHORS
- Now you have to change code in some of this files. Next table contains which files should be changed and how. We use demonstration example of ouw LWM dissector.
|AUTHORS||Modify this file with your information. The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
|CMakeLists.txt||Replace all occurrences of “gryphon” in those files
with your dissector short name and add your source files to the DISSECTOR_SRC variable. (Use replace command CTRL + H)Example of DISSECTOR_SRC:
|Makefile.am||Replace all occurrences of “gryphon” in those files with your dissector short name.|
|Makefile.common||Your plugins/foo/Makefile.common should only list the main source file(s),
which exports register_*() and handoff_*(), for your dissector in the
DISSECTOR_SRC variable. All other supporting source files should be
listed in the DISSECTOR_SUPPORT_SRC variable.
The header files for your dissector, if any, must be listed in the
DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
DISSECTOR_INCLUDES = \
packet-lwm.h# Dissector helpers. They’re included in the source files in this
# directory, but they’re not dissectors themselves, i.e. they’re not
# used to generate “plugin.c”.
|moduleinfo.h||File is used to set the version information for the plugin|
|moduleinfo.nmake||File is used to set the version information for building the plugin. Its contents should match that in moduleinfo.h|
Step 2: Copy Your Dissector
Now you need to add your dissector to a new folder which you have created in Step 1. In our case packet-lwm.c and packet-lwm.h.
Step3: Prepare command line
- Run command line as an Administrator.
- Create folder with name of your dissector
\wireshark\plugins\<your dissector short name>\and go to it.
- Than you need to create a little windows batch script: @echo off
echo Adding things to the path…
set PATH=%PATH%;c:\cygwin\binecho Setting up Visual Studio environment…
call “c:\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat”set WIRESHARK_TARGET_PLATFORM=win32
title Command Prompt (VC 2010)
- line call c:\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat depends on the compiler version and its exact location of vcvarsall.bat.For more information follow this link
- line with set WIRESHARK_TARGET_PLATFORM=win32 execute 32-bit binaries for target platform. For 64-bit binaries use set WIRESHARK_TARGET_PLATFORM=win64. Here is table for some cases of operation system and target platform:
Your processor architecture Target architecture Value of WIRESHARK_TARGET_PLATFORM vcvarsall.bat argument x86, x64 x86 win32 ”x86? (default) x86, x64 x64 win64 ”x86_amd64? x64 x64 win64 ”amd64?
- example of code for 32-bit operation system and for 64-bit target platform: set WIRESHARK_TARGET_PLATFORM=win64
call “c:\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat” x86_amd64
- now we have the script ready, let’s run this script.
Step 4: Build plugin
- Create new script file. Name him for example “run_script.bat” and save with this content: nmake -f Makefile.nmake distclean
nmake -f Makefile.nmake
- run script.
If your compiler return error message, you should try disclean files with nmake -f Makefile.nmake distclean or look at the Troubleshooting section at the bottom of this article.
(not tested!) If you want your plugin to be included in Wireshark package you have to add your dissector’s short name to PLUGIN_LIST in wireshark/plugins/ to file Makefile.nmake.
Step 5: Plugin installation
- Find dll file in your plugin folder.
- Copy dll file to your Wireshark directory
- If you have not installed, go to www.wireshark.org and download/install Wireshark.
- Run Wireshark and your dissector should be prepared to use. If Wireshark returns error message during the start, you probably compiled your plugin for other target platform.
- Sometimes you may observed, that your plugin does not operate and no error message appears. There is probably some other dissector present and it decodes the same data.
- Try to check the plugin Wireshark menu -> Analyze -> Enabled Protocols, select your plugin then Wireshark menu -> Analyze -> Decode As and select your plugin.
In many cases just command nmake -f Makefile.nmake distclean might fix the problem.