Awesome

Japanese

Logos

Pcap4J 2.x and newer

Pcap4J is a Java library for capturing, crafting and sending packets. Pcap4J wraps a native packet capture library (libpcap, Npcap, or WinPcap) via JNA and provides you Java-Oriented APIs.

Contents

• Download
• Features
• How to use
  • System requirements
    • Dependencies
    • Platforms
    • Others
  • Documents
  • How to run samples
  • How to add Pcap4J to your project
  • About native library loading
    • WinPcap or Npcap
  • Docker
• How to build
• Contributing Code
• License
• Contacts

Download

Pcap4J is available on the Maven Central Repository.

• Pcap4J 2.0.0-alpha.6
  • pcap4j-2.0.0-alpha.6-distribution.zip
• Snapshot builds
  • https://oss.sonatype.org/content/repositories/snapshots/org/pcap4j/pcap4j/

Features

• Capturing packets via a network interface and converting them into Java objects. You can get/set each field of a packet header via the Java object converted from the packet. You can also craft a packet object from scratch.
• Sending packet objects to a real network.
• Supported protocols:
  • Ethernet, Linux SLL, raw IP, PPP (RFC1661, RFC1662), BSD (Mac OS X) loopback encapsulation, and Radiotap
  • IEEE 802.11
    • Probe Request
  • LLC and SNAP
  • IEEE802.1Q
  • ARP
  • IPv4 (RFC791 and RFC1349) and IPv6 (RFC2460)
  • ICMPv4 (RFC792) and ICMPv6 (RFC4443, RFC4861, and RFC6275)
  • TCP (RFC793, RFC2018, and draft-ietf-tcpm-1323bis-21), UDP, and SCTP (only common header)
  • GTPv1 (only GTP-U and GTP-C header)
  • DNS (RFC1035, RFC3596, and RFC6844)
• All built-in packet classes are serializable and thread-safe (practically immutable).
• You can add a protocol support without modifying Pcap4J library itself.
• Dumping and reading pcap-formatted files (e.g. a capture file of Wireshark).
• Semantic Versioning 2.0.0

How to use

System requirements

Dependencies

Pcap4j needs JRE 8+. And also a pcap native library (libpcap 1.0.0+, Npcap or WinPcap 3.0+), JNA 5+, slf4j-api, and an implementation of logger for slf4j are required. I'm using the following libraries for the test.

• libpcap 1.1.1
• WinPcap 4.1.2
• JNA 5.1.0
• slf4j-api 1.7.25
• logback-core 1.0.0
• logback-classic 1.0.0

Platforms

I tested Pcap4j on the following OSes with x86 or x64 processors.

• Windows: XP, Vista, 7, 10, 2003 R2, 2008, 2008 R2, and 2012
• OS X
• Linux
  • RHEL: 5, 6, and 7
  • CentOS: 5, 6, and 7
  • Ubuntu: 13
• UNIX
  • Solaris: 10
  • FreeBSD: 10

Hopefully Pcap4j can run on the other OSes supported by both JNA and libpcap.

Others

Pcap4J needs administrator/root privileges. Or, if on Linux, you can run Pcap4J with a non-root user by granting capabilities CAP_NET_RAW and CAP_NET_ADMIN to your java command by the following command: setcap cap_net_raw,cap_net_admin=eip /path/to/java

Documents

The latest JavaDoc is here. Each version's JavaDoc is on the Maven Central Repository.

Refer to here for information about Pcap4J modules.

Because Pcap4J is a wrapper of a pcap native library, the following documents help you to understand how to use Pcap4J.

• Programming with pcap
• WinPcap Manuals
• Mapping between pcap API and Pcap4J API

You can learn how to write Pcap4J programs from samples.

Learn more about Pcap4j from the following documents:

• Learn about packet class
• Learn about Packet Factory
• How to add protocol support
• kaitoy's blog

How to run samples

See the following examples:

• org.pcap4j.sample.Loop
• org.pcap4j.sample.SendArpRequest

If you want to run a sample in pcap4j-sample on Eclipse, add pcap4j-packetfactory-static or pcap4j-packetfactory-propertiesbased project to the top of User Entries in Classpath tab of the Run Configuration for the sample.

How to add Pcap4J to your project

• Gradle

  Add a dependency to the build.gradle as like below:

  dependencies {
    compile 'org.pcap4j:pcap4j-core:2.0.0-alpha.6'
    compile 'org.pcap4j:pcap4j-packetfactory-static:2.0.0-alpha.6'
  }
  

• Maven

  Add a dependency to the pom.xml as like below:

  <project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                        http://maven.apache.org/xsd/maven-4.0.0.xsd">
    ...
    <dependencies>
      <dependency>
        <groupId>org.pcap4j</groupId>
        <artifactId>pcap4j-core</artifactId>
        <version>2.0.0-alpha.6</version>
      </dependency>
      <dependency>
        <groupId>org.pcap4j</groupId>
        <artifactId>pcap4j-packetfactory-static</artifactId>
        <version>2.0.0-alpha.6</version>
      </dependency>
         ...
    </dependencies>
    ...
  </project>
  

About native library loading

By default, Pcap4j loads the native libraries on the following conditions:

• Windows
  • search path: The paths in the PATH environment variable, etc. (See MSDN for the details.), and %SystemRoot%\System32\Npcap.
  • file name: wpcap.dll and Packet.dll
• Linux/UNIX
  • search path: The search paths of shared libraries configured on the OS. (e.g. The paths in the LD_LIBRARY_PATH environment variable)
  • file name: libpcap.so
• Mac OS X
  • search path: The search paths of shared libraries configured on the OS. (e.g. The paths in the DYLD_LIBRARY_PATH environment variable)
  • file name: libpcap.dylib

You can use the following Java system properties to change the default behavior.

• jna.library.path: The search path
• org.pcap4j.core.pcapLibName: The full path of the pcap library (wpcap.dll, libpcap.so, or libpcap.dylib)
• (Windows only) org.pcap4j.core.packetLibName: The full path of the packet library (Packet.dll)

WinPcap or Npcap

There are two native pcap libraries for Windows; WinPcap and Npcap.

The development of WinPcap has stopped since version 4.1.3 (libpcap 1.0.0 base) was released on 3/8/2013, while Npcap is still being developed. So, you should pick Npcap if you want to use new features or so.

By default, WinPcap is installed in %SystemRoot%\System32\, and Npcap is installed in %SystemRoot%\System32\Npcap\.

If you have both WinPcap and Npcap installed and want to use Npcap, you can explicitly specify it by setting org.pcap4j.core.pcapLibName to %SystemRoot%\System32\Npcap\wpcap.dll and org.pcap4j.core.packetLibName to %SystemRoot%\System32\Npcap\Packet.dll.

Docker

A Docker image for Pcap4J on CentOS is available at Docker Hub.

Download it by docker pull kaitoy/pcap4j and execute docker run kaitoy/pcap4j:latest to start capturing packets from eth0 on the container.

This image is built everytime a commit is made on the Git repositry.

How to build

1. Install libpcap, WinPcap, or Npcap:

   Install Npcap or WinPcap (if Windows), or libpcap (if Linux/UNIX). It's needed for the unit tests which are run during a build.

2. Install JDK:

   Download and install JDK 9, 10, 11, or 12, and set the environment variable JAVA_HOME properly.

3. Install Git:

   Download Git and install it. This step is optional.

4. Clone the Pcap4J repository:

   If you installed Git, execute the following command: git clone git@github.com:kaitoy/pcap4j.git<br> Otherwise, download the repository as a zip ball and extract it.

5. Build:

   Open a command prompt/a terminal, cd to the project root directory, and execute gradlew build. Note Administrator/root privileges are needed for the unit tests.

Contributing Code

1. Fork this repository.

2. Create a branch from v1 branch.

3. Write code.

   • Please refer to This PR as an example when adding protocol support.
   • This project follows Google Java Style Guide. Execute the following command to format your code: gradlew spotlessApply

4. Send a PR from the branch.

License

LICENSE

Contacts

Kaito Yamada (kaitoy@pcap4j.org)