Skip to content

Latest commit

 

History

History
311 lines (247 loc) · 17.1 KB

README_ja.md

File metadata and controls

311 lines (247 loc) · 17.1 KB
Raw

English

Pcap4J

ロゴ

Slack Maven Central

Build Status Build status Coverage Status

Pcap4J

パケットをキャプチャ・作成・送信するためのJavaライブラリ。 ネイティブのパケットキャプチャライブラリであるlibpcap またはWinPcapをJNAを 使ってラッピングして、JavaらしいAPIに仕上げたもの。

目次

ダウンロード

Maven Central Repositoryからダウンロードできる。

開発経緯

SNMPネットワークシミュレータをJavaで作っていて、ICMPをいじるためにパケットキャプチャをしたくなったが、 Raw Socketやデータリンクアクセスを使って自力でやるのは大変そうなので pcapを使うことに。

pcapの実装は、UNIX系にはlibpcap、WindowsにはWinPcapがあるが、いずれもネイティブライブラリ。 これらのJavaラッパはjpcapやjNetPcapが既にあるが、 これらはパケットキャプチャに特化していて、パケット作成・送信がしにくいような気がした。

Jpcapはパケット作成・送信もやりやすいけど、 ICMPのキャプチャ周りにバグがあって使えなかった。結構前から開発が止まっているようだし。 ということで自作した。

機能

  • ネットワークインターフェースからパケットをキャプチャし、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)
    • TCP (RFC793、RFC2018、draft-ietf-tcpm-1323bis-21)、UDP、SCTP (共通ヘッダのみ)
    • GTPv1 (GTP-UとGTP-Cのヘッダのみ)
  • 各ビルトインパケットクラスはシリアライズに対応。スレッドセーフ(実質的に不変)。
  • ライブラリをいじらずに、対応プロトコルをユーザが追加できる。
  • pcapのダンプファイル(Wiresharkのcapture fileなど)の読み込み、書き込み。

使い方

システム要件

ライブラリ等の依存

1.1.0以前のはJ2SE 5.0以降で動く。1.2.0以降のはJ2SE 6.0以降で動く。 UNIX系ならlibpcap 1.0.0以降、WindowsならWinPcap (多分)3.0以降がインストールされている必要がある。 jna、slf4j-api(と適当なロガー実装モジュール)もクラスパスに含める必要がある。

動作確認に使っているバージョンは以下。

  • libpcap 1.1.1
  • WinPcap 4.1.2
  • jna 4.1.0
  • slf4j-api 1.7.12
  • logback-core 1.0.0
  • logback-classic 1.0.0
プラットフォーム

x86かx64プロセッサ上の以下のOSで動作することを確認した。

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

また、tomuteさんからMac OS Xで動いたとの報告が。ありがとうございます。

他のアーキテクチャ/OSでも、JNAとlibpcapがサポートしていれば動く、と願う(FreeBSDはだめそう)。

その他

Pcap4Jは管理者権限で実行する必要がある。 ただし、Linuxの場合、javaコマンドにケーパビリティCAP_NET_RAWとCAP_NET_ADMINを与えれば、非rootユーザでも実行できる。 ケーパビリティを付与するには次のコマンドを実行する: setcap cap_net_raw,cap_net_admin=eip /path/to/java

ドキュメント

最新のJavaDocはこちら。 各バージョンのJavaDocはMaven Central Repositoryからダウンロードできる。

Pcap4Jのモジュール構成についてはこちら。

Pcap4Jはlibpcap/WinPcapのラッパーなので、以下のドキュメントを読むとPcap4Jの使い方がわかる。

Pcap4Jプログラムの書き方はサンプルを見ると理解しやすい。

さらにPcap4Jを理解するには以下のドキュメントを参照。

サンプル実行方法

以下の例を参照。

Eclipse上でpcap4j-sampleにあるサンプルを実行する場合、 その実行構成のクラスパスタブのユーザー・エントリーの最初に、 pcap4j-packetfactory-staticプロジェクトかpcap4j-packetfactory-propertiesbasedプロジェクトを追加する必要がある。

Mavenプロジェクトでの使用方法

pom.xmlに以下のような記述を追加する。

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

ネイティブライブラリのロードについて

デフォルトでは下記の条件でネイティブライブラリを検索し、ロードする。

  • Windows
    • サーチパス: 環境変数PATHに含まれるパス。
    • ファイル名: 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)へのフルパスを指定する。

Docker

CentOSのPcap4J実行環境を構築したDockerイメージがDocker Hubにある。

docker pull kaitoy/pcap4jでダウンロードし、docker run kaitoy/pcap4j:latestでコンテナのeth0のパケットキャプチャーを実行できる。

このイメージはGitレポジトリにコミットがあるたびにビルドされる。

ビルド

開発に使っている環境は以下。

Mavenコマンドでのビルド手順 (推奨)

  1. WinPcap/libpcapインストール:
    WindowsであればWinPcap、Linux/Unixであればlibpcapをインストールする。 ビルド時に実行されるunit testで必要なので。
  2. JDK 1.6+インストール:
    JDKの1.6以上をダウンロードしてインストール。JAVA_HOMEを設定する。
  3. Mavenインストール:
    Mavenの3.0.5以上をインストールして、そのbinディレクトリにPATHを通す。
  4. Gitをインストール:
    Gitをダウンロードしてインストールする。 Gitのインストールはビルドに必須ではないので、このステップはスキップしてもよい。
  5. Pcap4Jのレポジトリのダウンロード:
    Gitをインストールした場合はgit clone git@github.com:kaitoy/pcap4j.git を実行する。 インストールしていない場合は、zipでダウンロードして展開する。
  6. ビルド:
    プロジェクトのルートディレクトリにcdして、mvn install を実行する。 unit testを通すためにはAdministrator/root権限が必要。

Eclipse上でのビルド手順

  1. WinPcap/libpcapインストール:
    WindowsであればWinPcap、Linux/Unixであればlibpcapをインストールする。 ビルド時に実行されるunit testで必要なので。
  2. Eclipseインストール:
    Eclipse.orgあたりでダウンロードして解凍するだけ。
  3. M2Eインストール:
    EclipseのGUIで、[ヘルプ]＞[新規ソフトウェアのインストール] を開き、 作業対象に http://download.eclipse.org/technology/m2e/releases を入力してEnter。 m2e - Eclipse用のMaven統合をチェックして次へ。 使用条件の条項に同意しますにチェックして完了。 m2eのインストールが完了したらEclipseを再起動。
  4. Gitをインストール:
    Gitをダウンロードしてインストールする。 Gitのインストールはビルドに必須ではないので、このステップはスキップしてもよい。
  5. Pcap4Jのレポジトリのダウンロード:
    Gitをインストールした場合はgit clone git@github.com:kaitoy/pcap4j.git を実行する。 インストールしていない場合は、zipでダウンロードして展開する。
  6. プロジェクトのインポート:
    EclipseのGUIで、ファイル ＞ インポート を開き、 一般 ＞ 既存プロジェクトをワークスペースへでPcap4Jの全プロジェクトをインポートする。
  7. ビルド:
    EclipseのGUIのプロジェクト・エクスプローラーで、Pcap4Jの親プロジェクトを右クリックして、 実行 ＞ Maven installを実行する。 unit testを通すためにはAdministrator/root権限が必要。

因みに、M2Eは旧m2eclipse。 m2eclipseでビルドしたい場合は、ステップ2をスキップして、ステップ4でMavenプロジェクトの方をインポートすればよい。

ライセンス

Pcap4J is distributed under the MIT license.

Copyright (c) 2011-2015 Pcap4J.org

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.

以下に定める条件に従い、本ソフトウェアおよび関連文書のファイル（以下「ソフトウェア」）の複製を取得するすべての人に対し、
ソフトウェアを無制限に扱うことを無償で許可します。これには、ソフトウェアの複製を使用、複写、変更、結合、掲載、頒布、サブライセンス、
および/または販売する権利、およびソフトウェアを提供する相手に同じことを許可する権利も無制限に含まれます。
上記の著作権表示および本許諾表示を、ソフトウェアのすべての複製または重要な部分に記載するものとします。

ソフトウェアは「現状のまま」で、明示であるか暗黙であるかを問わず、何らの保証もなく提供されます。
ここでいう保証とは、商品性、特定の目的への適合性、および権利非侵害についての保証も含みますが、それに限定されるものではありません。
作者または著作権者は、契約行為、不法行為、またはそれ以外であろうと、ソフトウェアに起因または関連し、
あるいはソフトウェアの使用またはその他の扱いによって生じる一切の請求、損害、その他の義務について何らの責任も負わないものとします。

コンタクト

Kaito Yamada (kaitoy@pcap4j.org)

おまけ

Pcap4J を使ったSNMPネットワークシミュレータ、SNeO。Githubに公開しました: https://github.com/kaitoy/sneo