nmap / nmap/npcap

Npcap buffer sizes are not well-documented

Open
#30 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
C
Stars
3.6k
Forks
592
PR merge metrics
No merged PRs in 30d

Description

Npcap Guide does not have good documentation of the interaction between the sizes of the kernel buffer, the user buffer, and the number of CPU cores. This information is vital to proper tuning of performance. A brief description follows, which could be used to begin the appropriate documentation:

The Npcap driver stores captured packets in a circular buffer until they are retrieved (pcap_next_ex(), pcap_dispatch(), pcap_loop(), PacketRecievePacket()) by the user program. Each adapter handle (pcap_t or ADAPTER) has its own buffer, the size of which is set via pcap_set_buffer_size(), pcap_setbuff() (deprecated WinPcap extension), or PacketSetBuff(), and which defaults to 1MB. The buffer is split into a number of independent segments according to the number of processors on the system. When a packet is received by the driver, it is put into the buffer segment corresponding to the driver thread's current processor. If there is not enough room in that segment, the packet is dropped.

A user program receives packets into a "user buffer" which is passed to PacketRecievePacket(). The driver empties packets from its own buffer segments in the order they were received until it runs out of space in the user buffer or runs out of packets to return. A large user buffer can ensure the kernel buffer is emptied more quickly, preventing packet drops. The libpcap API (wpcap.dll) configures the size of this user buffer via pcap_setuserbuffer(), which defaults to 256KB.

The current behavior of splitting the buffer into number_of_processors segments is flawed, as described in nmap/nmap#1967, but it needs to be documented anyway, since it's how WinPcap did things, minus the mapping of processor numbers greater than 63 to 63. We can rewrite the documentation if and when we change the behavior.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Npcap Guide and the buffer APIs named in the issue, including pcap_set_buffer_size(), pcap_setuserbuffer(), PacketSetBuff(), and PacketRecievePacket(). Document how kernel-buffer segments, user-buffer size, and processor count affect packet drops and performance; done means the Guide explains the current behavior and tuning implications.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation, networking
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.