How to: Capture traffic on your ByteBlower Port
Posted by Wouter Debie, Last modified by Craig Godbold on 05 June 2023 11:28 AM
When you are testing your device with ByteBlower, you sometimes like to have a pcap-capture of the data for debugging purpose. With the ByteBlower API we can easly capture that network traffic and present it to you as a pcap-file. This feature will help you to debug quickly the problem with your device.
Let me explain how to do this.
Using the ByteBlower GUI
This is the simplest way of capturing traffic. Available since GUI v2.11, and server v2.9. Here you can see how it works :
Options to keep the file size manageable
With the default settings all network traffic is captured from the selected interface. Often this results in very large PCAP files. Since version 2.13 of the ByteBlower GUI, two options are open to reduce filesize:
The default settings for both is capture all traffic.
These two options are available in the advanced config part of the capture dialog. They are configured before the capture starts. Did the capture already begin? The options become editable again in dialog after stopping the capture.
Using the Remote Capture Tool
This was the easiest way of capturing traffic on your port, until we brought the capture functionality to the GUI. It's a command-line tool that can be downloaded from the setup pages. It can be used on Windows, Mac and Linux.
Using the ByteBlower lower-layer API
When you are using our TCL API to transmit your traffic you can use the Rx.Capture of a ByteBlower Port to create a capture. Using our API allows you to automate when to create a capture. Let your script determine when you need to create a capture.
All you need is the Rx.Capture.Add call on your ByteBlower Port.
Just like you add a Trigger to a ByteBlower port you can add a Capture. On this capture-object you can set a capture filter and thus define which frames you would like to see captured. After that just start the capture and you are all set. Now lets put these simple words into a working script.
For this post, we assume we have created a back-to-back scenario with:
Create a capture on the dstPort and configure it
Now you have a capture Object. Using the Tk command you can visualize it to see what you can do with this object.
It is important to set a capture filter on this capture. This will allow you to capture only the packets you are interested in.
The filter must be a BPF filter. On http://biot.com/capstats/bpf.html you can find more info on the syntax of these filters and some day-to-day examples.
Start the capture
You can start the capture now.
Now start your traffic and every frame that matches your filter will be captured. You can see how many frames have been captured with the in the result capture object
Stop the capture and get the PCAP-file
Like the start-method there is a stop method the capturing.
To retrieve your pcap-file use the Pcap.Save method.
On your disk you will find DeviceX.pcap containing the packets that matched your filter that arrived on your ByteBlower destination port (destPort). If you want, you can use Frames.Get to retrieve a TCL-list containing the packets represented in hex-encoding. This way you could use TCL to parse your retrieved packets...
You can find the api documentation of the RxCapture here: https://api.byteblower.com/tcl/classRx_8Capture_8RawPacket.html
Why does my capture sometimes contain packets with invalid checksums?
When creating a packet capture (.pcap file) using the ByteBlower GUI, then it's possible that some packets will have an incorrect checksum in the capture. Wireshark typically marks those in red with the hint: "maybe caused by UDP checksum offload?".
That hint is actually correct. In some cases the ByteBlower makes use of checksum offloading. This means that the checksumming is done by the NIC hardware. Because the packets are stored in the capture before sending them to the NIC they still have the invalid checksum in the capture.
Currently checksum offloading is only used for Frame Blasting flows that have one of the following features enabled: latency, out-of-sequence, random size modifier, growing size modifier or field modifier. In all other cases the ByteBlower will perform the checksumming in software.
Remember that the actual packet sent on the network will have the correct checksum! You can verify this by capturing on the receiving interface. The incoming packets will should have a correct checksum. Unless, of course, something bad happened like packet corruption.