search

rust-pcap / pcap

Rust language pcap library
Apache License 2.0
639 stars 146 forks source link

readme

pcap

This is a Rust language crate for accessing the packet sniffing capabilities of libpcap (or Npcap on Windows). If you need anything, feel free to post an issue or submit a pull request!

Linux Mac OS Windows Coverage Crates.io Docs.rs

Features:

See examples for usage.

Building

This crate requires the libpcap (or Npcap on Windows) library.

Installing dependencies

Windows

  1. Install Npcap.
  2. Download the Npcap SDK.
  3. Add the SDK's /Lib or /Lib/x64 folder to your LIB environment variable.

Linux

Install the libraries and header files for the libpcap library. For example:

Note: If not running as root, you need to set capabilities like so: sudo setcap cap_net_raw,cap_net_admin=eip path/to/bin.

Mac OS X

libpcap should be installed on Mac OS X by default.

Note: A timeout of zero may cause pcap::Capture::next to hang and never return (because it waits for the timeout to expire before returning). This can be fixed by using a non-zero timeout (as the libpcap manual recommends) and calling pcap::Capture::next in a loop.

Linking

It is your responsibility, as the crate user, to configure linking with libpcap/wpcap to suit your needs (e.g. library version, static vs. dynamic linking, etc.) via your own build script. For most setups, the defaults are most likely sufficient and you don't have to do anything special beyond installing libpcap as described above. The notes below are provided if the defaults are not suitable.

Supporting different library versions

This crate supports several different versions of libpcap, such as wpcap, to ensure it can be compiled against older versions while still providing access to functionality available in newer versions. The build script will try to automatically detect the right version and configure pcap, but it may fail at this task. Especially, if you have an unusual build setup. If you are getting compilation error of the form

cannot find function `pcap_<some_function>` in module `raw`

then that is probably what is happening. It is likely that your libpcap does not support the newest libpcap API and pcap failed to query libpcap to find out which unsupported features it should exclude.

To solve this, you can try helping the pcap crate compile the correct feature set that is compatible with your libpcap using the following two approaches:

Library Location

If you are linking dynamically with libpcap, pcap will try to consult libpcap for its version. However, if your library is in an unconventional location and you had to customize cargo:rustc-link-search=native in your own build script, pcap's build script is unable to pick up on that and will default to the most recent API version. If you are not using the most recent library version, please communicate the library's location to pcap's build script using the LIBPCAP_LIBDIR environment variable.

If LIBPCAP_LIBDIR is unset, the build will attempt to find the library via pkg-config instead. On most setups, this is the easiest way to get things working and may even eliminate the need for any custom build scripts in your software.

Library Version

If setting the library location does not work or you are linking statically, you may need to set the libpcap version manually. You can do this by setting the environment variable LIBPCAP_VER to the desired version (e.g. env LIBPCAP_VER=1.5.0). By default, if pcap fails to query libpcap/wpcap for its API version, it will assume the newest API so this should only be necessary if you are using an old version of libpcap.

Note that LIBPCAP_VER is respected even if you haven't set LIBPCAP_LIBDIR and are using pkg-config. If it is unset, we'll find whatever available version as long as it's supported by the library.

Optional Features

capture-stream

Use the capture-stream feature to enable support for streamed packet captures.

[dependencies]
pcap = { version = "2", features = ["capture-stream"] }

Unstable Features

Use at your own risk, we do not consider this our public API yet.

lending-iter

Use the lending-iter feature to enable the lending packet iterator. See lendingiterprint example.

Minimum Supported Rust Version (MSRV)

This crate uses Rust 2021 and requires a compiler version >= 1.63.

The feature capture-stream depends on tokio = "1.0". Therefore, when capture-stream is enabled, this crate requires a compiler version new enough to compile the tokio crate.

Some dependencies no longer support our chosen MSRV. Since many crates do not consider this a breaking change there is not much that can be done to prevent this through semver requirements. However, users can protect themselves against such incompatibility with Cargo.lock file. We provide msrv.lock which is the lockfile against which we test MSRV builds in our CI.

Discuss the MSRV.

License

Licensed under either of

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.