npcap-guide.xml

<sect1 id="npcap-users-guide">
  <title>Npcap Users' Guide</title>
  <sect1info>
    <abstract>
      <para>The Users' Guide covers the basics of installing and removing
        Npcap, interactions with WinPcap, frequently asked questions,
        and how to report bugs.</para>
    </abstract>
  </sect1info>

  <para>Because Npcap is a packet capture architecture, not merely a software
    library, some aspects of installation and configuration may fall to the end
    user. This Users' Guide covers the basics of installing, configuring, and
    removing Npcap, as well as how to report bugs.</para>

  <sect2 id="npcap-installation">
    <title>Installation</title>

    <para>
      Npcap is distributed as a signed executable installer, downloadable from
      <ulink url="https://nmap.org/npcap/#download">Nmap.com</ulink>. Major
      versions are backwards-compatible, and users of the free non-commercial
      version are encouraged to upgrade regularly for security and stability
      fixes. Software distributors may have separate requirements for supported
      Npcap versions.  Please refer to
      <ulink url="http://www.npcap.org/#License">the Npcap License</ulink> for
      terms of use and redistribution.</para>

    <para>
      The Npcap installer and uninstaller are easy to use in
      <quote>Graphical Mode</quote> (direct run) and <quote>Silent Mode</quote> (run with
      <option>/S</option> parameter, available only with <ulink url="https://nmap.org/npcap/oem/">Npcap OEM</ulink>).
    </para>

    <sect3 id="npcap-installation-options">
      <title>Installer options</title>
      <para>
        The installer accepts several command-line options that correspond to the
        options presented in the graphical interface (GUI).  The options take the form
        <option>/<replaceable>name</replaceable>=<replaceable>value</replaceable></option>,
        where <replaceable>name</replaceable> is one of
        <option>/npf_startup</option>, <option>/loopback_support</option>,
        <option>/dlt_null</option>, <option>/admin_only</option>,
        <option>/dot11_support</option>, <option>/vlan_support</option>,
        or <option>/winpcap_mode</option>.
      </para>
      <para>The values for these options must be one of:
      </para>
      <itemizedlist>
        <listitem><para><option>yes</option>: select the option</para></listitem>
        <listitem><para><option>no</option>: unselect the option</para></listitem>
        <listitem><para><option>enforced</option>: select the option and make it unchangable in the GUI</para></listitem>
        <listitem><para><option>disabled</option>: unselect the option and make it unchangable in the GUI</para></listitem>
      </itemizedlist>

      <para>There is also one option that does not appear in the GUI, which is
        <option>/disable_restore_point=yes</option>, which will prevent the
        installer from setting a system restore point. Windows may independently
        create a restore point because of the driver installation independent
        from this option.
      </para>

      <para>The destination directory for installation can also be overridden by
        the <option>/D</option> option, with a few restrictions. First, it will
        only affect where Npcap keeps its installation logs and helper utilities.
        The driver and DLLs will always be installed into the appropriate
        directories below <command>%SYSTEMROOT%\System32\</command>. Second, the
        <option>/D</option> must be the last option in the command, and the path
        must not contain quotes. For example, to change the installation directory
        to <filename>C:\Path With Spaces\</filename>, the invocation would be:
        <command>npcap-<replaceable>version</replaceable>.exe /D=C:\Path With Spaces</command>
      </para>

      <para>
        An example of Npcap installer options is:
      </para>

      <para>
        <option>/npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=yes /dot11_support=yes /vlan_support=yes /winpcap_mode=yes</option>
      </para>

      <itemizedlist>
        <listitem><para><option>/npf_startup=yes</option>: Automatically start the Npcap driver at boot time</para></listitem>
        <listitem><para><option>/loopback_support=yes</option>: Support loopback traffic (<quote>Npcap Loopback Adapter</quote> will be created)</para></listitem>
        <listitem><para><option>/dlt_null=no</option>: Use <varname>DLT_EN10MB</varname> (Ethernet) as the
            <quote>Npcap Loopback Adapter</quote>'s link layer protocol instead of the default <varname>DLT_NULL</varname>.
        </para></listitem>
        <listitem><para><option>/admin_only=yes</option>: Restrict Npcap driver's access to Administrators only</para></listitem>
        <listitem><para><option>/dot11_support=yes</option>: Support raw 802.11 traffic (and <quote>Monitor Mode</quote>) for wireless adapters</para></listitem>
        <listitem><para><option>/vlan_support=yes</option>: Support 802.1Q VLAN tag when capturing and sending data</para></listitem>
        <listitem><para><option>/winpcap_mode=yes</option>: Install Npcap in WinPcap API-compatible Mode</para></listitem>
      </itemizedlist>
    </sect3>

    <sect3 id="npcap-installation-uninstall-options">
      <title>Uninstaller options</title>
      <para>
        The uninstaller provided with Npcap also accepts some command-line options.
        The <option>/Q</option> flag means to skip the confirmation page and finish page in the uninstall wizard. So this option is
        only meaningful for <quote>GUI Mode</quote>. The <option>/no_kill</option> controls how the uninstaller handles
        processes that are still using Npcap at the time of uninstall. If <option>/no_kill=yes</option>
        is specified, then Npcap uninstaller will fail if there are still applications using Npcap driver or DLLs.
        If <option>/no_kill=no</option> is specified in silent mode, Npcap uninstaller will immediately terminate any command-line processes that are using
        Npcap (like a Nmap process that is still scanning), and wait for at most 15 seconds to gracefully terminate any GUI processes
        that are using Npcap (like Wireshark UI that is still capturing). <quote>gracefully</quote> means that if you are
        still capturing via Wireshark, Wireshark UI will prompt the user about whether to save the current capture to a pcap.
        So the user have 15 seconds to save his session. Note: although Npcap uninstaller won't terminate Wireshark UI processe
        immediately, the live capture stops immediately. This is because Wireshark UI uses command-line processes named
        <varname>dumpcap.exe</varname> to capture, and that command-line process will be terminated immediately. The default
        value for <option>/no_kill</option> is <option>no</option>, but if the
        graphical interface is used (without <option>/S</option>), the user will be
        prompted for what to do.
      </para>

      <para>
        An example of Npcap uninstaller options is:
      </para>

      <para>
        <option>/S /Q /no_kill=yes</option>
      </para>
    </sect3>

    <sect3 id="npcap-installation-options-disabled">
      <title>Disabled and enforced options for GUI Mode</title>

      <para>
        We may disable or enforce certain options in the installer GUI to make them unselectable. This
        usually means that those options can easily cause compatibility issues and are considered
        not suitable for most users, 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.
      </para>

      <para>
        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 <option>disabled</option> or <option>enforced</option>.
        For example, the following command will start an installer GUI with the
        <option>dlt_null</option> disabled and unselected:
      </para>

      <para>
        <command>npcap-<replaceable>version</replaceable>.exe /dlt_null=disabled</command>
      </para>
    </sect3>

    <sect3 id="npcap-installation-options-gui">
      <title>How to change options for GUI Mode</title>
      <para>
        Default options for Npcap installer GUI can be changed. An example is:
      </para>

      <para>
        <command>npcap-<replaceable>version</replaceable>.exe /npf_startup=yes /loopback_support=yes /dlt_null=yes /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=yes</command>
      </para>

      <para>
        Because most of these are the default values for these options, this example could be even simpler:
      </para>

      <para>
        <command>npcap-<replaceable>version</replaceable>.exe /winpcap_mode=yes</command>
      </para>

      <para>
        Running the installer
        directly without options will see <option>Install Npcap in WinPcap API-compatible Mode</option>
        <emphasis>UNCHECKED</emphasis> by default in the <quote>Installation Options</quote> page.
        However, the above two commands will launch the installer GUI, and in the <quote>Installation Options</quote> page, the
        <option>Install Npcap in WinPcap API-compatible Mode</option> option will be <emphasis>CHECKED</emphasis> by default.
      </para>
    </sect3>

    <sect3 id="npcap-installation-options-silent">
      <title>How to change options for Silent Mode</title>
      <para>
        An example of changing option features for silent installation is:
      </para>

      <para>
        <command>npcap-<replaceable>version</replaceable>.exe /S /admin_only=yes /dot11_support=yes /vlan_support=yes</command>
      </para>

      <itemizedlist>
        <listitem><para>If you doesn't specify a parameter key, it will take the default value.
            This is the same with the GUI.</para></listitem>
        <listitem><para>The keys are <emphasis>case-insensitive</emphasis>.</para></listitem>
        <listitem><para>The values are <emphasis>case-sensitive</emphasis>, only two values are
            permitted: <option>yes</option> or <option>no</option>.</para></listitem>
      </itemizedlist>
    </sect3>

  </sect2>

  <sect2 id="npcap-feature-dot11-wireshark">
    <title>How to use Wireshark to capture raw 802.11 traffic in <quote>Monitor Mode</quote></title>

    <para>
      The latest Wireshark has already integrated the support for Npcap's <quote>Monitor Mode</quote> capture.
      If you want to use Wireshark to capture raw 802.11 traffic in <quote>Monitor Mode</quote>, you need to
      switch on the monitor mode inside the Wireshark UI instead of using <xref linkend="npcap-feature-dot11-wlanhelper" />.
      This is because Wireshark only recognizes the monitor mode set by itself. So when you turn
      on monitor mode outside Wireshark (like in <filename>WlanHelper</filename>), Wireshark will not know the adapter
      has been in monitor mode, and will still try to capture in Ethernet mode, which will get no traffic.
<!-- TODO: Change instructions in other sections to reflect this. Verify that it is correct, first -->
      So after all, the correct steps are:
    </para>

    <itemizedlist>
      <listitem><para>Install latest version Wireshark and latest version Npcap with
          <option>Support raw 802.11 traffic</option> option checked.</para></listitem>

      <listitem><para>Launch Wireshark QT UI (GTK version is similar), go to <quote>Capture options</quote>.
          Then toggle the checkbox in the <quote>Monitor Mode</quote> column of your wireless adapter's row.
          Click the <quote>Start</quote> button. If you see a horizontal line instead of the checkbox,
          then it probably means that your adapter doesn't support monitor mode. You can use the
          <filename>WlanHelper</filename> tool to double-check this fact.</para></listitem>

      <listitem><para>To decrypt <emphasis>encrypted 802.11 data</emphasis>
          packets, you need to specify the decipher key in Wireshark, otherwise
          you will only see 802.11 data packets.</para></listitem>

      <listitem><para>Stop the capture in Wireshark UI when you finishes capturing, the monitor mode
          will be turned off automatically by Npcap.</para></listitem>
    </itemizedlist>
  </sect2>

  <sect2 id="npcap-qa">
    <title>Q &amp; A</title>

    <itemizedlist>
      <listitem><para>Network disconnects after installing Npcap: As Microsoft states
          <ulink role="hidepdf" url="https://support.microsoft.com/en-us/kb/2019184">here</ulink>,
          <emphasis>an optional NDIS light-weight filter (LWF) driver like Npcap could cause
            90-second delay in network availability</emphasis>. Some solutions you could try
          are: 1) wait for 90 seconds; 2) disable and re-enable the adapter icon in
          <command>ncpa.cpl</command>; 3) reboot. If this doesn't work,
          please <ulink role="hidepdf" url="http://issues.nmap.org/new?title=Npcap+Bug+Report">file a bug report</ulink>.
      </para></listitem>
      <listitem><para>Installation fails with error code <varname>0x8004a029</varname>:
          The cause is that you have <quote>reached the maximum number of network filter
            drivers</quote>, see solution
          <ulink role="hidepdf" url="https://social.technet.microsoft.com/Forums/windows/en-US/4deb27fc-33ce-4fc0-a26f-3fec5b57733d/is-there-a-maximum-number-of-network-filter-drivers-in-windows-7?forum=w7itpronetworking">here</ulink>.
      </para></listitem>
      <listitem><para>Npcap Loopback Adapter is missing:
          Npcap Loopback Adapter is actually a wrapper of Microsoft Loopback Adapter.
          Such adapters won't show up in Wireshark if the <varname>Basic Filtering Enging (BFE)</varname>
          service was not running. To fix this issue, you should start this service at <varname>services.msc</varname>
          manually and restart the Npcap service by running <command>net stop npcap</command>
          and <command>net start npcap</command>. See details about this issue
          <ulink role="hidepdf" url="https://github.com/nmap/nmap/issues/802">here</ulink>.
      </para></listitem>

      <listitem><para>Npcap only captures TCP handshake and teardown, but not data packets.
          Some network adapters support offloading of tasks to free up CPU time for
          performance reasons. When this happens, Npcap may not receive all of the
          packets, or may receive them in a different form than is actually sent on the
          wire. To avoid this issue, you may disable TCP Chimney, IP Checksum
          Offloading, and Large Send Offloading in the network adapter properites on
          Windows. See details about this issue in
          <ulink role="hidepdf" url="https://github.com/nmap/nmap/issues/989">issue
            #989</ulink> on our tracker.
      </para></listitem>
    </itemizedlist>
  </sect2>

  <sect2 id="npcap-issues">
    <title>Reporting Bugs</title>

    <para>
      Please report any bugs or issues about Npcap on
      <ulink role="hidepdf" url="http://issues.nmap.org/new?title=Npcap+Bug+Report">the Nmap Project's Issues tracker</ulink>.
      In your report, please provide your <emphasis>DiagReport</emphasis> output, user
      software version (e.g. Nmap, Wireshark), steps to reproduce the problem, and other information
      you think necessary. If your issue occurs only on a particular OS version (e.g. Win10
      1511, 1607), please mention it in the report.
    </para>

    <sect3 id="npcap-issues-diagreport">
      <title>Diagnostic report</title>

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

      <para>
        For Vista users: <filename>DiagReport</filename> is a script written for
        <ulink role="hidepdf" url="https://msdn.microsoft.com/en-us/powershell/mt173057.aspx">Windows PowerShell</ulink>,
        and Vista doesn't have it installed by default. So if you are using Vista,
        you need to install <emphasis>PowerShell 2.0 (KB968930)</emphasis> on your
        system. Please download it <ulink role="hidepdf" url="https://www.microsoft.com/en-hk/download/details.aspx?id=9864">here for x86</ulink>
        and <ulink role="hidepdf" url="https://www.microsoft.com/en-us/download/details.aspx?id=9239">here for x64</ulink>.
        Win7 and later systems have built-in PowerShell support and don't need
        to do anything about it.
      </para>

    </sect3>
    <sect3 id="npcap-issues-installation-log">
      <title>General installation log</title>

      <para>
        Npcap keeps track of the installation in a log file:
        <filename>C:\Program Files\Npcap\install.log</filename>. Please submit it
        together in your report if you encounter issues during the installation
        (e.g. the installer halts).
      </para>
    </sect3>

    <sect3 id="npcap-issues-driver-installation-log">
      <title>Driver installation log</title>

      <para>
        Npcap keeps track of the driver installation (aka commands run by
        <filename>NPFInstall.exe</filename>) in a log file:
        <filename>C:\Program Files\Npcap\NPFInstall.log</filename>, please submit
        it together in your report if you encounter issues during the driver
        installation or problems with the <quote>Npcap Loopback Adapter</quote>.
      </para>

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

    <sect3 id="npcap-issues-packet-log">
      <title>Dynamic link library (DLL) log</title>

      <para>
        For problems with Npcap's regular operation, you may need to obtain a
        debug log from <filename>Packet.dll</filename>.  To do this, you will
        need a debug build of Npcap.  If you are a Npcap developer, you can build
        the <filename>Packet.sln</filename> project with the
        <varname>_DEBUG_TO_FILE</varname> macro defined. If you are an end user,
        you can contact the Npcap development team for the latest Npcap debug
        build.  The debugging process will continue to append to the debug log
        (<filename>C:\Program Files\Npcap\Packet.log</filename>), so you may want
        to delete it after an amount of time, or save your output to another
        place before it gets too large.
      </para>
    </sect3>

    <sect3 id="npcap-issues-driver-log">
      <title>Driver log</title>

      <para>
        If there is an issue with the Npcap driver, you can open an
        <emphasis>Administrator</emphasis> command prompt,  enter <command>sc query
          npcap</command> to query the driver status and <command>net start
          npcap</command> to start the driver (replace
        <replaceable>npcap</replaceable> with <replaceable>npf</replaceable> if you
        installed Npcap in <quote>WinPcap Compatible Mode</quote>).  The command
        output will inform you whether there's an error. If the driver is running
        well, but the issue still exists, then you may need to check the driver's
        log. Normal Npcap releases don't switch on the driver log function for
        performance. Contact the Npcap development team to obtain a driver-debug
        version of the Npcap installer.  When you have got an appropriate
        driver-debug version Npcap, you need to use <ulink role="hidepdf"
          url="https://technet.microsoft.com/en-us/sysinternals/debugview.aspx">DbgView</ulink>
        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.
      </para>
    </sect3>
    <sect3 id="npcap-issues-bsod">
      <title>Blue screen of death (BSoD) dump</title>

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

</sect1>