Skip to content

Latest commit

 

History

History
278 lines (208 loc) · 11.2 KB

README.md

File metadata and controls

278 lines (208 loc) · 11.2 KB
Raw

Japanese

Pcap4J

Logos

Slack Maven Central

Build Status CircleCI Build status codecov Code Quality: Java Total Alerts

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

Pcap4J is available on the Maven Central Repository.

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.

You can learn how to write Pcap4J programs from samples.

Learn more about Pcap4j from the following documents:

How to run samples

See the following examples:

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
    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)