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!
Features:
- List devices
- Open capture handle on a device or savefiles
- Get packets from the capture handle
- Filter packets using BPF programs
- List/set/get datalink link types
- Configure some parameters like promiscuity and buffer length
- Write packets to savefiles
- Inject packets into an interface
See examples for usage.
Building
This crate requires the libpcap (or Npcap on Windows) library.
Installing dependencies
Windows
- Install Npcap.
- Download the Npcap SDK.
- Add the SDK's
/Lib
or/Lib/x64
folder to yourLIB
environment variable.
Linux
Install the libraries and header files for the libpcap library. For example:
- On Debian based Linux: install
libpcap-dev
. - On Fedora Linux: install
libpcap-devel
.
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 = "1", features = ["capture-stream"] }
This feature is supported only on Linux and Mac OS X. It will not work and is not supported on Windows.
Minimum Supported Rust Version (MSRV)
This crate uses Rust 2018 and requires a compiler version >= 1.46.
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.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
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.