1. Getting Started

Network Capture Development using jNetPcap

This page walks you through setting up development using jNetPcap module for packet capture, network statistics and packet transmission using libpcap library.

Prerequisites

• Java 19 or higher with --preview-enable option (for Foreign Function feature JEP 424)
• Native libpcap library installed on your system
  • libpcap-dev on Linux systems
  • WinPcap or Npcap on Microsoft Windows systems
• Note that jNetPcap does not have any other external to JRE module dependencies. It is a stand-along module.

Installation

There several ways to install org.jnetpcap module

• add a Maven dependency to your pom.xml file

<dependency>
    <groupId>com.slytechs.jnet</groupId>
    <artifactId>jnetpcap</artifactId>
    <version>2.0.0-preview.1</version>
</dependency>

• Download the Jar file from our download page: latest release
• Clone github repo and build from source

Note: jNetPcap java software no longer comes with any custom native JNI libraries like jNetPcap V1 did. Version 2 is a pure java library, which does interface with off the shelf libpcap native library through newly introduced java RJE API called Foreign Function API part of the java.base module in standard Java distribution.

Native libpcap installation

Without going into too much detail about native libpcap installation, as that is covered under tcpdump.org and npcap.com websites, here are a few tips as they relate to maven build script and how the native libpcap is located and loaded by jNetPcap.

For Windows and Linux platforms

Nothing special needs to be done for linux and Windows platforms. The maven pom.xml defines numerous profiles to handle specific directory locations for each of those.

For MacOs/OsX platforms

Mac/OsX platforms provide two main installation methods for installation of libpcap library.

Using Homebrew (/usr/local/bin/brew)

Homebrew installation tool, installs libpcap library under the directory /usr/local/Cellar/libpcap/${VERSION}/lib. There is no default 'latest' installation directory and you must always specify a libpcap version when setting up your application or using maven unit tests. If you are setting up your application from java command line or in IDE, you just have to define the system property java.library.path to point to the directory where libpcap.dylib shared object resides. If you are trying to run the maven unit tests, you must specify the user property with maven command line -Dlibpcap.version=X.Y.Z as an example, mvn -Dlibpcap.version=1.10.3 test.

Using Mac Ports (/opt/local/bin/port)

When installing libpcap library using Mac Ports, things are a little easer since Mac Ports libpcap package gets installed in a non-versioned directly and the libpcap.dylib file found there is a soft link to the latest version under /opt/local/lib directory.

Hint! To install libpcap using Mac Ports: sudo port install libpcap

Setting up your project

In your Java project, you need to add the following requires dependency to have jNetPcap on the module-path of your project. In your module-info.java file at the root of of your project directory add:

module my.project.module {
  requires org.jnetpcap;
}

Enabling capture privilege

To enable capture privilege for Java applications to access certain priviledged functions

Linux

sudo setcap cap_net_raw,cap_net_admin=eip $JAVA_HOME/bin/java

MacOs

sudo chown $(whoami):admin /dev/bpf*

Compile and runtime java flags

In order to properly run org.jnetpcap module you need to add a couple of command line flags to your application startup and/or build system.

1. java needs to be able to find the install native libpcap library -Djava.library.path=$(absolute_path_to_libpcap)
2. For Java 19 and until later released fully incorporate Foreign Function feature, you need to add to the startup and/or build system enable --enable-preview
3. For running jUnit5 tests, the command line mvn test should suffice. If manually setting up, note that the src/test/java source directory needs to be outside the module system, as unnamed module, and jUnit5 module added to the java's classpath not module-path.

Note: that unit tests utilize multiple tags and the default maven configuration is setup to only run tests which require normal user-permission and exclude windows-api|unix-api|linux-api, which leaves only tests which can run under regular user privileges and are well supported libpcap-api tests common to all platforms. Please see javadocs for the org.jnetpcap.test package for details on available tags.

Note: the unit tests source code found in the github repo are a good source of examples on every single jNetPcap API call.