[English](https://github.com/kaitoy/pcap4j)
[ロゴ](https://github.com/kaitoy/pcap4j/blob/master/www/logos.md)
[](https://pcap4j-slackin.herokuapp.com/)
[](https://maven-badges.herokuapp.com/maven-central/org.pcap4j/pcap4j-distribution)
[](https://travis-ci.org/kaitoy/pcap4j)
[](https://circleci.com/gh/kaitoy/pcap4j/tree/master)
[](https://ci.appveyor.com/project/kaitoy/pcap4j/branch/master)
[](https://codecov.io/gh/kaitoy/pcap4j)
[](https://lgtm.com/projects/g/kaitoy/pcap4j/context:java)
[](https://lgtm.com/projects/g/kaitoy/pcap4j/alerts)
Pcap4J 2.x and newer
====================
パケットをキャプチャ・作成・送信するためのJavaライブラリ。
ネイティブのパケットキャプチャライブラリである[libpcap](http://www.tcpdump.org/)、
[Npcap](https://github.com/nmap/npcap)、または[WinPcap](http://www.winpcap.org/)を[JNA](https://github.com/twall/jna)を
使ってラッピングして、JavaらしいAPIに仕上げたもの。
目次
----
* [ダウンロード](#ダウンロード)
* [機能](#機能)
* [使い方](#使い方)
* [システム要件](#システム要件)
* [ライブラリ等の依存](#ライブラリ等の依存)
* [プラットフォーム](#プラットフォーム)
* [その他](#その他)
* [ドキュメント](#ドキュメント)
* [サンプル実行方法](#サンプル実行方法)
* [プロジェクトへPcap4Jを追加する方法](#プロジェクトへpcap4jを追加する方法)
* [ネイティブライブラリのロードについて](#ネイティブライブラリのロードについて)
* [WinPcapかNpcapか](#WinPcapかNpcapか)
* [Docker](#docker)
* [ビルド](#ビルド)
* [コードに貢献](#コードに貢献)
* [ライセンス](#ライセンス)
* [コンタクト](#コンタクト)
ダウンロード
------------
Maven Central Repositoryからダウンロードできる。
* Pcap4J 2.0.0-alpha.6
* [pcap4j-2.0.0-alpha.6-distribution.zip](http://search.maven.org/remotecontent?filepath=org/pcap4j/pcap4j/2.0.0-alpha.6/pcap4j-2.0.0-alpha.6-distribution.zip)
* スナップショットビルド
* https://oss.sonatype.org/content/repositories/snapshots/org/pcap4j/pcap4j/
機能
----
* ネットワークインターフェースからパケットをキャプチャし、Javaのオブジェクトに変換する。
* パケットオブジェクトにアクセスしてパケットのフィールドを取得できる。
* 手動でパケットオブジェクトを組み立てることもできる。
* パケットオブジェクトを現実のパケットに変換してネットワークに送信できる。
* 以下のプロトコルに対応。
* Ethernet、Linux SLL、raw IP、PPP (RFC1661、RFC1662)、BSD (Mac OS X) loopback encapsulation、Radiotap
* IEEE 802.11
* Probe Request
* LLC、SNAP
* IEEE802.1Q
* ARP
* IPv4 (RFC791、RFC1349)、IPv6 (RFC2460)
* ICMPv4 (RFC792)、ICMPv6 (RFC4443、RFC4861、RFC6275)
* TCP (RFC793、RFC2018、draft-ietf-tcpm-1323bis-21)、UDP、SCTP (共通ヘッダのみ)
* GTPv1 (GTP-UとGTP-Cのヘッダのみ)
* DNS (RFC1035、RFC3596、RFC6844)
* 各ビルトインパケットクラスはシリアライズに対応。スレッドセーフ(実質的に不変)。
* ライブラリをいじらずに、対応プロトコルをユーザが追加できる。
* pcapのダンプファイル(Wiresharkのcapture fileなど)の読み込み、書き込み。
* [Semantic Versioning 2.0.0](https://semver.org/lang/ja/)準拠。
使い方
------
#### システム要件 ####
##### ライブラリ等の依存 #####
JRE 8以降で動く。
UNIX系ならlibpcap 1.0.0以降、WindowsならNpcapかWinPcap (多分)3.0以降がインストールされている必要がある。
JNA 5以降、slf4j-api(と適当なロガー実装モジュール)もクラスパスに含める必要がある。
動作確認に使っているバージョンは以下。
* 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
##### プラットフォーム #####
x86かx64プロセッサ上の以下のOSで動作することを確認した。
* Windows: XP, Vista, 7, [10](http://tbd.kaitoy.xyz/2016/01/12/pcap4j-with-four-native-libraries-on-windows10/), 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
他のアーキテクチャ/OSでも、JNAとlibpcapがサポートしていれば動く、と願う。
##### その他 #####
Pcap4Jは管理者権限で実行する必要がある。
ただし、Linuxの場合、javaコマンドにケーパビリティ`CAP_NET_RAW`と`CAP_NET_ADMIN`を与えれば、非rootユーザでも実行できる。
ケーパビリティを付与するには次のコマンドを実行する: `setcap cap_net_raw,cap_net_admin=eip /path/to/java`
#### ドキュメント ####
最新のJavaDocは[こちら](http://www.javadoc.io/doc/org.pcap4j/pcap4j/2.0.0-alpha.6)。
各バージョンのJavaDocは[Maven Central Repository](http://search.maven.org/#search|ga|1|g%3A%22org.pcap4j%22)からダウンロードできる。
Pcap4Jのモジュール構成については[こちら](https://github.com/kaitoy/pcap4j/blob/master/www/pcap4j_modules.md)。
Pcap4Jはpcapネイティブライブラリのラッパーなので、以下のドキュメントを読むとPcap4Jの使い方がわかる。
* [Programming with pcap](http://www.tcpdump.org/pcap.html)
* [WinPcap Manuals](http://www.winpcap.org/docs/default.htm)
* [pcap API と Pcap4J API の対応](https://github.com/kaitoy/pcap4j/blob/master/www/api_mappings.md)
Pcap4Jプログラムの書き方は[サンプル](https://github.com/kaitoy/pcap4j/tree/master/pcap4j-sample/src/main/java/org/pcap4j/sample)を見ると理解しやすい。
さらにPcap4Jを理解するには以下のドキュメントを参照。
* [Learn about packet class](https://github.com/kaitoy/pcap4j/blob/master/www/Packet.md)
* [Learn about Packet Factory](https://github.com/kaitoy/pcap4j/blob/master/www/PacketFactory.md)
* [サポートプロトコル追加方法](https://github.com/kaitoy/pcap4j/blob/master/www/HowToAddProtocolSupport.md)
* [kaitoy's blog](http://tbd.kaitoy.xyz/tags/pcap4j/)
#### サンプル実行方法 ####
以下の例を参照。
* [org.pcap4j.sample.Loop](https://github.com/kaitoy/pcap4j/blob/master/www/sample_Loop_ja.md)
* [org.pcap4j.sample.SendArpRequest](https://github.com/kaitoy/pcap4j/blob/master/www/sample_SendArpRequest_ja.md)
Eclipse上でpcap4j-sampleにあるサンプルを実行する場合、
その実行構成のクラスパスタブのユーザー・エントリーの最初に、
pcap4j-packetfactory-staticプロジェクトかpcap4j-packetfactory-propertiesbasedプロジェクトを追加する必要がある。
#### プロジェクトへPcap4Jを追加する方法 ####
* Gradle
build.gradleに以下のような記述を追加する。
```
dependencies {
compile 'org.pcap4j:pcap4j-core:2.0.0-alpha.6'
compile 'org.pcap4j:pcap4j-packetfactory-static:2.0.0-alpha.6'
}
```
* Maven
pom.xmlに以下のような記述を追加する。
```xml
...
org.pcap4j
pcap4j-core
2.0.0-alpha.6
org.pcap4j
pcap4j-packetfactory-static
2.0.0-alpha.6
...
...
```
#### ネイティブライブラリのロードについて ####
デフォルトでは下記の条件でネイティブライブラリを検索し、ロードする。
* Windows
* サーチパス: 環境変数`PATH`に含まれるパス等([MSDN](https://msdn.microsoft.com/ja-jp/library/7d83bc18.aspx)参照。)と`%SystemRoot%\System32\Npcap`。
* ファイル名: wpcap.dllとPacket.dll
* Linux/UNIX
* サーチパス: OSに設定された共有ライブラリのサーチパス。例えば環境変数`LD_LIBRARY_PATH`に含まれるパス。
* ファイル名: libpcap.so
* Mac OS X
* サーチパス: OSに設定された共有ライブラリのサーチパス。例えば環境変数`DYLD_LIBRARY_PATH`に含まれるパス。
* ファイル名: libpcap.dylib
カスタマイズのために、以下のJavaのシステムプロパティが使える。
* jna.library.path: サーチパスを指定する。
* org.pcap4j.core.pcapLibName: pcapライブラリ(wpcap.dllかlibpcap.soかlibpcap.dylib)へのフルパスを指定する。
* (Windowsのみ) org.pcap4j.core.packetLibName: packetライブラリ(Packet.dll)へのフルパスを指定する。
##### WinPcapかNpcapか #####
Windowsのネイティブpcapライブラリの選択肢にはWinPcapとNpcapがある。
WinPcapは2013/3/8に4.1.3(libpcap 1.0.0ベース)をリリースして以来開発が止まっているのに対して、
Npcapは現在も開発が続いているので、より新しい機能を使いたい場合などにはNpcapを選ぶといい。
デフォルトでは、WinPcapは`%SystemRoot%\System32\`にインストールされ、Npcapは`%SystemRoot%\System32\Npcap\`にインストールされる。
両方インストールしている環境で、明示的にNpcapを使用したい場合、`org.pcap4j.core.pcapLibName`に`%SystemRoot%\System32\Npcap\wpcap.dll`を指定して、`org.pcap4j.core.packetLibName`に`%SystemRoot%\System32\Npcap\Packet.dll`を指定する。
### Docker ###
[](https://microbadger.com/images/kaitoy/pcap4j)
CentOSのPcap4J実行環境を構築したDockerイメージが[Docker Hub](https://registry.hub.docker.com/u/kaitoy/pcap4j/)にある。
`docker pull kaitoy/pcap4j`でダウンロードし、`docker run kaitoy/pcap4j:latest`でコンテナのeth0のパケットキャプチャーを実行できる。
このイメージはGitレポジトリにコミットがあるたびにビルドされる。
ビルド
------
1. WinPcap/Npcap/libpcapインストール:
WindowsであればNpcapかWinPcap、Linux/Unixであればlibpcapをインストールする。
ビルド時に実行されるunit testで必要なので。
2. JDK インストール:
JDKの9か10か11か12をダウンロードしてインストール。JAVA_HOMEを設定する。
3. Gitをインストール:
[Git](http://git-scm.com/downloads)をダウンロードしてインストールする。
Gitのインストールはビルドに必須ではないので、このステップはスキップしてもよい。
4. Pcap4Jのレポジトリのダウンロード:
Gitをインストールした場合は`git clone git@github.com:kaitoy/pcap4j.git` を実行する。
インストールしていない場合は、[zip](https://github.com/kaitoy/pcap4j/zipball/master)でダウンロードして展開する。
5. ビルド:
プロジェクトのルートディレクトリに`cd`して、`gradlew build` を実行する。
unit testを通すためにはAdministrator/root権限が必要。
コードに貢献
------------
1. このリポジトリをフォークする。
2. v1ブランチからブランチを作る。
3. コードを書く。
* プロトコルサポートを追加するときは[このPR](https://github.com/kaitoy/pcap4j/pull/70)を参照。
* このプロジェクトは[Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)に従う。「`gradlew spotlessApply`」を実行するとフォーマットできる。
4. そのブランチからPRを送る。
ライセンス
----------
[LICENSE](/LICENSE)
コンタクト
----------
Kaito Yamada (kaitoy@pcap4j.org)