Npcap Users' Guide

You may notice that Npcap has several version strings. The installer name can be something like npcap-0.07-r5.exe. “0.07” is the version number, and “r5” is the revision number. We use a version number less than “1.00” to imply that it's still a beta release. This naming follows the Nmap's convension. However, WinPcap follows a different version system. It has three dotted figures like “4.1.3”, which is more Wireshark-like. One thing you need to know here is that Npcap starts the development based on the latest WinPcap “4.1.3”. So any Npcap release is more advanced than WinPcap's latest release. Another thing needs to notice is that, the “0.07” version number can be obtained from the pcap_lib_version function. The “r5” revision number only appears in the installer filename, it doesn't show its existence in any code or functions. So you'd better not determine anything based on Npcap revision number. Just use the latest release.

The executable file version (aka e-version in this document) is another thing we need to notice. A e-version has four dotted figures on Windows. Npcap's e-version is something like “5.0.7.424”. “5” here is used to advance Npcap version than the legacy WinPcap's e-version “4.1.0.2980” because “5.0.7.424” is larger than “4.1.0.2980”. The legacy WinPcap installer and Wireshark uses e-version to check the version of WinPcap. Usually these legacy codes don't even know Npcap. So Npcap needs to make them simply think Npcap is a newer version of WinPcap. “0” and “7” in Npcap's e-version corresponds to Npcap's version “0.07”. “424” means that this release is built at date “4.24” (aka 24th, April). When Npcap version jumps to a new version (like from “0.06” to “0.07”), the e-version will also change (like from “0.6.0.301” to “0.7.0.424”). A revision update won't cause a change of version or e-version.

You can check the existence of C:\Program Files\Npcap\NPFInstall.exe to detect Npcap's existence. If Npcap exists, you can check the file version of C:\Program Files\Npcap\NPFInstall.exe to detect Npcap e-version. The e-version also gives you the version. The NSIS code is shown below. $inst_ver is an e-version string like “5.0.7.424”

GetDllVersion "C:\Program Files\Npcap\NPFInstall.exe" $R0 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF
IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $inst_ver "$R2.$R3.$R4.$R5"

You can check the installation options of an already installed Npcap by reading the registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npf (WinPcap compatible mode) or HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npcap (Non-WinPcap compatible mode). the entries like AdminOnly, Loopback, DltNull,Dot11Support, VlanSupport, WinPcapCompatible, etc. show the installation options. Loopback is REG_SZ type. A non-NULL value indicates the option is CHECKED. All other entries are REG_DWORD type. A 0x00000001 value indicates the option is CHECKED.

Npcap and WinPcap can be installed together on a symtem. Which capture library is used by the user software relies on the DLL loading path. If Npcap's wpcap.dll is loaded first, then you are using Npcap, vice versa. However, it's difficult and fragile to check the DLL loading path by yourself. Fortunately, you can use pcap_lib_version to get the Npcap/WinPcap version string.

char *pcap_version = pcap_lib_version();
printf("%s", pcap_version);
// Npcap output: "Npcap version 0.08, based on libpcap version 1.8.0"
// WinPcap output: "WinPcap version 4.1.3"

Considering Npcap has different driver service names for different modes, we provide a way to get the current service name. You can query the registry key: HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Npcap\WinPcapCompatible for x64 systems (or HKEY_LOCAL_MACHINE\SOFTWARE\Npcap\WinPcapCompatible for x86 systems). If it's 1, it means Npcap is installed in “WinPcap Compatible Mode”. In this mode both npcap and npf services (drivers) are installed. If the key value is 0, it means Npcap is installed in “Non-WinPcap Compatible Mode”. In this mode only npcap service (driver) is installed. We recommend our users to use the npcap service instead of npf. Given that npcap service is always installed in both modes, a good practice is just trying the npcap service first. If it fails, then try the npf service. This is also what most of our users do in their software based on our investigation. A code sample from Nmap is here.

Npcap installs its DLLs into C:\Windows\System32\Npcap\ instead of WinPcap's C:\Windows\System32\. Based on the design of DLL search path, your application will use WinPcap first by default when Npcap and WinPcap coexist, as C:\Windows\System32\ is prior to C:\Windows\System32\Npcap\. So when Npcap and WinPcap coexist, an application that want to use Npcap instead of WinPcap must make C:\Windows\System32\Npcap\ precedent to the C:\Windows\System32\ in Dll search path. here we provide ways to modify this search path to make your application load Npcap's DLLs first. Here are two conditions based on how your application links Npcap/WinPcap's library (wpcap.dll).

Npcap uses service name “npcap” instead of WinPcap's “npf” with “WinPcap Compatible Mode” OFF. So applications using net start npf for starting service must change to this: run net start npcap first, if it fails, then try net start npf.

“Managed Mode” (for Linux) = “Extensible Station Mode” (aka “ExtSTA”, for Windows)

“Monitor Mode” (for Linux) = “Network Monitor Mode” (aka “NetMon”, for Windows)

“Master Mode” (for Linux) = “Extensible Access Point” (aka “ExtAP”, for Windows)

WlanHelper is used to set/get the operation mode (like “Monitor Mode”) for a wireless adapter on Windows. WlanHelper tries to follow the grammar of iwconfig, a wireless management tool for Linux. So if you rename WlanHelper.exe to iwconfig.exe, your command lines for WlanHelper will be exactly the same with the iwconfig tool.

C:\> WlanHelper.exe
WlanHelper for Npcap 0.07 (http://npcap.org)
Usage: WlanHelper {Interface Name or GUID} [Options]
Options:
  mode: get interface operation mode
  mode <managed|monitor|master|wfd_device|wfd_owner|wfd_client>: set interface operation mode
  modes: get all operation modes supported by the interface, comma-separated
  channel: get interface channel
  channel <1-11>: set interface channel (only works at monitor mode)
  freq: get interface frequency
  freq <0-200>: set interface frequency (only works at monitor mode)
Operation Modes:
  managed - the Extensible Station (ExtSTA) operation mode
  monitor - the Network Monitor (NetMon) operation mode
  master - the Extensible Access Point (ExtAP) operation mode (supported for Windows 7 and later)
  wfd_device - the Wi-Fi Direct Device operation mode (supported for Windows 8 and later)
  wfd_owner - the Wi-Fi Direct Group Owner operation mode (supported for Windows 8 and later)
  wfd_client - the Wi-Fi Direct Client operation mode (supported for Windows 8 and later)
Examples:
  WlanHelper wi-fi mode
  WlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da channel 11
  WlanHelper 42dfd47a-2764-43ac-b58e-3df569c447da freq 2
See the MAN Page (https://github.com/nmap/npcap) for more options and examples
        

C:\> netsh wlan show interfaces

There is 1 interface on the system:

    Name                   : Wi-Fi
    Description            : Qualcomm Atheros AR9485WB-EG Wireless Network Adapter
    GUID                   : 42dfd47a-2764-43ac-b58e-3df569c447da
    Physical address       : a4:db:30:d9:3a:9a
    State                  : connected
    SSID                   : LUO-PC_Network
    BSSID                  : d8:15:0d:72:8c:18
    Network type           : Infrastructure
    Radio type             : 802.11n
    Authentication         : WPA2-Personal
    Cipher                 : CCMP
    Connection mode        : Auto Connect
    Channel                : 1
    Receive rate (Mbps)    : 150
    Transmit rate (Mbps)   : 150
    Signal                 : 100%
    Profile                : LUO-PC_Network

    Hosted network status  : Not available

C:\> WlanHelper.exe wi-fi mode
managed
C:\> WlanHelper.exe wi-fi mode monitor
Success
C:\> WlanHelper.exe wi-fi mode 
monitor
C:\> WlanHelper.exe wi-fi mode managed
Success
C:\> WlanHelper.exe wi-fi mode
managed
        

The installation options are key-value pairs. The keys can be one of these values: /npf_startup, /loopback_support, /dlt_null, /admin_only, /dot11_support, /vlan_support, /winpcap_mode, representing the options in the GUI. The values can be one of these four values: yes, no, enforced, disabled.

An example of Npcap installation options is (for both “GUI Mode” and “Silent Mode”):

/npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=no

We may disable or enforce certain options in the installer GUI to make them unselectable. This usually means that those options can easily cause compatible issues and are considered not suitable for beginners, or we think we need to enforce some rules for the Npcap API. Advanced users can still change their states via command-line parameters, which is described in following sections.

Fortunately, if a distributor wants to start the Npcap installer GUI and disable or enforce certain options for reasons like compatibility. It can also use the four value mechanism by setting the command-line parameters to disabled or enforced. For example, the following command will start an installer GUI with the dlt_null disabled and unselected:

npcap-0.08.exe /dlt_null=disabled

Default options for Npcap installer GUI can be changed. An example is:

npcap-0.08.exe /npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=yes

or even simpler:

npcap-0.08.exe /winpcap_mode=yes

As the default option of /winpcap_mode is no. Running the installer directly without options will see Install Npcap in WinPcap API-compatible Mode UNCHECKED by default in the “Installation Options” page. However, the above two commands will launch the installer GUI, and in the “Installation Options” page, the Install Npcap in WinPcap API-compatible Mode option will be CHECKED by default.

An example of changing option feature for silent installation is:

npcap-0.08.exe /S /npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=yes

Npcap has its own SDK for “Non-WinPcap Compatible Mode”. By using it, your software will run under “Non-WinPcap Compatible Mode”. We don't update the SDK as frequently as the binaries. The latest SDK is Npcap SDK 0.07 r9.

If you only want to build your software under “WinPcap Compatible Mode” (which is NOT recommended), please use the legacy WinPcap 4.1.2 Developer's Pack instead.

This document currently only addresses the Npcap particular features. It doesn't show you the basics about the general WinPcap usage. As Npcap shares the libpcap API with WinPcap, you can always refer to the WinPcap documentation for general usage of Npcap.

You can refer to WinPcap's examples to see the usage.

I also provided an example: UserBridge, which is a tool to redirect all packets from an interface to another.

Npcap has provided a diagnostic utility called DiagReport. It provides a lot of information including OS metadata, Npcap related files, install options, registry values, services, etc. You can simply click the C:\Program Files\Npcap\DiagReport.bat file to run DiagReport. It will pop up a text report via Notepad (it's stored in: C:\Program Files\Npcap\DiagReport.txt). Please always submit it to us if you encounter any issues.

For Vista users: DiagReport is a script written by Windows PowerShell, and Vista doesn't have it installed by default. So if you are using Vista, you need to install PowerShell 2.0 (KB968930) on your system. Please download it here for x86 and here for x64. Win7 and later systems have built-in PowerShell support and don't need to do anything about it.

Npcap keeps track of the installation in a log file: C:\Program Files\Npcap\install.log, please submit it together in your report if you encounter issues about the installation (e.g. the installer halts).

Npcap keeps track of the driver installation (aka commands run by NPFInstall.exe) in a log file: C:\Program Files\Npcap\NPFInstall.log, please submit it together in your report if you encounter issues about the driver installation and “Npcap Loopback Adapter”.

There's another system-provided driver installation log in: C:\Windows\INF\setupapi.dev.log. If you encounter errors about the driver/service installation, please copy the Npcap-related lines out and send them together in your report.

If you think the dynamic link library (Packet.dll) doesn't function well, you can refer to Packet.dll's log. It's also stored in Npcap's installation folder: C:\Program Files\Npcap\Packet.log. We don't enable this log feature in regular releases. You have two ways: If you are a Npcap developer, you can build the Packet.sln project with the _DEBUG_TO_FILE macro defined. If you are only a Npcap user, you can download the packet-debug version Npcap from our releases. Currently, the latest packet-debug version is Npcap 0.08 r4. You can also ask me to build a packet-debug version Npcap for a specific version Npcap. I'll be glad to do it. Note, the (Packet.log) file is written in an appending manner. So you may want to delete it after an amount of time, or save your output to another place before it gets too large.

If you think the driver doesn't function well, you can open an Administrator command prompt, enter sc query npcap to query the driver status and net start npcap to start the driver (replace npcap with npf if you installed Npcap in “WinPcap Compatible Mode”). The command output will inform you whether there's an error. If the driver is running well, but the issue still exists, then you need to check the driver's log. Normal Npcap releases don't switch on the driver log function for performance. So you have to install a driver-debug version Npcap. We don't build a driver-debug version for every release. Currently, the latest driver-debug version is Npcap 0.08 r7. If the currently available driver-debug version Npcap doesn't have your issue, you can ask me to build a driver-debug version Npcap for a specific version in mail. I'll be happy to do that. When you have got an appropriate driver-debug version Npcap, you need to use DbgView to read the Windows kernel log (which contains our driver log). You may need to turn on DbgView before installing Npcap, if the error occurs when the driver loads. When done, save the DbgView output to a file and submit it in your report.

If you encountered BSoD when using Npcap, please attach the minidump file (in C:\Windows\Minidump) to your report together with the Npcap version. We may ask you to provide the full dump (C:\Windows\MEMORY.DMP) for further troubleshooting.