Skip to content
This repository

A Java library for capturing, crafting, and sending packets.

branch: master
README.md

Japanese

Pcap4J

Pcap4J

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

Download

Pcap4J is now available on the Maven Central Repository.

Pcap4J 0.9.13 (last version distributed from this page)

Pcap4J 1.1.0 (latest version on Maven Central Repository)

Why Pcap4J was born

I have been developing an SNMP network simulator(SNeO, available at the link below) by Java, which needed to capture packets and I found the pcap was useful for it. Although there are some implementations of the pcap such as libpcap(for UNIX) and WinPcap(for Windows), because they are both native libraries, a Java wrapper library was necessary in order to use them for SNeO. I researched it and found three Java wrapper libraries for pcap: jpcap, jNetPcap, and Jpcap. But both jpcap and jNetPcap were unsuitable for SNeO because they seemed to be designed for mainly capturing packets and not to be useful for making and sending packets so much. On the other hand, Jpcap looked useful for making and sending packets. But it had a defect in capturing ICMP packets and its development seemed to be stopped long ago. That's why I started developing 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, IEEE802.1Q, ARP, IPv4(RFC791 and RFC1349), IPv6(RFC2460), ICMPv4(RFC792), ICMPv6(RFC4443, RFC4861), TCP(RFC793), and UDP.
  • 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).

Supported Operating Systems

I tested Pcap4j on the following OSes with x86 processors.

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

And tomute tested Pcap4j on Mac OS X. The report is here. Thank you, tomute!

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

How to use

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

And the following resources will help you to learn how to use Pcap4j.

Pcap4j needs J2SE 5.0+, libpcap 0.9.3+ or WinPcap 3.0+, jna, slf4j-api, and an implementation of logger for slf4j. I'm using the following libraries for the test.

  • libpcap 1.1.1
  • WinPcap 4.1.2
  • jna 3.5.2
  • slf4j-api 1.6.4
  • logback-core 1.0.1
  • logback-classic 1.0.1

Run Pcap4J with administrator/root privileges.

About pcap library loading

By default, Pcap4j loads the pcap library on the following conditions:

  • Windows
    • search path: The paths in the PATH environment variable.
    • file name: wpcap.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: Specify the search path
  • org.pcap4j.core.pcapLibName: Specify the full path of the pcap library

How to use in a Maven project

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>1.1.0</version>
      </dependency>
      <dependency>
        <groupId>org.pcap4j</groupId>
        <artifactId>pcap4j-packetfactory-static</artifactId>
        <version>1.1.0</version>
      </dependency>
         ...
    </dependencies>
    ...
  </project>

Examples

How to build

I'm developing Pcap4j in the following environment.

The build procedure using Eclipse is the following:

  1. Install WinPcap/libpcap
    The pcap library is needed for the unit tests ran in the Build step.
  2. Setup Eclipse 3.7+
    Install JDK, download a compressed Eclipse file from the Eclipse Downloads Page, and decompress it.
  3. Install M2E
    Launch the Eclipse and select Help > Install New Software to open the "Install" wizard. Paste the Update Site URL(http://download.eclipse.org/technology/m2e/releases) into the field named "Work with:" and press Enter. Click and check the box of "Maven Integration for Eclipse". Click Next or Finish until beginning of the installation process. Once the installation process is finished, restart the Eclipse.
  4. Install Git
    Download Git and install it. This step is optional, you can skip this step.
  5. Clone the Pcap4J repository
    Execute the following command: git clone git@github.com:kaitoy/pcap4j.git
    If you skipped the step 3, download the repository as a zip ball and extract it.
  6. Import the Eclipse project
    In the Eclipse, select [File] > [Import] to open the "Import" wizard. Select [General] > [Existing Projects into Workspace] and follow the wizard to import the all projects in the Pcap4J repository.
  7. Build
    Right-click the parent project in the Project Explorer of Eclipse and select [Run as] > [Maven install]. Note administrator/root privileges are needed for the unit tests.

For your information, M2E was formerly called m2eclipse. If you want to build Pcap4j with m2eclipse, skip the step 2 and import the maven project instead of the eclipse project in the step 4.

The build procedure using Maven command line is the following:

  1. Install WinPcap/libpcap
    The pcap library is needed for the unit tests ran in the Build step.
  2. Install JDK1.5+
    Set the environment variable JAVA_HOME properly.
  3. Install Maven
    The newer the better. Add the path of the Maven bin directory to the environment variable PATH.
  4. Install Git
    Download Git and install it. This step is optional, you can skip this step.
  5. Clone the Pcap4J repository
    Execute the following command: git clone git@github.com:kaitoy/pcap4j.git
    If you skipped the step 3, download the repository as a zip ball and extract it.
  6. Build
    Open a command prompt, cd to the project root directory(i.e. the same directory as the pom.xml in the directory created in the step 4), and execute mvn install. Note administrator/root privileges are needed for the unit tests.

License

Pcap4J is distributed under the MIT license.

Copyright (c) 2011-2013 Kaito Yamada
All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Extra

An SNMP Network Simulator using Pcap4J; SNeO is also hosted on Github: https://github.com/kaitoy/sneo

Something went wrong with that request. Please try again.