CaptureExample.java Documentation

Overview

The CaptureExample.java program demonstrates how to capture network packets to a PCAP file using the jNetWorks SDK. The jNetWorks SDK is compatible with PCAP, Napatech SmartNIC, and Intel's DPDK drivers and hardware, enabling high-performance network capture and processing. This program captures packets, writes them to a PCAP file (capture.pcap), and applies filtering and configuration options to control the capture process.

This documentation provides a detailed explanation of the program flow, the purpose of each step, and how the jNetWorks SDK simplifies packet capture while supporting advanced network hardware.

Prerequisites

• jNetWorks SDK: The program requires the jNetWorks SDK, which provides libraries for network capture and packet processing.
• Network Interface: A compatible network interface, such as a Napatech SmartNIC or Intel DPDK-supported hardware, must be available and configured.
• Host Buffers: The system must have sufficient receive (RX) host buffers configured to support high-speed capture.
• Java Environment: A Java runtime environment compatible with the jNetWorks SDK.
• Write Permissions: The program requires write permissions to create and write to the output PCAP file (capture.pcap).

Program Flow and Detailed Explanation

The CaptureExample.java program follows a structured flow to initialize the capture environment, configure the capture settings, capture packets, and write them to a PCAP file. Below is a step-by-step breakdown of the program.

1. Initialize the jNetWorks SDK

try (NetWorks networks = new PcapWorks()) {

• Purpose: Initializes the jNetWorks SDK, preparing the library for network operations.
• Code Details: The PcapWorks class (implementing NetWorks) is instantiated within a try-with-resources block, ensuring proper resource cleanup when the program exits.
• Functionality: This step sets up the SDK to interact with compatible hardware (e.g., Napatech SmartNIC or Intel DPDK-supported devices) and prepares the environment for packet capture.

2. Create a Receive Buffer

CaptureBuffer rxBuffer = networks.createRxBuffer(filename);

• Purpose: Allocates a receive buffer (CaptureBuffer) to store captured network packets before they are written to disk.
• Code Details: The createRxBuffer method creates a buffer associated with the output file (capture.pcap). This buffer manages packet segments during capture.
• Functionality: The buffer is optimized for high-performance capture, leveraging the capabilities of compatible hardware to handle large volumes of packet data.

3. Determine File Format and Create File Header

FileHeader fileHeader = networks.getFileFormatForExt(filename)
        .createFileHeader(); // Creates a PCAP file header

• Purpose: Identifies the file format based on the file extension (.pcap) and creates a PCAP file header, which is required at the beginning of the capture file.
• Code Details: The getFileFormatForExt method infers the PCAP format from the .pcap extension, and createFileHeader generates a FileHeader object containing metadata for the PCAP file.
• Functionality: This ensures compatibility with PCAP standards, allowing the output file to be analyzed by tools like Wireshark.

4. Open Capture and File Channel

try (NetCapture capture = networks.openCapture(rxBuffer);
        FileChannel channel = FileChannel.open(file, WRITE, CREATE)) {

• Purpose: Opens a capture session and a file channel for writing packets to the PCAP file.
• Code Details:
  • openCapture(rxBuffer) creates a NetCapture object, which manages the capture process using the allocated rxBuffer.
  • FileChannel.open(file, WRITE, CREATE) opens a file channel to write data to capture.pcap, creating the file if it does not exist.
• Functionality: The capture session leverages the SDK’s compatibility with high-performance hardware to efficiently capture packets, while the file channel ensures reliable disk I/O.

5. Configure Capture Settings

capture.assignTraffic("all")
        .portFilter(PortId.portRange(0, 64))
        .color(7)
        .descriptor(PacketDescriptorType.PCAP); // Use PCAP descriptor

• Purpose: Configures the capture session by specifying which traffic to capture and how to process it.
• Code Details:
  • assignTraffic("all"): Captures all available traffic, providing a broad capture scope.
  • portFilter(PortId.portRange(0, 64)): Filters traffic to include only packets from ports 0 to 64.
  • color(7): Assigns a color value (7) to the captured packets, potentially for prioritization or classification (specific to the jNetWorks SDK).
  • descriptor(PacketDescriptorType.PCAP): Specifies that the packet descriptor format should be compatible with PCAP, ensuring the captured data aligns with the PCAP file format.
• Functionality: These settings allow fine-grained control over packet capture, optimized for performance on compatible hardware.

6. Write the PCAP File Header

channel.write(fileHeader.asByteBuffer());

• Purpose: Writes the PCAP file header to the beginning of the capture file, initializing it for packet data.
• Code Details: The fileHeader.asByteBuffer() method converts the FileHeader object to a ByteBuffer, which is written to the file using channel.write.
• Functionality: This step ensures the PCAP file is properly formatted, maintaining compatibility with standard PCAP tools.

7. Capture and Write Packet Segments

while (rxBuffer.hasRemaining()) {
    NetSegment segment = rxBuffer.take();

    // Step 2, write captured packets, segment at a time
    channel.write(segment.asByteBuffer());

    rxBuffer.release(segment);
}

• Purpose: Captures packet segments from the receive buffer, writes them to the PCAP file, and releases the segments to free up buffer space.
• Code Details:
  • rxBuffer.hasRemaining(): Checks if there are more segments available in the receive buffer.
  • rxBuffer.take(): Retrieves the next NetSegment (a collection of packets) from the buffer.
  • segment.asByteBuffer(): Converts the segment to a ByteBuffer for writing.
  • channel.write(segment.asByteBuffer()): Writes the segment data to the PCAP file.
  • rxBuffer.release(segment): Releases the segment, freeing its memory for reuse.
• Functionality: This loop efficiently processes packet segments, leveraging the SDK’s compatibility with high-performance hardware to handle large data volumes.

8. Resource Cleanup

} // Close capture and file channel

• Purpose: Closes the capture session and file channel, releasing all associated resources.
• Code Details: The try-with-resources block automatically closes the NetCapture and FileChannel objects when the block exits.
• Functionality: This ensures proper cleanup, preventing resource leaks and maintaining system stability.

Key Features and Capabilities

The CaptureExample.java program highlights several key features of the jNetWorks SDK:

• High-Performance Capture: The SDK supports high-speed packet capture, optimized for Napatech SmartNIC and Intel DPDK-compatible hardware.
• PCAP Compatibility: The program generates standard PCAP files, ensuring compatibility with tools like Wireshark.
• Flexible Filtering: The assignTraffic and portFilter methods allow precise control over captured traffic.
• Simplified API: The Java-based, object-oriented API abstracts low-level details, making it easy to configure and manage capture sessions.
• Resource Management: Try-with-resources ensures automatic cleanup, reducing the risk of memory leaks.

Usage Notes

• Output File: The program writes packets to capture.pcap, which can be analyzed using tools like Wireshark or tcpdump.
• Port Filtering: The example filters packets from ports 0 to 64. Modify the portFilter range to capture different traffic.
• Color Attribute: The color(7) setting is specific to the jNetWorks SDK and may relate to packet prioritization. Consult the SDK documentation for details.
• Performance Considerations: Ensure sufficient host buffer memory and system resources for high-speed capture.
• Error Handling: The program uses try-with-resources and exception handling (NetException, IOException) for robust error management.

Example Output

Running the program creates a capture.pcap file containing:

1. A PCAP file header with metadata about the capture session.
2. Captured packet segments from ports 0 to 64, formatted according to the PCAP descriptor type.

The file can be opened in Wireshark to inspect packets, including timestamps, lengths, and protocol details.

Conclusion

The CaptureExample.java program showcases the jNetWorks SDK’s ability to perform high-performance packet capture with a simple, Java-based API. Compatible with PCAP, Napatech SmartNIC, and Intel DPDK drivers and hardware, the SDK enables efficient capture and processing of network traffic. The program’s clear flow—initialization, configuration, capture, and cleanup—demonstrates how to leverage the SDK’s features for real-world applications.

For more details, refer to the jNetWorks SDK documentation. To extend this example, consider adding custom filters, packet inspection, or integration with other SDK features like real-time analysis.