jNetPcap 2.X

Stand alone libpcap wrapper module

jNetPcap 2.0 design

[MWB - 3/16/10: this is still work in progress]

This document describes the jnetpcap 2.0 design. Next major step in evolution of jnetpcap software is to make it more manageable in terms of complexity, size and efficiency. The major changes planned for jnetpcap 2.0 are as follows:

  • Break up into multiple modules: jnetpcap, jnetcommon, jnetdecoder, jnetanalyzer
  • Provide a multi-module build script
  • Provide a simple Makefile build process for native components, in addition to existing ant scripts
  • Provide additional protocol modules for specific protocol families

In addition to release structure changes the following API changes will also be implemented:

  • Move common code into more general java packages and bundled into a jnetcommon module
  • Remove java dependencies between modules except for the common module
  • Acquire new domain for more common code: jnetsoft.org [MWB: already registered]
  • Preserve most of the API syntax, but with some classes moved to other java packages in order to facilitate a clean breakup into multiple modules
  • Provide a NDK for native development - specific native functionality will be provided with specific native and java API, especially in the native to java memory boundary area

The above changes will depart from the current monolithic API of jnetpcap releases. The jNetPcap module will become a standalone java wrapper for libpcap/winpcap libraries. Additional modules will provide the decode and analyzer features that will be plugged in at runtime.

Started on 1.4.b0001

I started work on 1.4.b0001. The new branch-1.4 is based branch-1.3. Its using exact same code base, but will have few new features added and expanded platform support. Any bugs that will be discovered in 1.3, the fixes will be incorporated into 1.4 as well.

Here is what I'm working on right at the moment:

1) Adding the "lazy decode" feature.

2) Adding JPacketBufferHandler feature.

Lazy decode is when packet scan/decoding is triggered only when the packet contents are first accessed and not when the packet is created. This will delay packet decoding to a time when its actually needed. This will allow packet decoding to be delayed by the user, to be performed in other threads and not the capture thread.

The JPacketBufferHandler is a new dispatcher handler that is designed for efficiency and minimization of java overhead during capture. This new handler uses a new container object JPacketBuffer which is designed to allocate large user memory buffer to store multiple packets. The default allocation size is 1MB and allows storage of anywhere between 500 to 10,000 packets depending on the packet size. Both the pcap header and the packet contents are stored in the buffer. The native dispatcher copies incoming packets from libpcap into this buffer until its full. Only when the buffer is full is the buffer dispatched to java handler with all of the captured packets. The JPacketBuffer container provides an iterator to access packets within the buffer. This minimizes interaction with java as hundreds if not thousands of packets can be efficiently stored in the buffer before any interaction with java has to occur. After the buffer is dispatched to java, a new buffer is allocated to receive more packets.

Official release 1.3.a1 (alpha1) is released

The official release jnetpcap-1.3.a1 is released. This release freezes new feature development. Only bug and documentation fixes will be allowed on this release branch.

This is the recommended release for environments not looking for very latest features and which require code stability in production environments.

Release 1.3 contains the following features:

  1. All the libpcap wrapper API
  2. Header decoder (the quick native scanner)
  3. Existing core protocols (Ethernet, 802.3, Ip4, Tcp, Icmp, etc..)
  4. Native checksum generation and verification for various protocol CRC fields
  5. No changes to existing native memory model.
  6. Flow-key generation

5.6 - Registering a header

Once a header definition is complete you need to "register" your new header with jNetPcap's registry of protocol headers, to make the header active. The JRegistry class provides a JRegistry.register method for registering new headers. In this step, the JRegistry.register method will scan the header definition for any errors to make sure all the required components of a header definition are there.

Here is how you would register a new header definition defined in MyHeader class file.

try {
  int headerID = JRegistry.register(MyHeader.class);

  System.out.printf("Header registered successfully, its numeric ID is %d\n", headerID);

} catch (JRegistryHeaderErrors e) {

When to register

It is important to know when to register the header with JRegistry. The scanner that is assigned to process packets coming from libpcap, takes a snapshot of all the headers registered at the time, as it is assigned to its task. Therefore you have to register your new header before that happens.

It is recommended that you register your header before even pcap capture is opened. Although this is strictly not necessary, it is recommended that the registration takes place before hand.

Registering from static initializer in header definition itself

A common approach is to put registration code inside the header definition itself in a static initializer. This ensures that the header is always registered the first time the class file is loaded into java VM.

... // header definition class
static {
  try {
  } catch (RegistryHeaderErrors e) {
... // rest of header definition class
Syndicate content