読み込みのためにキャプチャのハンドルをオープン

ライブキャプチャ、キャプチャが行われるべきである、ネットワークまたは他のインタフェースの与えられた名前のためのハンドルをオープンするためには、ハンドルで適切なオプションを設定する pcap_create() を呼び出し、次に pcap_activate() でそれを活性化します。

ライブキャプチャのためにオープンすることができるデバイスのリストを取得するためには、 pcap_findalldevs() を呼び出します。 pcap_findalldevs() によって返されたリストを解放するためには、 pcap_freealldevs() を呼び出します。 pcap_lookupdev() は、``ループバック'' ネットワークインタフェースでないそのリストの最初のデバイスを返します。

``savefile'' のパスを与えられ、パケットを読み込むために ``savefile'' のためのハンドルをオープンするためには、 pcap_open_offline() を呼び出します。読み込みのために既にオープンされているファイルを参照する FILE * を与えられて、``savefile'' のためのハンドルをセットアップするためには、 pcap_fopen_offline() を呼び出します。

書き込みのために ``savefile'' をオープンし、フィルタ表現をコンパイルするルーチンのように、引数として pcap_t を要求するルーチンで使用するために ``偽の'' pcap_t を取得するためには、 pcap_open_dead() を呼び出します。

pcap_create(), pcap_open_offline(), pcap_fopen_offline() と pcap_open_dead() は、キャプチャストリームまたは ``savefile'' からパケットを読み込むために、そしてキャプチャストリームまたは ``savefile'' に関する情報を見つけるために使用するハンドルである、 pcap_t へのポインタを返します。ハンドルをクローズするためには、 pcap_close() を使用します。

キャプチャハンドルで次のオプション設定できます

スナップショットの長さ (snapshot length)

キャプチャするとき、利用者がパケットの全体の内容をキャプチャするるなら、それは、パケットを利用者のアプリケーションにコピーするために多くの CPU 時間、パケットデータをファイルに書き込むために多くのディスク空間と場合によりネットワーク回線容量、とパケットを保存するためにより多くのディスク空間を必要とします。利用者がパケット全体の内容を必要としないなら - 例えば、パケットの TCP ヘッダのみに関心があるなら、 - 利用者は、キャプチャのための "スナップショットの長さ"を適切な値に設定できます。スナップショットの長さが snaplen に設定されて、 snaplen がキャプチャされるパケットのサイズ以下であるなら、パケットの最初の snaplen バイトのみがキャプチャされ、パケットデータとして提供されます。

パケットから利用可能なすべてのデータをキャプチャするためにすべてのネットワークではありませんが、ほとんどで、 65535 のスナップショットの長さは、十分でしょう。

スナップショットの長さは、 pcap_set_snaplen() で設定されます。

プロミスキャス (混合) モード (promiscuous mode)

イーサネットのようなブロードキャスト (同報通信) LAN では、ネットワークが切り換えられないか、またはアダプタがスイッチを通過するすべてのパケットが、送信されるスイッチの "ミラーポート"に接続されるなら、ネットワークアダプタは、ネットワークアダプタが認識するように設定されていないネットワークアドレスに送信されなかったユニキャストまたはマルチキャストパケットを含んでいる、LAN ですべてのパケットを受信します。

通常、そのアダプタは、それらのパケットを捨てます。しかしながら、多くのネットワークアダプタは、パケットがアダプタが認識するアドレスに送信されなくても、すべてのパケットは、ホストに提供されるモードである、"プロミスキャスモード"をサポートします。これは、解析のために 2 つ以上の他のホストの間のトラフィックをそのままキャプチャするために役に立ちます。

アプリケーションがプロミスキャスモードを設定しなくても、アダプタは、ある他の理由のためにプロミスキャスモードとなるかもしれないことに注意してください。

今のところ、これは、"any (どの)"デバイスでも動作していません。 "any"または NULL の引数が供給されるなら、プロミスキャスモードの設定は、無視されます。

プロミスキャスモードは、 pcap_set_promisc() で設定されます。

ミラーモード (monitor mode)

IEEE 802.11 無線 LAN では、たとえアダプタがプロミスキャスモードであっても、関連しているネットワークのためにフレームだけをホストに提供します。それは、また、管理または制御フレームではなく、データフレームだけを提供し、それらのフレームのために 802.11 ヘッダまたはラジオ情報疑似ヘッダを供給しないかもしれません。

また時々 "rfmon モード" ("Radio Frequency MONitor" (ラジオ周波数モニタ) のために) と呼ばれる "モニタモード"で、アダプタは、それが 802.11 ヘッダで受信するすべてのフレームを提供し、同様にフレームに関するラジオ情報で疑似ヘッダを提供するかもしれません。

モニタモードで、アダプタは、利用者がそのアダプタで任意の無線ネットワークを使用することができないように、それに関連しているネットワークから分離するかもしれないことに注意してください。これは、利用者がモニタモードでキャプチャし、別のアダプタで別のネットワークに接続されないなら、ネットワークサーバのファイルにアクセスするか、またはホスト名またはネットワークアドレスを解決することを防ぐかもしれません。

pcap_set_rfmon() でモニタモードを設定し、アダプタをモニタモードにすることができるかどうかを決定するために pcap_can_set_rfmon() を使用することができます。

読み込みタイムアウト (read timeout)

キャプチャするとき、パケットが到着するとすぐに配信されるなら、パケットをキャプチャするアプリケーションは、パケットが到着するとき、各パケットのために起こされます、そして各パケットを取って来るためにオペレーティングシステムを 1 回以上の呼び出しを行わなければならないかもしれません。

そうでなくて、パケットを到着するとすぐに配信されませんが、 ("読み込みタイムアウト"と呼ばれる) 少しのディレイ (遅れ) の後に配信されるるなら、複数のパケットのために単一の wakeup (起きること) を行い、オペレーティングシステムに行われる呼び出しの各組は、単一のパケットではなく、複数のパケットを供給することができるように、パケットが配信される前に、2 つ以上のパケットを蓄積することができます。パケットが高いレートで到着するなら、これは、キャプチャすることができる 1 秒毎のパケットの数を増加させ、パケット毎の CPU のオーバヘッドを削減します。

読み込みタイムアウトは、パケットを配信する前に、アプリケーションがオペレーティングシステムのキャプチャバッファを満たすために wait (待ち) しなくてもよいように要求されます。パケットがゆっくり到着するなら、その wait (待ち) は、任意に長い期間がかかるかもしれません。

すべてのプラットフォームが、読み込みタイムアウトをサポートしているというわけではありません。それを行わないプラットフォームでは、読み込みタイムアウトは、無視されます。読み込みタイムアウトをサポートするプラットフォームでは、タイムアウトの 0 値によって、読み込みは、タイムアウトなしで、パケットが到着するのを十分可能なだけ wait (待ち) します。

注: いくつかのプラットフォームでは、読み込みタイムアウトがサポートされず、いくつかのプラットフォームでは、タイマは、少なくとも 1 つのパケットが到着するまで開始しないので、時間の制限された期間以内に返るためにパケットを読み込む呼び出しを引き起こすために読み込みタイムアウトを使用することができません。これは、読み込むタイムアウトが使用されるべきで ない ことを意味します、例えば、パケットキャプチャのループがユーザ入力のために定期的に ``ポーリング'' することができるインタラクティブなアプリケーションで、パケットが到着しなくても、タイムアウトが期限が切れた後に、パケットを読み込む呼び出しが、返るという保証が全くない場合です。

読み込みタイムアウトは、 pcap_set_timeout() で設定されます。

バッファサイズ (buffer size)

キャプチャのために到着するパケットは、到着するとすぐに、アプリケーションに読み込まれる必要がないように、バッファに格納されます。いくつかのプラットフォームでは、バッファのサイズを設定することできます。小さ過ぎるサイズは、あまりに多くのパケットがキャプチャされ、スナップショットの長さがバッファリングされるデータの量を制限しないなら、大き過ぎるサイズは、パケットが落されることを防ぐために必要とするより、より多くのページング不可能なオペレーティングシステムのメモリを使用するかもしれませんが、アプリケーションが、それからパケットを読み込むことができる前に、バッファが満杯になるなら、パケットが落されるかもしれないことを意味します。

バッファサイズは、 pcap_set_buffer_size() で設定されます。

タイムスタンプのタイプ (timestamp type)

いくつかのプラットフォームにおいて、ライブキャプチャのパケットに与えられたタイムスタンプは、異なる解決があるかもしれないか、またはネイティブのオペレーティングシステムのルーチンによって供給された現在の時刻のための時間の値と異なる関係があるかもしれない、異なったソースから来るかもしれません。タイムスタンプのタイプのリストについては、 pcap-tstamp(7) を参照してください。

タイムスタンプのタイプは、 pcap_set_tstamp_type() で設定されます。

ネットワークインタフェースからパケットを読み込むことは、利用者に特権があることを必要とします:

NIT または BPF がある SunOS 3.x または 4.x の下で:

利用者には、 /dev/nit または /dev/bpf* の読み込みアクセスができなければなりません。

DLPI がある Solaris の下で:

利用者には、ネットワーク疑似デバイス、例えば、 /dev/le の読み込み/書き込みアクセスができなければなりません。しかしながら、 Solaris の少なくともいくつかのバージョンでは、これは、 tcpdump がプロミスキャスモードでキャプチャすることができるために十分ではありません。 Solaris のそれらのバージョンでは、プロミスキャスモードでキャプチャするために、利用者は、root でなければなりません、またはパケットをキャプチャするアプリケーションは、root に setuid してインストールされていなければなりません。多く (おそらくすべて) のインタフェースで、利用者がプロミスキャスモードでキャプチャしないなら、利用者は、任意の発信パケットを見れないので、プロミスキャスモードで行われなかったキャプチャは、それほど役に立たないことに注意してください。

Solaris の新しいバージョンでは、利用者は、 net_rawaccess 特権を与えられていなければなりません。これは、ネットワーク疑似デバイスへのアクセスを利用者に与えるために必要で十分です - そのデバイスで特権を変更する必要はありません。例えば、 usermod (1M) コマンドでユーザの defaultpriv キーにその特権を追加することによって、その特権をユーザに与えることができます。

DLPI がある HP-UX の下で:

利用者は、ルートでなければならないか、またはパケットをキャプチャするアプリケーションが、ルートに setuid をしてインストールされていなければなりません。

スヌープ (snoop) がある IRIX の下で:

利用者は、ルートでなければならないか、またはパケットをキャプチャするアプリケーションが、ルートに setuid をしてインストールされていなければなりません。

Linux の下で:

利用者は、ルートでなければならないか、または (利用者の配布に、 CAP_NET_RAW とそれらがログインするとき、ユーザの初期プロセスでそれらのビットを設定するのを許容するために、それらのケーパビリティビットを特定のアカウントに与えられることができるコードのようなケーパビリティビットをサポートするカーネルがないなら、その場合、利用者には、キャプチャするための CAP_NET_RAW と、例えば、 -D フラグでネットワークデバイスを列挙するための CAP_NET_ADMIN がなければなりませんが) パケットをキャプチャするアプリケーションが、ルートに setuid をしてインストールされていなければなりません。

ULTRIX と Digital UNIX/Tru64 UNIX の下で:

任意のユーザが、ネットワークトラフィックをキャプチャします。しかしながら、(スーパユーザでさえない) ユーザは、スーパユーザが pfconfig(8) を使用するインタフェースでプロミスキャスモードの操作を有効にしていないなら、インタフェースでプロミスキャスモードでキャプチャすることができません、そして、(スーパユーザでさえない) ユーザは、スーパユーザが pfconfig を使用するインタフェースでコピーオールモード (copy-all-mode) の操作を有効にしていないなら、インタフェースでマシンによって受信されるか、または送信されるユニキャストトラフィックをキャプチャすることができませんので、インタフェースで 役に立つ パケットのキャプチャは、そのインタフェースで有効にされるプロミスキャスモードまたはコピーオールモード操作のいずれか、または両方の操作モードをたぶん必要とします。

(Mac OS X を含んで) BSD の下で:

利用者は、クローニング BPF デバイスを持っていないシステムで /dev/bpf* または、持っているシステムで /dev/bpf への読み込みアクセスがなければなりません。 (Mac OS X を含んで) devfs がある BSDs では、これは、 BPF デバイスで所有権またはパーミッションを設定するスーパユーザのアクセスがある誰かが単に持つ以上の必要があるかもしれません - システムがブートされるたびに、システムが devfs サポートしていても、所有権またはパーミッションを設定するために devfs を設定するする必要があるかもしれません。それをサポートしないなら、利用者は、ブート時に起こるようにするある他の方法を見つけなければならないかもしれません。

保存されたパケットファイルを読み込むために特権を必要としません。

ハンドルから読み込まれたパケットは、パケットメタデータの様々な形式を含んでいる ``偽ヘッダ''、たぶんその内容が異なるネットワークインタフェースのための異なるかもしれないリンクレイヤヘッダを含んでいます。ハンドルによって供給されたパケットの形式を決定するためには、 pcap_datalink() を呼び出します。 http://www.tcpdump.org/linktypes.html は、それが返す値をリストし、それらの値に対応するパケットの形式を記述しています。

``savefile'' のためにオープンされる pcap_t に対応する FILE * を得るためには、 pcap_file() を呼び出します。

ルーチン

ライブキャプチャのためのリンクレイヤヘッダタイプを選択

いくつかのデバイスは、2 つ以上のリンクレイヤヘッダタイプを提供します。デバイスによって提供されるすべてのリンクレイヤヘッダタイプのリストを取得するためには、デバイスのために活性化された pcap_t で pcap_list_datalinks() を呼び出します。リンクレイヤヘッダタイプのリストを解放するためには、 pcap_free_datalinks() を呼び出します。デバイスのためにリンクレイヤヘッダタイプを設定するためには、 pcap_set_datalink() を呼び出します。これは、デバイスが活性化された後に、行われるべきですが、あらゆるパケットが読み込まれる前で、あらゆるフィルタがコンパイルされるかインストールされる前です。

ルーチン

パケットを読み込む

パケットは、1 つ以上のパケットを処理する、 pcap_dispatch() または pcap_loop() で、各パケットのためのコールバックルーチンを呼び出すか、または次のパケットを返す pcap_next() または pcap_next_ex() で読み込まれます。 pcap_dispatch() と pcap_loop() のためのコールバックは、次のメンバを含む struct pcap_pkthdr へのポインタが提供されます:

pcap_next_ex() は、ポインタ引数を通してそのポインタを提供します。 pcap_next() は、 struct pcap_pkthdr 構造体を指す引数が渡され、それに書き込みます。

また、コールバックは、(コールバックルーチンへ渡される struct pcap_pkthdr ポインタで与えられるような) パケットの最初の caplen バイトのデータへの const u_char ポインタを供給されます。これは、必ずしもパケット全体となるというわけではありません。すべてのパケットをキャプチャするために、利用者は、 pcap_set_snaplen() への呼び出しでパケットのデータのすべてを得るために十分大きな snaplen のための値を提供しなければなりません - 値が 65535 であれば、すべてのネットワークでないなら、ほぼ十分のはずです)。 ``savefile'' から読み込むとき、キャプチャが実行されたとき指定されたスナップショットの長さは、利用可能なパケットデータの総量を制限します。 pcap_next() は、そのポインタを返します。 pcap_next_ex() は、ポインタ引数を通してそのポインタを提供します。

pcap_dispatch() または pcap_loop() のループを強制的に終了するためには、 pcap_breakloop() を呼び出します。

デフォルトで、ライブキャプチャのためにオープンされたインタフェースからパケットを読み込むとき、 pcap_dispatch(), pcap_next() と pcap_next_ex() は、パケットが読み込まれるれることが現在利用可能でなければ、利用可能となるパケットのためのウェートをブロックします。すべてのプラットフォームでは なく いくつかで、読み込みタイムアウトが指定されたなら、ウェートは、読み込みタイムアウトが終了した後に終了します。アプリケーションは、いくつかのプラットフォームで起こるように、このために準備されているべきですが、他のプラットフォームで起こらないので、それに依存するべきではありません。

ハンドルは、``非ブロッキングモード'' (non-blocking mode) に入れることができるので、それらのルーチンは、ブロッキングするのではなく、パケットが読み込みできないことを示す印を返します。ハンドルを非ブロッキングモードに入れるか、または非ブロッキングモードから抜けるためには、 pcap_setnonblock() を呼び出します。ハンドルが非ブロッキングモードであるかどうか判断するためには、 pcap_getnonblock() を呼び出します。非ブロッキングモードは、Mac OS X 10.6 で正確に動作しないことに注意してください。

非ブロッキングモードは、しばしば select(2) または poll(2) またはプラットフォームが 1 組の記述子のうちのいずれかでデータの有効性のためにウェートすることを申し出る他のルーチンのようなルーチンと組み合わされます。ハンドルのために、それらのルーチンで使用することができる記述子を取得するためには、 pcap_get_selectable_fd() を呼び出します。すべてのハンドルが、そのような記述子を利用可能にしておくとは限りません。 pcap_get_selectable_fd() は、そのような記述子が存在しないなら、-1 を返します。さらに、様々な理由で、それらのルーチンの 1 つ以上は、記述子で適切に動作しません。 pcap_get_selectable_fd() のための文書は、詳細を示します。

ルーチン

フィルタ

パケットを読み込むとき、特定のパケットだけを返すためには、ハンドルでフィルタを設定することができます。ライブキャプチャについては、フィルタリングは、カーネルからユーザモードまでの ``つまらない'' パケットのコピーを避けるために、できれば、カーネルモードで実行されます。

テキスト文字列としてフィルタを指定することができます。文字列の構文とセマンティックスは、 pcap-filter(7) によって記述された通りです。フィルタの文字列は、 pcap_compile() によって疑似マシン語 (pseudo-machine-language) でプログラムにコンパイルされ、 pcap_setfilter() でハンドルに対して結果のプログラムをフィルタリングすることができます。 pcap_compile() の結果は、 pcap_freecode() への呼び出しで解放することができます。 pcap_compile() は、フィルタの文字列の特定の表現のためのネットワークマスクを要求します。与えられたキャプチャデバイスののためのネットワークアドレスとネットワークマスクを見つけるために pcap_lookupnet() を使用することができます。

また、コンパイルされたフィルタを pcap_offline_filter() を使用して読み込まれたパケットに直接適用することができます。

ルーチン

着信と発信パケット

デフォルトで、libpcap は、マシンによって送信されたパケットとマシンによって受信されたパケットの両方をキャプチャすることを試みます。それをマシンによって受信されたパケットだけ、またはできれば、マシンによって送信されたパケットだけをキャプチャすることを制限するためには、 pcap_setdirection() を呼び出します。

ルーチン

キャプチャの統計

ライブキャプチャで受信され、落されたパケットに関する統計を取得するには、 pcap_stats() を呼び出します。

ルーチン

キャプチャされたパケットを書き込むためのハンドルをオープン

``savefile'' にあるべきパス名を与えられ、パケットを書き込むために ``savefile'' をオープンするためには、 pcap_dump_open() を呼び出します。 ``savefile'' にあるべきパス名を与えられ、パケットを書き込むために ``savefile'' をオープンするためには、 pcap_dump_open() を呼び出します。書き込みのために既にオープンされているファイルを参照する FILE * を与えられて、``savefile'' のためのハンドルをセットアップするためには、 pcap_dump_fopen() を呼び出します。それらは各々、``savefile'' にパケットを書き込むために使用されたハンドルである、 pcap_dumper_t へのポインタを返します。それが成功するなら、それが存在しないなら、ファイルを作成し、それが存在するなら、ファイルを切り詰めます。 pcap_dumper_t をクローズするためには、 pcap_dump_close() を呼び出します。

ルーチン

パケットを書き込む

pcap_dumper_t にパケットを書き込むためには、 pcap_dump() を呼び出します。 pcap_dump() で書き込まれたパケットは、``savefile'' に直接書き込むのではなく、バッファリングされます。 pcap_dumper_t をクローズすることによって、すべてのバッファリングされているが、まだ書き込まれていない (buffered-but-not-yet-written) パケットは、 ``savefile'' に書き込まれるます。 pcap_dumper_t をクローズせずに、``savefile'' に書き込むために pcap_dumper_t によってバッファリングされるので、 pcap_dumper_t に ``savefile'' にまだ書き込まれていない、すべてのパケットを強制的に書き込むためには、 pcap_dump_flush() を呼び出します。

ルーチン

パケットを注入

必要な特権があるなら、 pcap_inject() または pcap_sendpacket() を使用して、ライブキャプチャのための pcap_t でネットワークにパケットを注入することができます。 (2 つのルーチンは、OpenBSD と WinPcap の両方との互換性のために存在します。それらは、同じ機能を実行しますが、異なる返り値があります。)

ルーチン

エラーの報告

いくつかのルーチンは、エラーまたは警告の状態コードを返します。それらを文字列に変換するためには、 pcap_statustostr() を使用します。

ルーチン

ライブラリバージョン情報を取得

libpcap に関するバージョン情報を与える文字列を取得するためには、 pcap_library_version() を呼び出します。

ルーチン