forked from nmap/npcap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
npcap-guide-wrapper.html
505 lines (501 loc) · 63.3 KB
/
npcap-guide-wrapper.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Npcap Users' Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /></head><body><div class="article"><div class="titlepage"><div><div><h1 class="title"><a id="idm45862732447264"></a>Npcap Users' Guide</h1></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#npcap-overview">Npcap: Nmap Project's packet sniffing library for Windows, based on WinPcap/Libpcap improved with NDIS 6 and LWF</a></span></dt><dt><span class="sect1"><a href="#ncat-features">Features</a></span></dt><dt><span class="sect1"><a href="#npcap-architecture">Architecture</a></span></dt><dt><span class="sect1"><a href="#npcap-detect">How to detect what version Npcap/WinPcap you are using?</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-detect-version">Npcap version</a></span></dt><dt><span class="sect2"><a href="#npcap-detect-install-time">Install-time detection</a></span></dt><dt><span class="sect2"><a href="#npcap-detect-run-time">Run-time detection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-feature-native">For software that want to use Npcap first when Npcap and WinPcap coexist</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-feature-native-dll">DLL loading</a></span></dt><dt><span class="sect2"><a href="#npcap-feature-native-servicename">Service name</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-feature-loopback">For software that use Npcap loopback feature</a></span></dt><dt><span class="sect1"><a href="#npcap-feature-dot11">For software that use Npcap raw 802.11 feature</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-feature-dot11-steps">Steps</a></span></dt><dt><span class="sect2"><a href="#npcap-feature-dot11-tips">Tips</a></span></dt><dt><span class="sect2"><a href="#npcap-feature-dot11-terminology">Terminology</a></span></dt><dt><span class="sect2"><a href="#npcap-feature-dot11-wlanhelper">WlanHelper</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-get-code">Get the code</a></span></dt><dt><span class="sect1"><a href="#npcap-build">Build</a></span></dt><dt><span class="sect1"><a href="#npcap-packaging">Packaging</a></span></dt><dt><span class="sect1"><a href="#npcap-symbols">Generating debug symbols (optional)</a></span></dt><dt><span class="sect1"><a href="#npcap-redistribution">Redistribution</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-redistribution-options">Installation options</a></span></dt><dt><span class="sect2"><a href="#npcap-redistribution-options-gui">Disabled options for GUI Mode</a></span></dt><dt><span class="sect2"><a href="#npcap-redistribution-options-gui">How to change default options for GUI Mode</a></span></dt><dt><span class="sect2"><a href="#npcap-redistribution-options-silent">How to change options for Silent Mode</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-download">Downloads</a></span></dt><dt><span class="sect1"><a href="#npcap-development">Development</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-sdk">SDK</a></span></dt><dt><span class="sect2"><a href="#npcap-documentation">Documentation</a></span></dt><dt><span class="sect2"><a href="#npcap-examples">Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-incompatible">The list of incompatible software</a></span></dt><dt><span class="sect1"><a href="#npcap-qa">Q & A</a></span></dt><dt><span class="sect1"><a href="#npcap-license">License</a></span></dt><dt><span class="sect1"><a href="#npcap-issues">Bug report</a></span></dt><dd><dl><dt><span class="sect2"><a href="#npcap-issues-installation-log">Installation log</a></span></dt><dt><span class="sect2"><a href="#npcap-issues-packet-log">Dynamic link library (DLL) log</a></span></dt><dt><span class="sect2"><a href="#npcap-issues-driver-log">Driver log</a></span></dt><dt><span class="sect2"><a href="#npcap-issues-bsod">Blue screen of death (BSoD) dump</a></span></dt></dl></dd><dt><span class="sect1"><a href="#npcap-list">Contact</a></span></dt></dl></div><a id="npcap-indexterm" class="indexterm"></a><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-overview"></a>Npcap: Nmap Project's packet sniffing library for Windows, based on WinPcap/Libpcap improved with NDIS 6 and LWF</h2></div></div></div><p>
Npcap is an update of <a class="ulink" href="http://www.winpcap.org/" target="_top">WinPcap</a>
to <a class="ulink" href="https://msdn.microsoft.com/en-us/library/windows/hardware/ff565492(v=vs.85).aspx" target="_top">NDIS 6 Light-Weight Filter (LWF)</a> technique.
It supports <span class="command"><strong>Windows Vista, 7, 8 and 10</strong></span>. It is sponsored
by the <a class="ulink" href="http://nmap.org/" target="_top">Nmap Project</a>
and developed by <a class="ulink" href="http://www.veotax.com/" target="_top">Yang Luo</a>
under <a class="ulink" href="https://www.google-melange.com/gsoc/project/details/google/gsoc2013/hsluoyz/5727390428823552" target="_top">Google Summer of Code 2013</a> and
<a class="ulink" href="https://www.google-melange.com/gsoc/project/details/google/gsoc2015/hsluoyz/5723971634855936" target="_top">2015</a>.
It also received many helpful tests from <a class="ulink" href="https://www.wireshark.org/" target="_top">Wireshark</a>
and <a class="ulink" href="http://www.netscantools.com/" target="_top">NetScanTools</a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ncat-features"></a>Features</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>NDIS 6 Support</em></span>: Npcap makes use of new LWF driver in
Windows Vista and later (the legacy driver is used on XP). It's faster
than the legacy <a class="ulink" href="https://msdn.microsoft.com/en-us/library/windows/hardware/ff557012(v=vs.85).aspx" target="_top">NDIS 5 Intermediate</a>
technique. One reason is that
packet data stucture has changed (from <code class="varname">NDIS_PACKET</code> to <code class="varname">NET_BUFFER_LIST</code>)
since Vista and NDIS 5 needs to handle extra packet structure conversion.</p></li><li class="listitem"><p><span class="emphasis"><em><span class="quote">“<span class="quote">Admin-only Mode</span>”</span> Support</em></span>: Npcap supports to restrict its
use to Administrators for safety purpose. If Npcap is installed with
the option <span class="quote">“<span class="quote">Restrict Npcap driver's access to Administrators only</span>”</span> checked,
when a non-Admin user tries to start a user software (Nmap, Wireshark, etc),
the <a class="ulink" href="http://windows.microsoft.com/en-us/windows/what-is-user-account-control#1TC=windows-7" target="_top">User Account Control (UAC)</a>
dialog will prompt asking for Administrator privilege. Only when the end
user chooses Yes, the driver can be accessed. This is similar to UNIX
where you need root access to capture packets.</p></li><li class="listitem"><p><span class="emphasis"><em><span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span>
Support</em></span>: <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> is used to decide whether Npcap should coexist With WinPcap or
be compatible with WinPcap. With <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> OFF, Npcap
can coexist with WinPcap and share the DLL binary interface with WinPcap.
So the applications unaware of Npcap <span class="emphasis"><em>SHOULD</em></span> be able to use Npcap
automatically if WinPcap is unavailable. The applications who knows
Npcap's existence can choose to use Npcap or WinPcap first. The key
about which is loaded first is DLL Search Path. With <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> OFF, Npcap installs its DLLs into <code class="filename">C:\Windows\System32\Npcap\</code>
instead of WinPcap's <code class="filename">C:\Windows\System32\</code>. So applications who want
to load Npcap first must make <code class="filename">C:\Windows\System32\Npcap\</code> precedent
to other paths in ways such as calling <code class="function">SetDllDirectory</code>, etc. Another
point is Npcap uses service name <span class="quote">“<span class="quote">npcap</span>”</span> instead of WinPcap's <span class="quote">“<span class="quote">npf</span>”</span> with
<span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> OFF. So applications using <span class="command"><strong>net start npf</strong></span>
for starting service must use <span class="command"><strong>net start npcap</strong></span> instead. If you want
100% compatibility with WinPcap, you should install Npcap choosing
<span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> (<span class="quote">“<span class="quote">Install Npcap in WinPcap API-compatible Mode</span>”</span>).
In this mode, Npcap will install its Dlls in WinPcap's <code class="filename">C:\Windows\System32\</code>
and use the <span class="quote">“<span class="quote">npf</span>”</span> service name. It's notable that before installing in
this mode, you must uninstall WinPcap first (the installer wizard will
prompt you that).</p></li><li class="listitem"><p><span class="emphasis"><em>Loopback Packets Capture Support</em></span>: Now Npcap is able to
see Windows loopback packets using <a class="ulink" href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa366510(v=vs.85).aspx" target="_top">Windows Filtering Platform (WFP)</a>
technique. After installation, Npcap will create an adapter named <span class="quote">“<span class="quote">Npcap
Loopback Adapter</span>”</span> for you. If you are a Wireshark user, choose this adapter
to capture, you will see all loopback traffic the same way as other
non-loopback adapters. Try it by typing in commands like <span class="command"><strong>ping 127.0.0.1</strong></span>
(IPv4) or <span class="command"><strong>ping ::1</strong></span> (IPv6).</p></li><li class="listitem"><p><span class="emphasis"><em>Loopback Packets Send Support</em></span>: Besides loopback packets
capturing, Npcap can also send out loopback packets based on
<a class="ulink" href="https://msdn.microsoft.com/en-us/library/windows/hardware/ff556958(v=vs.85).aspx" target="_top">Winsock Kernel (WSK)</a>
technique. A user software (e.g. Nmap) can just send packets
out using <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> like other adapters.
<span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span>
will automatically remove the packet's Ethernet header and
inject the payload into Windows TCP/IP stack, so this kind of loopback
packet never go out of the machine.</p></li><li class="listitem"><p><span class="emphasis"><em>Raw 802.11 Packets Capture Support</em></span>: Npcap is able to see
<span class="emphasis"><em>802.11</em></span> packets instead of <span class="emphasis"><em>fake Ethernet</em></span> packets on ordinary wireless
adapters. You need to select the <code class="option">Support raw 802.11 traffic (and monitor
mode) for wireless adapters</code> option in the installation wizard to enable
this feature. When your adapter is in <span class="quote">“<span class="quote">Monitor Mode</span>”</span>, Npcap will supply all
<span class="emphasis"><em>802.11 data + control + management</em></span> packets with radiotap headers. When
your adapter is in <span class="quote">“<span class="quote">Managed Mode</span>”</span>, Npcap will only supply <span class="emphasis"><em>802.11 data</em></span>
packets with radiotap headers. Moreover, Npcap provides the <code class="filename">WlanHelper.exe</code>
tool to help you switch to <span class="quote">“<span class="quote">Monitor Mode</span>”</span> on Windows. See more details
about this feature in section <span class="quote">“<span class="quote">For software that use Npcap raw 802.11
feature</span>”</span>. See more details about radiotap here:
<a class="ulink" href="http://www.radiotap.org/" target="_top">http://www.radiotap.org/</a></p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-architecture"></a>Architecture</h2></div></div></div><p>
Npcap tries to <span class="emphasis"><em>keep the original WinPcap architecture as much as possible</em></span>.
As the table shows, you will find it very similar with WinPcap.
</p><div class="table"><a id="idm45862732527568"></a><p class="title"><strong>Table 1. Npcap Architecture</strong></p><div class="table-contents"><table summary="Npcap Architecture" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th align="left">Binary</th><th align="left">Source</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left">wpcap.dll</td><td align="left">wpcap</td><td align="left">the libpcap API, added "loopback support" to original WinPcap</td></tr><tr><td align="left">Packet.dll</td><td align="left">packetWin7\Dll</td><td align="left">the Packet API for Windows, added "Admin-only Mode" to original WinPcap</td></tr><tr><td align="left"><em class="replaceable"><code>npf</code></em>.sys (or <em class="replaceable"><code>npcap</code></em>.sys)</td><td align="left">packetWin7\npf</td><td align="left">the driver, ported from NDIS 5 to NDIS 6, we support two names: <em class="replaceable"><code>npf</code></em> or <em class="replaceable"><code>npcap</code></em>, based on whether Npcap is installed in <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span></td></tr><tr><td align="left">NPFInstall.exe</td><td align="left">packetWin7\NPFInstall</td><td align="left">a LWF & WFP driver installation tool we added to Npcap</td></tr><tr><td align="left">NpcapHelper.exe</td><td align="left">packetWin7\Helper</td><td align="left">the helper program for <span class="quote">“<span class="quote">Admin-only Mode</span>”</span>, will run under <span class="emphasis"><em>Administrator</em></span> rights</td></tr><tr><td align="left">WlanHelper.exe</td><td align="left">packetWin7\WlanHelper</td><td align="left">a tool is used to set/get the operation mode (like <span class="quote">“<span class="quote">Monitor Mode</span>”</span>) for a wireless adapter, will run under <span class="emphasis"><em>Administrator</em></span> rights</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-detect"></a>How to detect what version Npcap/WinPcap you are using?</h2></div></div></div><p>
Sometimes, our user software needs to detect the existence of Npcap/WinPcap at install-time or run-time. Although Npcap's GUI installer has the ability to handle this, you may want to handle it by yourself in some conditions, like you run Npcap installer in silent-mode.
The run-time detection is even more useful. Your software probably has some functions that rely on Npcap's particular features (like the loopback interface). You need to know if you are running on top of Npcap or the legacy WinPcap to control whether to switch your functions on.
Fortunately, Npcap provides you some methods to detect Npcap/WinPcap at install-time and run-time.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-detect-version"></a>Npcap version</h3></div></div></div><p>
You may notice that Npcap has several version strings. The installer name can be something
like <code class="filename">npcap-0.07-r5.exe</code>. <span class="quote">“<span class="quote">0.07</span>”</span> is the version number, and
<span class="quote">“<span class="quote">r5</span>”</span> is the revision number. We use a version number less than <span class="quote">“<span class="quote">1.00</span>”</span>
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 <span class="quote">“<span class="quote">4.1.3</span>”</span>,
which is more Wireshark-like. One thing you need to know here is that Npcap starts the
development based on the latest WinPcap <span class="quote">“<span class="quote">4.1.3</span>”</span>. So any Npcap release is more
<span class="emphasis"><em>advanced</em></span> than WinPcap's latest release. Another thing needs to notice is
that, the <span class="quote">“<span class="quote">0.07</span>”</span> version number can be obtained from the
<code class="function">pcap_lib_version</code> function. The <span class="quote">“<span class="quote">r5</span>”</span> revision number
<span class="emphasis"><em>only</em></span> 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.
</p><p>
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
<span class="quote">“<span class="quote">5.0.7.424</span>”</span>. <span class="quote">“<span class="quote">5</span>”</span> here is used to advance Npcap version than the legacy
WinPcap's e-version <span class="quote">“<span class="quote">4.1.0.2980</span>”</span> because <span class="quote">“<span class="quote">5.0.7.424</span>”</span> is larger than
<span class="quote">“<span class="quote">4.1.0.2980</span>”</span>. 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. <span class="quote">“<span class="quote">0</span>”</span> and <span class="quote">“<span class="quote">7</span>”</span>
in Npcap's e-version corresponds to Npcap's version <span class="quote">“<span class="quote">0.07</span>”</span>. <span class="quote">“<span class="quote">424</span>”</span> means
that this release is built at date <span class="quote">“<span class="quote">4.24</span>”</span> (aka 24th, April). When Npcap version jumps
to a new version (like from <span class="quote">“<span class="quote">0.06</span>”</span> to <span class="quote">“<span class="quote">0.07</span>”</span>), the e-version will also
change (like from <span class="quote">“<span class="quote">0.6.0.301</span>”</span> to <span class="quote">“<span class="quote">0.7.0.424</span>”</span>). A revision update won't
cause a change of version or e-version.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-detect-install-time"></a>Install-time detection</h3></div></div></div><p>
You can check the existence of <code class="filename">C:\Program Files\Npcap\NPFInstall.exe</code> to
detect Npcap's existence. If Npcap exists, you can check the file version of
<code class="filename">C:\Program Files\Npcap\NPFInstall.exe</code> to detect Npcap e-version. The
e-version also gives you the version. The NSIS code is shown below. <code class="varname">$inst_ver</code>
is an e-version string like <span class="quote">“<span class="quote">5.0.7.424</span>”</span>
</p><pre class="screen">
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"
</pre><p>
You can check the installation options of an already installed Npcap by reading the registry
key: <code class="filename">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npf</code>
(WinPcap compatible mode) or <code class="filename">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\npcap</code>
(Non-WinPcap compatible mode). the entries like <code class="filename">AdminOnly</code>,
<code class="filename">Loopback</code>, <code class="filename">DltNull</code>,<code class="filename">Dot11Support</code>,
<code class="filename">VlanSupport</code>, <code class="filename">WinPcapCompatible</code>, etc. show the installation options.
<code class="filename">Loopback</code> is <code class="code">REG_SZ</code> type. A non-NULL value indicates the option is
<span class="emphasis"><em>CHECKED</em></span>. All other entries are <code class="code">REG_DWORD</code> type. A 0x00000001 value
indicates the option is <span class="emphasis"><em>CHECKED</em></span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-detect-run-time"></a>Run-time detection</h3></div></div></div><p>
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 <code class="filename">wpcap.dll</code> 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 <code class="function">pcap_lib_version</code> to get the Npcap/WinPcap version string.
</p><pre class="screen">
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"
</pre><p>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:
<code class="filename">HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Npcap\WinPcapCompatible</code> for x64
systems (or <code class="filename">HKEY_LOCAL_MACHINE\SOFTWARE\Npcap\WinPcapCompatible</code> for x86
systems). If it's 1, it means Npcap is installed in <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span>. In this mode both
<code class="varname">npcap</code> and <code class="varname">npf</code> services (drivers) are installed. If
the key value is 0, it means Npcap is installed in <span class="quote">“<span class="quote">Non-WinPcap Compatible Mode</span>”</span>.
In this mode only <code class="varname">npcap</code> service (driver) is installed. We
<span class="emphasis"><em>recommend</em></span> our users to use the <code class="varname">npcap</code> service instead
of <code class="varname">npf</code>. Given that <code class="varname">npcap</code> service is always installed
in both modes, a good practice is just trying the <code class="varname">npcap</code> service first.
If it fails, then try the <code class="varname">npf</code> service. This is also what most of our users
do in their software based on our investigation. A code sample from Nmap is
<a class="ulink" href="https://github.com/nmap/nmap/blob/8c8e4a08c6c6b7abd2343e5921aafb6077bdb257/mswin32/winfix.cc#L322-L328" target="_top">here</a>.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-feature-native"></a>For software that want to use Npcap first when Npcap and WinPcap coexist</h2></div></div></div><p>
Prerequisite: Uncheck the <code class="option">Install Npcap in WinPcap API-compatible Mode</code> option at
install-time (which is by default).
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-native-dll"></a>DLL loading</h3></div></div></div><p>Npcap installs its DLLs into <code class="filename">C:\Windows\System32\Npcap\</code>
instead of WinPcap's <code class="filename">C:\Windows\System32\</code>. Based on the design
of <a class="ulink" href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms686203(v=vs.85).aspx" target="_top">DLL search path</a>,
your application will use WinPcap first by default when Npcap and WinPcap coexist,
as <code class="filename">C:\Windows\System32\</code> is prior to <code class="filename">C:\Windows\System32\Npcap\</code>.
So when Npcap and WinPcap coexist, an application that want to use Npcap instead
of WinPcap must make <code class="filename">C:\Windows\System32\Npcap\</code> precedent to the
<code class="filename">C:\Windows\System32\</code> 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
(<code class="filename">wpcap.dll</code>).</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="npcap-feature-native-dll-implicitly"></a>If the application <span class="emphasis"><em>implicitly</em></span> link <code class="filename">wpcap.dll</code>:</h4></div></div></div><p>Implicitly linking means that either you specified <code class="filename">wpcap.lib</code>
in your <code class="option">Project Properties</code> -> <code class="option">Configuration Properties</code>
-> <code class="option">Linker</code> -> <code class="option">Input</code> -> <code class="option">Additional Dependencies</code> in Visual Studio,
or specified <code class="code">#pragma comment(linker, "wpcap.lib")</code> in your code.</p><p>You need to do the following two steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Specify <code class="filename">wpcap.dll</code> as a delay-loaded DLL: In
Visual Studio, open the <code class="option">Project Properties</code> window. Go to:
<code class="option">Configuration Properties</code> -> <code class="option">Linker</code> -> <code class="option">Input</code>
-> <code class="option">Delay Loaded Dlls</code>. Enter <code class="filename">wpcap.dll</code>
in that option.</p></li><li class="listitem"><p>Before calling any <code class="filename">wpcap.dll</code> functions,
call <code class="function">SetDllDirectory</code> to add <code class="filename">C:\Windows\System32\Npcap\</code>
to DLL search path.</p></li></ul></div><p><a class="ulink" href="https://github.com/hsluoyz/WinDump/" target="_top">Here</a>
is an example called WinDump, it's a simple packet capture tool using Npcap/WinPcap.
And <a class="ulink" href="https://github.com/hsluoyz/WinDump/commit/dffe2eaa520fc3b449ec0a90dcfa24f96359bbfa" target="_top">this commit</a>
makes it able to use Npcap first when Npcap and WinPcap coexist.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="npcap-feature-native-dll-explicitly"></a>If the application <span class="emphasis"><em>explicitly</em></span> link <code class="filename">wpcap.dll</code>:</h4></div></div></div><p>Explicitly linking means that you exlicitly called <code class="function">LoadLibrary</code>
to load <code class="filename">wpcap.dll</code> and called <code class="function">GetProcAddress</code> to get the
function pointers.</p><p>You need to do the following one step:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Before calling <code class="function">LoadLibrary</code> to load <code class="filename">wpcap.dll</code>,
call <code class="function">SetDllDirectory</code> to add <code class="filename">C:\Windows\System32\Npcap\</code>
to DLL search path.</p></li></ul></div><p>The function <code class="function">init_npcap_dll_path</code> is provided in the following example:
<a class="ulink" href="https://github.com/hsluoyz/WinDump/commit/dffe2eaa520fc3b449ec0a90dcfa24f96359bbfa" target="_top">WinDump</a></p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-native-servicename"></a>Service name</h3></div></div></div><p>Npcap uses service name <span class="quote">“<span class="quote">npcap</span>”</span> instead of WinPcap's <span class="quote">“<span class="quote">npf</span>”</span> with
<span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span> OFF. So applications using <span class="command"><strong>net start npf</strong></span>
for starting service must change to this: run <span class="command"><strong>net start npcap</strong></span> first, if it
fails, then try <span class="command"><strong>net start npf</strong></span>.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-feature-loopback"></a>For software that use Npcap loopback feature</h2></div></div></div><p>
Prerequisite: Check the <code class="option">Support loopback traffic ("Npcap Loopback Adapter" will be created)</code> option at install-time.
</p><p>
Npcap's loopback adapter device is based on <span class="quote">“<span class="quote">Microsoft KM-TEST Loopback Adapter</span>”</span>
(Win8 and Win10) or <span class="quote">“<span class="quote">Microsoft Loopback Adapter</span>”</span> (Vista, Win7). It is an Ethernet
adapter, and Npcap has changed its behavior and rename it to <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span>,
to make it see the real loopback traffic only. The traffic captured by original WinPcap will not appear here.
</p><p>
The IP address of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> is usually like 169.254.x.x. However,
this IP is totally meaningless. Software using Npcap should regard this interface's IP address
as 127.0.0.1 (IPv4) and ::1 (IPv6). This work can't be done by Npcap because Windows forbids
any IP address to be configured as 127.0.0.1 or ::1 as they're reserved.
</p><p>
The MAC address of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> is usually like 02:00:4C:4F:4F:50. However,
this address is meaningless too. Software using Npcap should think this interface doesn't own a
MAC address, as the loopback traffic never goes to link layer. For software using Npcap to
capture loopback traffic, the MAC addresses in captured data will be all zeros (aka 00:00:00:00:00:00).
For software using Npcap to send loopback traffic, any MAC addresses can be specified as they
will be ignored. But notice that ether_type in Ethernet header should be set correctly. Only <code class="option">IPv4</code>
and <code class="option">IPv6</code> are accepted. Other values like <code class="option">ARP</code> will be ignored. (You don't need an ARP request for
loopback interface)
</p><p>
The MTU of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> is hard-coded to 65536 by Npcap. Software
using Npcap should get this value automatically and no special handling is needed. This value is
determined personally by me and doesn't mean Windows loopback stack can only support packet size
as large as 65536. So don't feel weird if you have captured packets whose size are larger than it.
</p><p>
Don't try to make OID requests to <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> except
<code class="varname">OID_GEN_MAXIMUM_TOTAL_SIZE</code> (MTU). Those requests will still succeed like
other adapters do, but they only make sense for NDIS adapters and Npcap doesn't even use the
NDIS way to handle the loopback traffic. The only handled OID request by Npcap is
<code class="varname">OID_GEN_MAXIMUM_TOTAL_SIZE</code>. If you query its value, you will always get
65550 (65536 + 14). If you try to set its value, the operation will always fail.
</p><p>
To conclude, a software that wants to support Npcap loopback feature should do these steps:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Detect Npcap Loopback Adapter's presence, by reading registry value Loopback
at key <code class="filename">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<em class="replaceable"><code>npf</code></em></code>
(or <em class="replaceable"><code>npcap</code></em> if you installed Npcap With <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span>
OFF). If <code class="filename">Loopback value</code> exsits, it means <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> is OK.
Then perform the following steps.</p></li><li class="listitem"><p>Treat the IP address of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> as 127.0.0.1 (IPv4) and ::1 (IPv6).</p></li><li class="listitem"><p>Treat the MAC address of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> as 00:00:00:00:00:00.</p></li><li class="listitem"><p>If you use IP Helper API to get adapter list, you will get an interface named
like <span class="quote">“<span class="quote">Loopback Pseudo-Interface 1</span>”</span>. This interface is a DUMMY interface by Microsoft
and can't be seen in NDIS layer. And it also takes the 127.0.0.1/::1 IP address. A good practice
for software is merging the entry of <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> and the entry of
<span class="quote">“<span class="quote">Loopback Pseudo-Interface 1</span>”</span> into one entry, like what I have implemented for Nmap (see the
<span class="quote">“<span class="quote">Other code (for developers)</span>”</span> part).</p></li><li class="listitem"><p>Don't make use of OID requests for <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span>
except <code class="varname">OID_GEN_MAXIMUM_TOTAL_SIZE</code> requests.</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-feature-dot11"></a>For software that use Npcap raw 802.11 feature</h2></div></div></div><p>
Prerequisite: Check the <code class="option">Support raw 802.11 traffic (and monitor mode) for wireless adapters</code> option at install-time.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-dot11-steps"></a>Steps</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Install the latest version Npcap with the
<code class="option">Support raw 802.11 traffic (and monitor mode) for wireless adapters</code> option
checked in the installation wizard. With this option checked, Npcap will see packets with
<span class="emphasis"><em>Radiotap + 802.11</em></span> headers for wireless adapters. Otherwise, Npcap
will see packets with <span class="emphasis"><em>fake Ethernet</em></span> headers for wireless adapters.</p></li><li class="listitem"><p>Run <code class="filename">WlanHelper.exe</code> with <span class="emphasis"><em>Administrator privilege</em></span>. Type in
the index of your wireless adapter (usually <span class="keycap"><strong>Enter</strong></span>) and press <span class="keycap"><strong>Enter</strong></span>.
Then type in <span class="keycap"><strong>Enter</strong></span> and press <span class="keycap"><strong>Enter</strong></span> to switch on the <span class="quote">“<span class="quote">Monitor Mode</span>”</span>.
<code class="filename">WlanHelper.exe</code> also supports parameters to be used in an API manner, run
<span class="command"><strong>WlanHelper.exe -h</strong></span> for details.</p></li><li class="listitem"><p>An example: launch Wireshark and capture on the wireless adapter, you will
see all 802.11 packets (<span class="emphasis"><em>data + control + management</em></span>). Here you should
make your software interact with Npcap using the WinPcap API (open the adapter, read packets,
send packets, etc).</p></li><li class="listitem"><p>If you need to return to <span class="quote">“<span class="quote">Managed Mode</span>”</span>, run <span class="command"><strong>WlanHelper.exe</strong></span>
again and input the index of the adapter, then type in <span class="keycap"><strong>Enter</strong></span> and press
<span class="keycap"><strong>Enter</strong></span> to switch off the <span class="quote">“<span class="quote">Monitor Mode</span>”</span>.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-dot11-tips"></a>Tips</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>You need to use <code class="filename">WlanHelper.exe</code> tool to switch on
the <span class="quote">“<span class="quote">Monitor Mode</span>”</span> in order to see <span class="emphasis"><em>802.11 control and management</em></span>
packets in Wireshark (also <span class="emphasis"><em>encrypted 802.11 data</em></span> packets, you need
to specify the decipher key in Wireshark in order to decrypt those packets), otherwise you will
only see 802.11 data packets.</p></li><li class="listitem"><p>Switching on the <span class="quote">“<span class="quote">Monitor Mode</span>”</span> will disconnect your wireless
network from the AP, you can switch back to <span class="quote">“<span class="quote">Managed Mode</span>”</span> using the same
<code class="filename">WlanHelper.exe</code> tool.</p></li><li class="listitem"><p>The <code class="filename">WlanHelper.exe</code> tool automatically installed to your
system path after installing Npcap.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-dot11-terminology"></a>Terminology</h3></div></div></div><p>
<span class="quote">“<span class="quote">Managed Mode</span>”</span> (for Linux) = <span class="quote">“<span class="quote">Extensible Station Mode</span>”</span> (aka <span class="quote">“<span class="quote">ExtSTA</span>”</span>, for Windows)
</p><p>
<span class="quote">“<span class="quote">Monitor Mode</span>”</span> (for Linux) = <span class="quote">“<span class="quote">Network Monitor Mode</span>”</span> (aka <span class="quote">“<span class="quote">NetMon</span>”</span>, for Windows)
</p><p>
<span class="quote">“<span class="quote">Master Mode</span>”</span> (for Linux) = <span class="quote">“<span class="quote">Extensible Access Point</span>”</span> (aka <span class="quote">“<span class="quote">ExtAP</span>”</span>, for Windows)
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-feature-dot11-wlanhelper"></a>WlanHelper</h3></div></div></div><p>
WlanHelper is used to set/get the operation mode (like <span class="quote">“<span class="quote">Monitor Mode</span>”</span>) for a wireless adapter on Windows.
WlanHelper tries to follow the grammar of <code class="filename">iwconfig</code>, a wireless management tool
for Linux. So if you rename <code class="filename">WlanHelper.exe</code> to <code class="filename">iwconfig.exe</code>,
your command lines for WlanHelper will be exactly the same with the iwconfig tool.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="npcap-feature-dot11-wlanhelper-usage"></a>WlanHelper's Usage</h4></div></div></div><p>
Note: <span class="command"><strong>WlanHelper</strong></span> must run under <span class="emphasis"><em>Administrator privilege</em></span>.
</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="npcap-feature-dot11-wlanhelper-usage-interactive"></a>Interactive way</h5></div></div></div><p>
Run <span class="command"><strong>WlanHelper</strong></span> without parameters.
</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="npcap-feature-dot11-wlanhelper-usage-api"></a>Command-line API way</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Run <span class="command"><strong>netsh wlan show interfaces</strong></span>, get the <code class="option">Name</code> or <code class="option">GUID</code> for the interface.</p></li><li class="listitem"><p>Run <span class="command"><strong>WlanHelper -h</strong></span> to see the man page.</p></li></ul></div><div class="example"><a id="npcap-ex-wlanhelper-man"></a><p class="title"><strong>Example 1. WlanHelper Man</strong></p><div class="example-contents"><pre class="screen">
C:\> <strong class="userinput"><code>WlanHelper.exe</code></strong>
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
</pre></div></div><br class="example-break" /><p>
An example:
</p><div class="example"><a id="npcap-ex-wlanhelper-api"></a><p class="title"><strong>Example 2. WlanHelper API Usage</strong></p><div class="example-contents"><pre class="screen">
C:\> <strong class="userinput"><code>netsh wlan show interfaces</code></strong>
There is 1 interface on the system:
Name : <em class="replaceable"><code>Wi-Fi</code></em>
Description : Qualcomm Atheros AR9485WB-EG Wireless Network Adapter
GUID : <em class="replaceable"><code>42dfd47a-2764-43ac-b58e-3df569c447da</code></em>
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:\> <strong class="userinput"><code>WlanHelper.exe <em class="replaceable"><code>wi-fi</code></em> mode</code></strong>
managed
C:\> <strong class="userinput"><code>WlanHelper.exe <em class="replaceable"><code>wi-fi</code></em> mode monitor</code></strong>
Success
C:\> <strong class="userinput"><code>WlanHelper.exe <em class="replaceable"><code>wi-fi</code></em> mode </code></strong>
monitor
C:\> <strong class="userinput"><code>WlanHelper.exe <em class="replaceable"><code>wi-fi</code></em> mode managed</code></strong>
Success
C:\> <strong class="userinput"><code>WlanHelper.exe <em class="replaceable"><code>wi-fi</code></em> mode</code></strong>
managed
</pre></div></div><br class="example-break" /></div></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-get-code"></a>Get the code</h2></div></div></div><p>
Run <span class="command"><strong>git clone https://github.com/nmap/npcap</strong></span>: pull this repo. This repo contains
<a class="ulink" href="https://github.com/the-tcpdump-group/libpcap" target="_top">libpcap</a> as a
submodule, so make sure that you have also pulled all the submodules.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-build"></a>Build</h2></div></div></div><p>
Run <span class="command"><strong>installer\Build.bat</strong></span>: build all DLLs and the driver. The DLLs need to be built
using Visual Studio 2013. And the driver needs to be built using Visual Studio 2015 with Windows SDK
10 10586 & Windows Driver Kit 10 10586. The build of <code class="filename">wpcap.dll</code> also requires
to install <a class="ulink" href="https://sourceforge.net/projects/winflexbison/" target="_top">Win flex-bison</a>.
Please unzip the downloaded package and add the directory to the <code class="filename">PATH</code>
environment variable.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-packaging"></a>Packaging</h2></div></div></div><p>
Run <span class="command"><strong>installer\Deploy.bat</strong></span>: copy the files from build directories to
deployment directories and sign the files. Generate an installer named
<code class="filename">npcap-%VERSION%.exe</code> using
<a class="ulink" href="http://nsis.sourceforge.net/Main_Page" target="_top">NSIS 2.51</a> with
the <a class="ulink" href="http://nsis.sourceforge.net/Special_Builds#Advanced_logging" target="_top">advanced logging special build</a>
and <a class="ulink" href="https://github.com/hsluoyz/SysRestore" target="_top">SysRestore
plug-in (special build for Npcap)</a> and sign the installer.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-symbols"></a>Generating debug symbols (optional)</h2></div></div></div><p>
Run <span class="command"><strong>installer\Deploy_Symbols.bat</strong></span>: copy the debug symbol files (.PDB)
from build directories to deployment directories and package them into a zip file named
<code class="filename">npcap-<VERSION>-DebugSymbols.zip</code> using
<a class="ulink" href="http://www.7-zip.org/" target="_top">7-Zip</a>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-redistribution"></a>Redistribution</h2></div></div></div><p>
(You need to first notice our <a class="ulink" href="http://www.npcap.org/" target="_top">LICENSE</a> before distributing Npcap)
</p><p>
The Npcap installer is friendly for redistribution by supporting two installation
ways: <span class="quote">“<span class="quote">GUI Mode</span>”</span> (direct run) and <span class="quote">“<span class="quote">Silent Mode</span>”</span> (run with
<code class="option">/s</code> paramter).
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-redistribution-options"></a>Installation options</h3></div></div></div><p>
The current Npcap installation options by default are (for both <span class="quote">“<span class="quote">GUI Mode</span>”</span> and <span class="quote">“<span class="quote">Silent Mode</span>”</span>):
</p><p>
<code class="option">/npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=no</code>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="option">/npf_startup=yes</code>: Automatically start the Npcap driver at boot time</p></li><li class="listitem"><p><code class="option">/loopback_support=yes</code>: Support loopback traffic (<span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span> will be created)</p></li><li class="listitem"><p><code class="option">/dlt_null=yes</code>: Use <code class="varname">DLT_NULL</code> as the loopback interface' link layer
protocol instead of <code class="varname">DLT_EN10MB</code>, so when capturing on <span class="quote">“<span class="quote">Npcap Loopback Adapter</span>”</span>,
the received packets will have <a class="ulink" href="http://www.tcpdump.org/linktypes.html" target="_top">DLT_NULL</a>
header instead of Ethernet header. Notice: many softwares on Windows still only support the Ethernet header,
so don't enable this option if you have no idea whether your software supports it or not</p></li><li class="listitem"><p><code class="option">/admin_only=yes</code>: Restrict Npcap driver's access to Administrators only</p></li><li class="listitem"><p><code class="option">/dot11_support=yes</code>: Support raw 802.11 traffic (and <span class="quote">“<span class="quote">Monitor Mode</span>”</span>) for wireless adapters</p></li><li class="listitem"><p><code class="option">/vlan_support=yes</code>: Support 802.1Q VLAN tag when capturing and sending data</p></li><li class="listitem"><p><code class="option">/winpcap_mode=yes</code>: Install Npcap in WinPcap API-compatible Mode</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-redistribution-options-gui"></a>Disabled options for GUI Mode</h3></div></div></div><p>
We may disable 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. Advanced users can still enable them using command-line
parameters, which is described in following sections.
</p><p>
Fortunately, if a distributor wants to start the Npcap installer GUI and disable
certain options for reasons like compatibility. It can also use this disable
mechanism by setting the command-line parameters to <code class="option">disabled</code>.
For example, the following command will start an installer GUI with the
<code class="option">dlt_null</code> disabled and unselected:
</p><p>
<span class="command"><strong>npcap-<em class="replaceable"><code>0.08</code></em>.exe /dlt_null=disabled</strong></span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-redistribution-options-gui"></a>How to change default options for GUI Mode</h3></div></div></div><p>
Default options for Npcap installer GUI can be changed. An example is:
</p><p>
<span class="command"><strong>npcap-<em class="replaceable"><code>0.08</code></em>.exe /npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=yes</strong></span>
</p><p>
or even simpler:
</p><p>
<span class="command"><strong>npcap-<em class="replaceable"><code>0.08</code></em>.exe /winpcap_mode=yes</strong></span>
</p><p>
As the default option of <code class="option">/winpcap_mode</code> is no. Running the installer
directly without options will see <code class="option">Install Npcap in WinPcap API-compatible Mode</code>
<span class="emphasis"><em>UNCHECKED</em></span> by default in the <span class="quote">“<span class="quote">Installation Options</span>”</span> page.
However, the above two commands will launch the installer GUI, and in the <span class="quote">“<span class="quote">Installation Options</span>”</span> page, the
<code class="option">Install Npcap in WinPcap API-compatible Mode</code> option will be <span class="emphasis"><em>CHECKED</em></span> by default.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-redistribution-options-silent"></a>How to change options for Silent Mode</h3></div></div></div><p>
An example of changing option feature for silent installation is:
</p><p>
<span class="command"><strong>npcap-<em class="replaceable"><code>0.08</code></em>.exe /S /npf_startup=yes /loopback_support=yes /dlt_null=no /admin_only=no /dot11_support=no /vlan_support=no /winpcap_mode=yes</strong></span>
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If you doesn't specify a paramter key, it will take the default value.
This is the same with the GUI.</p></li><li class="listitem"><p>The keys are <span class="emphasis"><em>case-insensitive</em></span>.</p></li><li class="listitem"><p>The values are <span class="emphasis"><em>case-sensitive</em></span>, only two values are
permitted: <code class="option">yes</code> or <code class="option">no</code>.</p></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-download"></a>Downloads</h2></div></div></div><p>
Latest Npcap installer: <a class="ulink" href="https://github.com/nmap/npcap/releases" target="_top">Npcap Releases</a>
</p><p>
Archived Npcap installers (prior to <code class="option">0.05</code>):
<a class="ulink" href="https://svn.nmap.org/nmap-exp/yang/NPcap-LWF/npcap_history_versions/" target="_top">Npcap Releases (SVN)</a>
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-development"></a>Development</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-sdk"></a>SDK</h3></div></div></div><p>
Npcap has its own SDK for <span class="quote">“<span class="quote">Non-WinPcap Compatible Mode</span>”</span>.
By using it, your software will run under <span class="quote">“<span class="quote">Non-WinPcap Compatible Mode</span>”</span>.
We don't update the SDK as frequently as the binaries. The latest SDK is <a class="ulink" href="https://github.com/nmap/npcap/releases/tag/v0.07-r9" target="_top">Npcap SDK 0.07 r9</a>.
</p><p>
If you only want to build your software under <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span>
(which is <span class="emphasis"><em>NOT</em></span> recommended), please use the legacy
<a class="ulink" href="http://www.winpcap.org/devel.htm" target="_top">WinPcap 4.1.2 Developer's Pack</a> instead.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-documentation"></a>Documentation</h3></div></div></div><p>
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
<a class="ulink" href="https://www.winpcap.org/docs/default.htm" target="_top">WinPcap documentation</a>
for general usage of Npcap.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-examples"></a>Examples</h3></div></div></div><p>
You can refer to <a class="ulink" href="https://github.com/nmap/npcap/tree/master/Examples" target="_top">WinPcap's examples</a> to see the usage.
</p><p>
I also provided an example:
<a class="ulink" href="https://github.com/hsluoyz/UserBridge/" target="_top">UserBridge</a>,
which is a tool to redirect all packets from an interface to another.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-incompatible"></a>The list of incompatible software</h2></div></div></div><p>
The LWF technique Npcap used is usually a cause of conflicts between the programs
using network drivers. The incompatible result can be <span class="emphasis"><em>bluescreen, no adapters,
no traffic</em></span>, etc. The reason can <span class="emphasis"><em>either be Npcap's bug or the incompatible
software's bug</em></span>. If the latter is the case, there's nothing much can be done by
Npcap but for youself to remove the incompatible software.
</p><p>
The commonly seen sources of the incompatble software are <span class="emphasis"><em>anti-virus,
network firewall, VPN, traffic capture</em></span>, etc. To help you identify those
software, We have collected the programs that have trouble with Npcap
according to user's report, so what you need to do is to remove them if
your Npcap doesn't work normally.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Avaya Collaboration Services</p></li><li class="listitem"><p>Avaya UCA Type Library</p></li><li class="listitem"><p>Killer Network Manager</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-qa"></a>Q & A</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Network disconnects after installing Npcap: As Microsoft states
<a class="ulink" href="https://support.microsoft.com/en-us/kb/2019184" target="_top">here</a>,
<span class="emphasis"><em>an optional NDIS light-weight filter (LWF) driver like Npcap could cause
90-second delay in network availability</em></span>. Some solutions you could try
are: 1) wait for 90 seconds; 2) disable and re-enable the adapter icon in
<span class="command"><strong>ncpa.cpl</strong></span>; 3) reboot. If this doesn't help you, you should
consider that you have <span class="emphasis"><em>installed some incompatible software</em></span>.
It can be a <span class="emphasis"><em>VPN, anti-virus, firewall or other network related</em></span>
software. We are maintaining an incompatible software list in the previous section.
So you can uninstall all those potential software one by one, and see which one
exactly causes the issue. Don't forget to report it to me, so I could add it to
this list.</p></li><li class="listitem"><p>Installation fails with error code <code class="varname">0x8004a029</code>:
The cause is that you have <span class="quote">“<span class="quote">reached the maximum number of network filter
drivers</span>”</span>, see solution
<a class="ulink" href="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" target="_top">here</a>.
</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-license"></a>License</h2></div></div></div><p>
See: <a class="ulink" href="https://github.com/nmap/npcap/blob/master/LICENSE" target="_top">LICENSE</a>
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-issues"></a>Bug report</h2></div></div></div><p>
Please report any bugs or issues about Npcap at:
<a class="ulink" href="https://github.com/nmap/nmap/issues" target="_top">Nmap issues on GitHub</a>.
In your report, please provide <span class="emphasis"><em>AT LEAST</em></span> your OS (Vista |
Win7 | Win8 | Win10, x86 | x64), Npcap version and installation options, user
software version (e.g. Nmap, Wireshark), reproduce steps and other information
you think necessary. If your issue occurs only on a special OS version (e.g. Win10
1511, 1607), please mention it in the report.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-issues-installation-log"></a>Installation log</h3></div></div></div><p>
Npcap keeps track of the installation in a log file:
<code class="filename">C:\Program Files\Npcap\install.log</code>, please submit it
together in your report if you encounter issues about the installation
(e.g. the installer halts).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-issues-packet-log"></a>Dynamic link library (DLL) log</h3></div></div></div><p>
If you think the dynamic link library (<code class="filename">Packet.dll</code>) doesn't
function well, you can refer to <code class="filename">Packet.dll</code>'s log. It's
also stored in Npcap's installation folder: <code class="filename">C:\Program Files\Npcap\Packet.log</code>.
We don't enable this log feature in regular releases. You have two ways: If you
are a Npcap developer, you can build the <code class="filename">Packet.sln</code> project
with the <code class="varname">_DEBUG_TO_FILE</code> 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
<a class="ulink" href="https://github.com/nmap/npcap/releases/tag/v0.08-r4" target="_top">Npcap 0.08 r4</a>.
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 (<code class="filename">Packet.log</code>) 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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-issues-driver-log"></a>Driver log</h3></div></div></div><p>
If you think the driver doesn't function well, you can open an
<span class="emphasis"><em>Administrator</em></span> command prompt, enter
<span class="command"><strong>sc query npcap</strong></span> to query the driver status and
<span class="command"><strong>net start npcap</strong></span> to start the driver (replace
<em class="replaceable"><code>npcap</code></em> with <em class="replaceable"><code>npf</code></em>
if you installed Npcap in <span class="quote">“<span class="quote">WinPcap Compatible Mode</span>”</span>).
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
<a class="ulink" href="https://github.com/nmap/npcap/releases/tag/v0.07-r16" target="_top">Npcap 0.07 r16</a>.
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
<a class="ulink" href="https://technet.microsoft.com/en-us/sysinternals/debugview.aspx" target="_top">DbgView</a>
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.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="npcap-issues-bsod"></a>Blue screen of death (BSoD) dump</h3></div></div></div><p>
If you encountered BSoD when using Npcap, please attach the minidump
file (in <code class="filename">C:\Windows\Minidump</code>) to your report
together with the Npcap version. We may ask you to provide the full
dump (<code class="filename">C:\Windows\MEMORY.DMP</code>) for further troubleshooting.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="npcap-list"></a>Contact</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="mailto:[email protected]" target="_top">[email protected]</a> (Nmap development list, this is <span class="emphasis"><em>preferred</em></span>)</p></li><li class="listitem"><p><a class="ulink" href="mailto:[email protected]" target="_top">[email protected]</a> (Yang Luo's email, if your issue needs to be kept private, please contact me via this mail)</p></li></ul></div></div></div></body></html>