Deployment
The topics in this section provide information regarding the deployment of applications built with PCAP Filter.
Topics
User Mode Library
The user-mode library must be deployed to end-user systems along with the kernel-mode drivers; the version of the kernel-mode drivers on the end-user systems must be equal to or newer than the version of the user-mode library. Thus, when the user-mode library is installed or updated on end-user systems, it is required to ensure that the kernel-mode drivers already present in the system are updated to match the version of the installed user-mode library.
The user-mode libraries come as dynamic libraries (DLLs) with import libraries, named pcapfilter24.dll and pcapfilter24.lib, respectively (available for x64, ARM64, and x86 processor architectures).
Deploy the .dll file to the target system and place it next to the application's .exe file.
Alternatively, the native library may be placed into one of directories, the paths to which are contained in the PATH environment variable, such as C:\Windows\System32 (or C:\Windows\SysWOW64 when deploying a 32-bit application on a 64-bit Windows system).
Remember to deploy the drivers too, as they are an integral part of PCAP Filter.
General Information
The topics in this section provide general information about various aspects of the product's functionality.
IPMonitor Topics
The topics in this section provide additional information specific to the IPMonitor class.
Topics
Network Filter Library
The IPMonitor class requires a libpcap-compatible library to be installed in the system.
Windows
On Windows 10 and later, the class requires npcap to be installed. On Windows 7 and 8, either npcap or Winpcap can be used.
Linux
On Linux, the class will automatically attempt to locate libpcap if it is installed. The following commands may be used to install libpcap:
sudo apt install libpcap0.8
or
yum install libpcap
macOS
On macOS, libpcap must be present in the system. It can be installed from source by downloading the source code from the TCPDump site and building it locally.
Alternatively, libpcap can also be installed via the Homebrew package manager on macOS:
brew install libpcap
System Configuration in Linux and macOS
In systems like Linux, *BSD and macOS, capturing the network traffic requires special configuration, and the approach is different between Linux and macOS, supported by the product. In most cases, the superuser or root can capture the network traffic without any extra steps; below instructions are mostly applicable to limited users who want to use an application without elevating rights (or those who don't have root or sudo rights in the first place).
Linux
In Linux, the process that attempts to capture the traffic, must have cap_net_raw and cap_net_admin capabilities. These capabilities are added by the operator or setup script using a command similar to
sudo setcap cap_net_raw,cap_net_admin=eip {path-to-process}
Note that the setcap tool replaces the capabilities, so if the process must have other capabilities too, all of them must be included in the command.
macOS
In macOS, the procedure is more complicated. There are several devices related to packet capturing present, which can be listed using the command
ls -l /dev/bpf*
You will need to adjust permissions of those devices.
The common approach is to create a dedicated group, which will have read-write access to those devices, and add a user (the one who needs access to capturing) to this group. A simple sequence of steps here is:
sudo chgrp your_group /dev/bpf*
sudo chmod 660 /dev/bpf*
where "your_group" is the name of the group to which the user account belongs. If necessary, you can create a dedicated group for BPF monitoring, add a user to this group, then use the group as shown above.
The above changes should be done on every system start, so it may be necessary to configure a small launch daemon which will execute the above lines:
- Write the above or similar lines to a file, let's call it "set_bpf_perms.sh"
- make the script executable by using chmod:
chmod +x /path/to/set_bpf_perms.sh" - Create a launch daemon plist file (e.g., com.user.bpf.plist) in /Library/LaunchDaemons:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.user.bpf</string> <key>ProgramArguments</key> <array> <string>/path/to/set_bpf_perms.sh</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> </dict> </plist> </xml> - Load the daemon:
sudo launchctl load /Library/LaunchDaemons/com.user.bpf.plist
Additional information on BPF devices and libpcap can be found in the libpcap files.
Buffer Parameters
Some events include one or more parameters intended for use as a binary data buffer. Depending on the event, these parameters may contain data when the event is fired, or it may be expected that the application populates them with the desired amount of data during the event handler. Some events combine both paradigms and then expect the application to modify the data already present when the event is fired.
The documentation for such events will describe which of these cases applies to each buffer parameter. In all cases, buffer parameters point to a preallocated block of unmanaged memory, the size of which is specified by the parameter immediately following the buffer parameter. In cases in which data are to be written, be sure to write it directly to the pointed-to memory, do not change the value of the buffer parameter itself.