Libpcap API for stopping delivering new packets

[garrymar]

There are cases when it is desirable to fully drain the OS-level input packet buffer before terminating programs using libpcap like tcpdump, Wireshark, and others. For example, it might be necessary when large input buffers are in use to accommodate faster input packet streams with slower storage devices.

Currently, when programs like tcpdump terminate, they cannot drain the input buffer to a dump file as there is no way to instruct libpcap to stop delivering new packets to the capturing program first. As a result, there is no way to prevent loss of packets stored in large input buffers when the programs stop. If libpcap provides such an API, consuming program will be able to ask for no more new packets and safely drain the input buffer before quitting.

More details on this use case can be found in the following mailing list discussion:

https://seclists.org/tcpdump/2024/q4/10

Thank you.

Regards,
Garri

[guyharris]

My first question to the audience:

What should the routine be called? It could be pcap_stop_capture(), but that name seems a bit vague and its purpose could be misinformed.

[guyharris]

Note that pcap_stop_capture() would cause all packets received by the machine after it's called not to be provided the the program, so, unless you only call it when you know you don't want any more packets, you're going to end up with... all subsequent packets being dropped by the capturing program.

[GD1200]

My first question to the audience:

What should the routine be called? It could be pcap_stop_capture(), but that name seems a bit vague and its purpose could be misinformed.

@guyharris, what about pcap_deprive_buffer() or pcap_deprive_input_buffer()? I think it would be in line with what will happen with the buffer.

I do not know if the input buffer is also used for offline reading, but if it is, it can help avoid focus on the "capture" part as it is connoted with live reading.

My 2 cents.

Garri

[guyharris]

I think it would be in line with what will happen with the buffer.

I.e., the input buffer will be deprived of any further packets, as in "further packets will be withheld from it"? I guess that works, although 1) it's a bit of a complicated explanation of the deprivation and 2) people might not be thinking of the input buffer, they may be thinking of the enitre pcap_t.

I do not know if the input buffer is also used for offline reading

It isn't. When capturing, the packets arrive spontaneously, rather than being individually requested; when reading, packets are individually requested by the loop in pcap_loop() or by a call to pcap_dispatch(), pcap_next(), or pcap_next_ex().

[fxlb]

pcap_drain_buffer() or pcap_drain_input_buffer() ?

[fxlb]

pcap_consume_buffer() or pcap_consume_input_buffer() ?

[fxlb]

pcap_exhaust_buffer() or pcap_exhaust_input_buffer()?

[GD1200]

@fxlb, I think the verbs drain, consume, and exhaust would describe the point of view of the program using libpcap's API as it would be the job of the program itself to drain/consume/exhaust the buffer once it is "abandoned" unless I am missing something.

[fxlb]

pcap_close_buffer() or pcap_close_input_buffer()?

[GD1200]

pcap_lock_buffer()
pcap_freeze_buffer()
pcap_readonly_buffer()

I am also thinking of these ones, but the buffer will not be readonly in fact as the packets will be popped out from it.

[fxlb]

pcap_lock_buffer() or pcap_lock_input_buffer()?

[GD1200]

pcap_stop_filling_buffer()
pcap_stop_feeding_buffer()
pcap_stop_updating_buffer()

?

[GD1200]

pcap_forsake_buffer()
pcap_forget_buffer()
pcap_abandon_buffer()

:)

[infrastation]

"The two most difficult problems in software engineering are cache invalidation and naming".

On a serious note, would it fit the problem space better to provide an optional call such as pcap_set_break_mode(), which would take an argument such as PCAP_BREAK_IMMEDIATELY and PCAP_BREAK_AFTER_DRAINING, copy it to a member of the pcap_t and leave it alone until it is time to stop the capture? Then the shutdown process could take the configured break mode into account and either break immediately or drain the buffer first. Such approach potentially could allow changing the default break mode through an environment variable (something like PCAP_BREAK_MODE without modifying and recompiling the libpcap client.