Wireshark Basics

Introduction:

This article is intended to give readers a strong foundational knowledge of using Wireshark to troubleshoot network-related issues with regards to Ignition. With this knowledge, the reader should be able to troubleshoot and assist Support in troubleshooting issues involving connectivity between Ignition and its various peripherals.

What is Wireshark?

Wireshark is an open-source packet sniffing program which collects, displays, and organizes network traffic. When devices communicate with each other over a network, this data is broken up into strictly structured "packets" which are then most commonly sent through the Wi-Fi or Ethernet channels that make up the network. Wireshark "sniffs" these packets by collecting all of the incoming and outgoing data on the machine that it's installed on and displaying it in a clear way for analysis by the user. This data can then be saved to a file to be shared with others. 

Wireshark is a very popular tool and is used in personal, commercial, and government enterprises. It is completely free to use and is available for MacOS, Windows, Linux, and other Operating Systems.

Use case for Wireshark

Wireshark is a tool use for granular analysis of network traffic, so it is generally used when other methods of troubleshooting fail to provide enough information, or give errors that are too vague to be able to meaningfully understand exactly what is happening.

For example, if Ignition is reporting a timeout to another device, Wireshark may be able to tell us more information about:

• if Ignition's requests are being received by the device
• if Ignition is sending requests at all
• if the device is receiving data from Ignition, but not responding

In the application context, network errors are often reduced to simple timeout or other errors, but Wireshark provides a direct view into what is happening on the network layer and often provides an explanation for errors or unexpected behavior we see in Ignition.

Because of Wireshark's microscopic level of detail, it's often most appropriate to use Wireshark after initially troubleshooting at the Ignition level. For example, it's typically not good practice to start up Wireshark to troubleshoot a connectivity issues between Ignition and a PLC without first pinging the PLC, checking error logs, and checking the physical connection between the devices first. Often times, a problem may have a simple solution that doesn't merit the usage of a specialized tool like Wireshark.

Installation

To install Wireshark, navigate to their website: https://www.wireshark.org/

1. Download

Installing is straightforward: For Windows and MacOS. Choose the version that applies to your Operating System from the stable releases:

Linux installations will vary depending on your distribution. Refer to this page for information about downloading the installer on Linux.

2. Run the installer

Run the installer. You will be given options to install other tools as well, such as T Shark. These tools are quite useful as well, but will not be covered in this article. Since they're lightweight and don't consume a lot of disk space, it may be worth leaving them in the install.

3. Npcap, WinPcap, and Libpcap

As you click through the confirmation screens, you will be prompted to install Npcap if on Windows (Network Packet Capture). Npcap is the underlying software used by Wireshark to sniff the network packets. You can think of Npcap as the software that collects the data, and of Wireshark as the software that organizes, displays, and lets the user analyze it.

You may also see mention of WinPcap and Libpcap. The basic breakdown is as follows:

• Npcap: Standard packet capturing for modern Windows
• WinPcap: Legacy version of Npcap which supports older Windows versions (Windows 8 or older)
• Libpcap: This is for Unix operating systems, including MacOS

If on Windows, try downloading Npcap first. if it doesn't work, rerun the Wireshark installer and install WinPcap instead.

4. USBPcap

The next screen in the installer offers USBPcap, which is used for capturing traffic over your device's USB ports. This is out of the scope of this article, and for our install we are electing not to install it.

5. Finishing Up

Click "Install". During the installation process, the control will transfer to the Npcap installer. If on a wireless network, it is probably a good idea to check the box "Support raw 802.11 traffic (and monitor mode) for wireless adapters".

After Npcap installs, Wireshark will finish installing and will be ready to use.

The Wireshark GUI

The Wireshark interface can be divided into 3 main spaces. The toolbar, the home page, and the capture page.

This picture shows the home page and toolbar at the top. We will describe the contents of each part in some detail, starting with the toolbar.

Toolbar

The toolbar is divided into 4 main sections as shown by the separator lines between some of the icons.

From left to right, we have

• Capture Tools
  • Start capture (Shark fin)
  • Stop capture
  • Restart the current capture - Greyed out because there was no current capture at the time of the screenshot
  • Capture options - Opens a menu for advanced capture options
• File Tools
  • Open the capture file
  • Save the capture file
  • Close the capture file
  • Reload the capture file
• Packet Tools
  • Search for a packet in the current capture
  • Go to previous packet
  • Go to next packet
  • Go to specified packet
  • Go to the first packet in the capture
  • Go to the last packet in the capture
  • Autoscroll - Automatically scroll to the last packet as more packets come in during a capture
  • Custom Coloring - Enable or disable your own custom coloring schemes for packets.
• Zoom Tools
  • Zoom in (Make text larger)
  • Zoom out (Make text smaller)
  • Reset zoom to default
  • Zoom in/out to fit contents of packets on screen

We will be using several of these options in the next section, "Capturing", so being familiar with these options is important.

Home Page

The home page is a simple page which shows your computer's network interfaces, as well as any automatically detected capture files (*.pcapng) on your machine.

• Open - A list of recently opened files on your machine.
• Capture - Settings to start a new capture
  • ...using this filter - Specify filters for your capture. See the next section on Capturing.
  • The network interface list shows all available interfaces on your machine. See "Selecting the correct NIC interface" below.
• Learn - Resources, tutorials, guides.

Capture Pane

The capture pane displays packet information for for packets from a capture file that has been opened on your computer, or the current capture process happening. 

Source: Wireshark.org

The pane is a table-like structure, which includes surface level details about each packet including: 

• Packet number - Packet 1 is the first packet captured at the start of the capture.
• Time - This starts at 0.0 and shows the time since the beginning of the capture
• Source - This is almost always an IP address, but may be a MAC address if devices are not using IP
• Destination
• Protocol - The highest level protocol that this packet is using.
• Packet length - The Size of the packet in bytes
• Packet Info - Extra details about the packet. This will vary.

Packet Details Pane

Last in this section is the packet details pane. This can be accessed from the capture pane by either double clicking on a packet in the list to open it in a new window, or by clicking "View" -> "Packet Details" in the top menu to open it as an additional pane in the same window.

Source: Wireshark.org

The packet details pane lays out data of the packet in layers by protocol. In the example above, we can see the layers of a packet containing a DNS response:

• Ethernet - This is where the MAC Addresses of devices are shown, as MAC addresses are used over ethernet communication. This is the lowest level which contains information simply about data over the wire.
• IPv4 - The internet protocol is where we see the IP addresses of the devices that are communicating
• UDP (User Datagram Protocol) - Another layer above IP which controls the manner in which data is sent.
• Domain Name System - This is where the core information of the packet is stored, within its highest level protocol. Other packets may show TCP, UDP, TLS, BACnet, Modbus, or countless other protocols as their high level protocols.

This protocol stack will look different depending on the protocols used by the devices in communication. Some familiarity with the nature of the protocols you are working with will be useful in being able to meaningfully decipher the conversation. Common protocols used by Ignition will be outlined at the end of the article.

Capturing:

The actual process of capturing data in Wireshark is simple, though there is caveat of whether or not you can actually see the raw data within the packets. If you take a packet capture of effectively any communication over the internet and try to examine the raw data within the the packet, you will see a random string of characters instead of meaningful data. This is because the data is encrypted. 

In capturing data, there are two different aspects of the communication you may be looking for.

1. The behavior of the communication itself.

In this case, you may be looking at how often devices are sending packets, what kind of packets they are, duration between exchange of data on the network, and more. In this case, encrypted packet data will usually not interfere with your observations. The packet metadata is still publicly viewable, so information about protocols, response codes, source, and destination are still visible in Wireshark. Since we don't care about the raw data being sent, it doesn't matter that it is encrypted.

2. The data being sent between devices

If you are seeing wrong data coming to or from Ignition, it may be helpful to look at the packet data itself. In this case, an unencrypted connection is required to easily view the packets. Wireshark does include functionality to allow for decryption of packet data if you have access to the private key used to encrypt the data, but within the scope of Ignition this is rarely necessary will not be included in this article.

Selecting the Correct NIC (Network Interface Card)

When Wireshark is first opened, the home page will display a list of Network Interfaces on your machine. 

You'll need to select the appropriate one in order to capture the right network traffic. Luckily, in the vast majority of Ignition systems, you'll just want to select either "Ethernet" or "Wi-Fi". Here is a breakdown of the four main ones you'll be seeing:

Ethernet

The ethernet interfaces are the ethernet cable(s) connected to your computer. For the majority of Ignition systems, you will want to select the Ethernet connection that shows any sort of traffic. In the image above, we can see that the computer has two Ethernet interfaces, but only one is in use, as indicated by the line to the right of the connection which is a graph that shows traffic volume over time. If we did selected Ethernet 2 and start a capture, we would see no packets.

Wi-Fi

This will be any traffic over your computer's Wi-Fi card. This is less common in Ignition use-cases, though it might apply to yours if not communicating over Ethernet.

Local Area Connection 

These can be ignored and are usually not in use by anything Ignition-related. For detailed information about the specific purpose of each interface, you can run the command below in Windows Powershell:

Get-NetAdapter -IncludeHidden 

On Linux:

ip link

Adapter for Loopback Traffic Capture

This is a virtual network interface exposed by Npcap. If you are on an older version of Windows and are using WinpCap, you won't see this. This adapter monitors traffic between internal process on the host machine. For example, if Ignition was running on the same server as a database, this traffic would be considered "Loopback" traffic and wouldn't be found on any external interfaces like ethernet or Wi-Fi. 

Applying a Capture Filter

The capture filter is an expression which dictates the criteria of whether a packet is included in the capture. Wireshark has its own syntax for building these expressions and offers many options to choose from as well as logic to apply to the filter. Note that applying a capture filter will cause Wireshark to completely ignore any packets that don't meet your criteria and they will not be included in the capture. 

Capture Filter Syntax

In general, a capture filter is made up of one or more primitives, which are set expressions allowed by the filter syntax. Primitives are made up of one or more qualifiers followed by zero or more identifiers.

To create a capture filter, type in the qualifiers you want, and if necessary, the IDs that further narrow the filter to create your primitive. Multiple primitives can be combined to create a more complex expression. All capture filter syntax is lexical and does not contain any symbols.

Here is a table of some of the most common qualifiers. There are three categories: type, direction , and protocol.

host 127.0.0.1

port 1433

portrange 8043-8088

ip

ether proto \ip

tcp port 8088

udp portrange 1-100

greater 1024

*Note that the capture filter ether proto \ip is equivalent to just ip. ip is a shorthand for specifying the ethernet protocol explicitly. Many qualifiers are simply built-in shorthand notation for other, more verbose filters. For example, port 8088 is short hand for udp port 8088 or tcp port 8088.

Here are a few simple examples of some capture filters that may be useful.

If Ignition's IP address is 123.45.67.8, then to see only traffic to/from Ignition specifically, we can use:

host 123.45.67.8

If Ignition is communicating with a device 123.45.67.2 over TCP on port 4096 and we only want to see traffic between Ignition and this device, we can use:

host 123.45.67.8 and host 123.45.67.2 and tcp.port eq 4096

If Ignition is communicating with two devices 123.45.67.2 and 123.45.67.3 over TCP on port 4096 and Ignition's hostname is "ignition-server123", and we want to see ignition's traffic between it and either of the devices, we can use:

host ignition-server123 and \(123.45.67.2 or 123.45.67.3 \)

Notice that the parentheses must be escaped with a backslash character: \

Lastly, we could specify traffic only over Ignition's SSL port 8060 and not over 8088. There are two ways:

port 8060 and not port 8088

or

port 8060 and not 8043

Notice that both whole expressions can be chained with "and" as well as only identifiers in a single expression. Additionally, the following is NOT valid syntax:

not 8043 and port 8060

because "not 8043" is not a valid primitive, as it does not contain any valid qualifiers.

After entering (or not entering) a capture filter, press the Shark Fin button to start capturing traffic.

Ring-Buffer (Rolling) Capture

A ring-buffer capture allow you to continuously capture data without consuming so much disk space. A ring-buffer capture can be run for long periods of time as it will not continue to create new files, and instead, it will prune the oldest files in order to keep disk usage below a set maximum. This is useful for capturing network events that may be unpredictable or occur during non-operational hours.

To configure the ring-buffer capture, click Capture -> Options from the top navigation bar to open the menu. There are three tabs for configuring the capture.

• The Input tab is effectively the same as the Capture section of the Home Page. You can choose your Network Interface and apply a capture filter.
• The Output tab contains the ring-buffer settings. You will need to
  • Enter the fully qualified path to the new file you wish to be created. 
  • Check the "Create a new file automatically" box.
  • Configure "after" to create a new file after one or more conditions are met
  • Check the box "use a ring buffer with" and specify the number of files
    • Optionally, if you do not check this box, wireshark will continue to generate new files until the capture is stopped manually.
• The Options tab contains extra options that may be useful to you. Namely, you can configure the capture to stop automatically after a certain condition is met.

Analysis:

With a capture filter set, you will see only the filtered packets being displayed on the screen. When done capturing, simply press the stop button. You now have a packet capture ready for analysis. In analyzing a packet capture, the exact process will differ depending on what you're looking for, but some general key points should be kept in mind.

Understand what you're looking for in the capture. Ensure that you have all the pieces of information you need like device IP or MAC addresses, protocols, and some working knowledge of the protocols being used between the devices.

Isolate what you're trying to find. Ensure that you utilize capture filters and/or display filters to narrow down what is shown on the screen so that key packets or behaviors are easier to find. In especially busy networks, this is especially necessary as capture files can grow very large in a very short amount of time without proper capture filters applied. 

Clearly describe what you're seeing in the capture and what you expect to see under normal circumstances. Devices might be communicating, but are they doing so in the way that you expect? 

If you applied a very granular capture filter, the packets of interest may stand out straight away, but if not, we can apply a display filter to filter out what we want. 

Applying a Display Filter

Display filters have different syntax than capture filters, and they are applied after the capture has been taken. Display filters allow you to filter data displayed on the screen temporarily, and can be removed to return all packets from the original capture to the display. Display filters are desirable when trying to isolate an issue during analysis, but without losing the packet data permanently as with a Capture Filter.

You can enter a display filter expression in the text field above the packet list. Type in the filter expression and press enter to apply the filter. To remove it, simply delete the expression and press enter again to apply.

Useful Syntax for Display Filters

Wireshark offers many ways to filter packets. A detailed list of options can be found here, but we will look at some of the main filtering mechanisms you may need to use when working with Ignition. The logical syntax may be familiar to you if you have experience with any programming languages or Ignition's Expression Language syntax. 

Comparison

eq

==

ne

!=

gt

>

le

<

ge

>=

le

<=

contains

In addition to these basic syntactical functions, Wireshark has a massive number of built-in Protocol Dissectors. Protocol Dissectors are properties extracted from the packets and exposed to the filtering system. To specify a dissector, you must use the format <protocol>.<dissector> 

Some dissectors have their own, more specific dissectors as well, specified with an additional "." after the dissector.

A master list of all dissectors can be found here. In this article, we will show some useful dissectors for some of the most common protocols you will be working with related to Ignition.

Dissectors

ip.addr == 127.0.0.1

ip.src == 127.0.0.1

ip.dst == 127.0.0.1

eth.addr == aa:bb:cc:dd

eth.len gt 20

eth.src eq aa:bb:cc:dd

eth.dst ne aa:bb:cc:dd

tcp.port == 8088

tcp.flags.syn == 1

tcp.flags.rst eq 1

tcp.segment_data contains "ignition"

udp.port == 161

udp.payload contains "Hello"

modbus.data contains "Hello"

modbus.func_code == 3

Searching packets for specific String Values

If you're looking for specific data that you know should be contained within a packet, but aren't sure if there is a filter for it, you can use Wireshark search function. Wireshark allows you to search for packets with string, hex, or regular expression search queries.

Click the Search icon in the toolbar. A search bar will appear below the Display Filter input.

1. You can choose to search in the packet details, the raw packet bytes, or the list of packets overall. For this example, "Packet List" will work just fine, and is appropriate for simple string searches in any case.
2. The second dropdown from the left allows you to choose string encodings. "Narrow & Wide" searches ASCII, UTF-8, and UTF-16. This can also be left as-is.
3. Select "Case sensitive" if it is necessary. If you aren't completely sure of the case of the values you're searching, it's better to leave this unchecked.
4. Finally, select "String" from the fourth dropdown. This dropdown allows you to search for different types of data.
5. Enter your search string into the box and click "Find". Wireshark will move your selected packet to the first packet that contains the given string. Keep clicking find to move to the next occurrence.

Packet Capturing on Headless Linux Servers:

Wireshark is a GUI tool which actually sits on top of the packet capturing technolog. That is to say, you can capture packets without the GUI tool installed. In some environments, this is necessary. This is where tshark comes in.

tshark is a command-line tool which effectively does the same thing as Wireshark. In fact, it is included in standard Wireshark installations. On Windows, this is found in

C:\Program Files\Wireshark\tshark.exe

To install tshark standalone on a headless server, simply install the package called tshark via the package manager for your machine. 

• On Windows, this means installing Chocolatey
• On MacOS, install Homebrew
• On Linux, this will vary depending on distribution.

NOTE: On some Linux distros, the package name is wireshark-cli. Refer to this page to see which one to install if you are on linux.

Capturing is the same idea as in Wireshark. There are a few command line flags that you will need to keep in mind. Firsly, ensure you know the name of your network adapter. (See Selecting the Correct NIC (Network Interface Card above for the commands to list your network interfaces on Linux and Windows).

Here are some of the most commonly used flags:

-i "Ethernet 2"

-D

-c 1000

-w path/to/file.pcap

-f "host 123.45.6.7"

Capture filter syntax is exactly the same as in Wireshark. For a full list of available flags, see this page.

Summary:

Wireshark is a powerful tool which can be used to see the finest details of network traffic. For this reason, it should be used only when necessary to see such detail. In most cases, other tools will suffice in troubleshooting - what is most important is to have a clear understand and direction for the behavior you're looking for.

Wireshark captures packet data from your specified network interface and displays it on the screen. Live data can be permanently filtered with capture filters and captured data can be temporarily filtered with display filters. These filtering tools, combined with string searches, make it fast and easy to find (or discover the absence of) the data you're looking for, allowing filtering mechanisms by protocol, port number, IP address, and much more.

For further reading on Wireshark, visit their documentation page: https://www.wireshark.org/docs/wsug_html_chunked/

Sources

1. https://wiki.wireshark.org/CaptureSetup/Loopback
2. https://gitlab.com/wireshark/wireshark/-/wikis/WinPcap
3. https://www.wireshark.org/docs/dfref/
4. https://www.tcpdump.org/manpages/pcap-filter.7.html
5. https://wiki.wireshark.org/CaptureFilters
6. https://wiki.wireshark.org/DisplayFilters
7. https://tshark.dev/setup/install/#installing-tshark-only
8. https://www.wireshark.org/docs/man-pages/tshark.html
9. https://tshark.dev/setup/install/#installing-tshark-only
10.