Skip to contentSkip to conversation

Wireshark external capture for DPDK

PATCH New Stephen Hemminger 2 participants 29 messages Jul 24 – Oct 25

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

v6 cover Wireshark external capture for DPDK

This series adds live packet capture from a running DPDK primary over the telemetry socket. A new capture library installs Rx/Tx callbacks on an ethdev port and writes pcapng to a caller-supplied path or FIFO, with an optional libpcap filter and per-queue selection. No application changes are needed beyond linking the library.

Two front ends use it: a Wireshark extcap plugin that makes each DPDK port appear in the Wireshark interface list, and a dpdk-dumpcap.py for file capture without a secondary process.

The pcapng interface-statistics block gains a filter-accepted count, which changes the rte_pcapng_write_stats() signature.

dpdk-dumpcap.py is not installed yet, since the name would shadow the existing C dpdk-dumpcap.The long term plan is to remove pdump and old dumpcap code and only support this new code.
Will take several releases to stablize first.

Stephen Hemminger (5):
pcapng: extend interface statistics
capture: infrastructure wireshark packet capture
test: add test for capture hooks usertools/dpdk-wireshark-extcap.py: script for external capture usertools/dpdk-dumpcap: add script for file capture

 MAINTAINERS                            |    4 +
 app/dumpcap/main.c                     |   16 +-
 app/test/meson.build                   |    1 +
 app/test/test_capture.c                |  512 ++++++++++++
 app/test/test_pcapng.c                 |    6 +-
 doc/guides/rel_notes/release_26_11.rst |   11 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  144 ++++
 lib/capture/capture.c                  | 1032 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  108 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 lib/pcapng/rte_pcapng.c                |   32 +-
 lib/pcapng/rte_pcapng.h                |   30 +-
 usertools/dpdk-dumpcap.py              |  426 ++++++++++
 usertools/dpdk-wireshark-extcap.py     |  374 +++++++++
 17 files changed, 2744 insertions(+), 29 deletions(-)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100755 usertools/dpdk-dumpcap.py
 create mode 100755 usertools/dpdk-wireshark-extcap.py
Signature · 1 line
2.53.0
#1 lore raw

PATCH v6 1/5 pcapng: extend interface statistics

The number of packets filtered was not implemented in original code but useful for analysis.

---
 app/dumpcap/main.c                     | 16 ++++++-------
 app/test/test_pcapng.c                 |  6 +++--
 doc/guides/rel_notes/release_26_11.rst |  5 ++++
 lib/pcapng/rte_pcapng.c                | 32 ++++++++++++++++++--------
 lib/pcapng/rte_pcapng.h                | 30 ++++++++++++++++--------
 5 files changed, 60 insertions(+), 29 deletions(-)
app/dumpcap/main.c +8 -8
index 46a6cb251e..baec68b0b9 100644
@@ -574,8 +574,8 @@ static void
 report_packet_stats(dumpcap_out_t out)
 {
 	struct rte_pdump_stats pdump_stats;
+	struct rte_pcapng_interface_stats isb;
 	struct interface *intf;
-	uint64_t ifrecv, ifdrop;
 	double percent;
 
 	fputc('\n', stderr);
@@ -584,22 +584,22 @@ report_packet_stats(dumpcap_out_t out)
 			continue;
 
 		/* do what Wiretap does */
-		ifrecv = pdump_stats.accepted + pdump_stats.filtered;
-		ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.ifrecv = pdump_stats.accepted + pdump_stats.filtered;
+		isb.ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.filteraccept = pdump_stats.accepted;
 
 		if (use_pcapng)
-			rte_pcapng_write_stats(out.pcapng, intf->port,
-					       ifrecv, ifdrop, NULL);
+			rte_pcapng_write_stats(out.pcapng, intf->port, &isb, sizeof(isb), NULL);
 
-		if (ifrecv == 0)
+		if (isb.ifrecv == 0)
 			percent = 0;
 		else
-			percent = 100. * ifrecv / (ifrecv + ifdrop);
+			percent = 100. * isb.ifrecv / (isb.ifrecv + isb.ifdrop);
 
 		fprintf(stderr,
 			"Packets received/dropped on interface '%s': "
 			"%"PRIu64 "/%" PRIu64 " (%.1f)\n",
-			intf->name, ifrecv, ifdrop, percent);
+			intf->name, isb.ifrecv, isb.ifdrop, percent);
 	}
 }
 
app/test/test_pcapng.c +4 -2
index d14ea84f0d..f6fd85faad 100644
@@ -570,8 +570,10 @@ test_write_packets(void)
 		goto fail;
 
 	/* write a statistics block */
-	ret = rte_pcapng_write_stats(pcapng, port_id,
-				     count, 0, "end of test");
+	struct rte_pcapng_interface_stats isb = {
+		.ifrecv = count,
+	};
+	ret = rte_pcapng_write_stats(pcapng, port_id, &isb, sizeof(isb), "end of test");
 	if (ret <= 0) {
 		printf("Write of statistics failed\n");
 		goto fail;
doc/guides/rel_notes/release_26_11.rst +5 -0
index 938617ca75..b27494fee7 100644
@@ -84,6 +84,11 @@ API Changes
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+* **pcapng: add packet filtering statistic.**
+
+  The API for ``rte_pcapng_write_stats`` was changed to include
+  recording the number of filtered packets.
+
 
 ABI Changes
 -----------
lib/pcapng/rte_pcapng.c +22 -10
index b5d1026891..455809d412 100644
@@ -394,9 +394,10 @@ rte_pcapng_add_interface(rte_pcapng_t *self, uint16_t port, uint16_t link_type,
 RTE_EXPORT_SYMBOL(rte_pcapng_write_stats)
 ssize_t
 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port_id,
-		       uint64_t ifrecv, uint64_t ifdrop,
-		       const char *comment)
+		       const struct rte_pcapng_interface_stats *stats,
+		       size_t size, const char *comment)
 {
+	struct rte_pcapng_interface_stats isb;
 	struct pcapng_statistics *hdr;
 	struct pcapng_option *opt;
 	uint64_t start_time = self->clock.ns_base;
@@ -410,12 +411,19 @@ rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port_id,
 	if (comment && strlen(comment) > PCAPNG_STR_MAX)
 		return -EINVAL;
 
+	/* Future proof for more/less stats - all UINT64_MAX */
+	memset(&isb, 0xff, sizeof(isb));
+	memcpy(&isb, stats, RTE_MIN(size, sizeof(*stats)));
+
 	optlen = 0;
 
-	if (ifrecv != UINT64_MAX)
-		optlen += pcapng_optlen(sizeof(ifrecv));
-	if (ifdrop != UINT64_MAX)
-		optlen += pcapng_optlen(sizeof(ifdrop));
+	/* compute how many stats will be added. */
+	if (isb.ifrecv != UINT64_MAX)
+		optlen += pcapng_optlen(sizeof(isb.ifrecv));
+	if (isb.ifdrop != UINT64_MAX)
+		optlen += pcapng_optlen(sizeof(isb.ifdrop));
+	if (isb.filteraccept != UINT64_MAX)
+		optlen += pcapng_optlen(sizeof(isb.filteraccept));
 
 	if (start_time != 0)
 		optlen += pcapng_optlen(sizeof(start_time));
@@ -439,12 +447,16 @@ rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port_id,
 	if (start_time != 0)
 		opt = pcapng_add_option(opt, PCAPNG_ISB_STARTTIME,
 					 &start_time, sizeof(start_time));
-	if (ifrecv != UINT64_MAX)
+	if (isb.ifrecv != UINT64_MAX)
 		opt = pcapng_add_option(opt, PCAPNG_ISB_IFRECV,
-				&ifrecv, sizeof(ifrecv));
-	if (ifdrop != UINT64_MAX)
+					&isb.ifrecv, sizeof(uint64_t));
+	if (isb.ifdrop != UINT64_MAX)
 		opt = pcapng_add_option(opt, PCAPNG_ISB_IFDROP,
-				&ifdrop, sizeof(ifdrop));
+					&isb.ifdrop, sizeof(uint64_t));
+	if (isb.filteraccept != UINT64_MAX)
+		opt = pcapng_add_option(opt, PCAPNG_ISB_FILTERACCEPT,
+					&isb.filteraccept, sizeof(uint64_t));
+
 	if (optlen != 0)
 		opt = pcapng_add_option(opt, PCAPNG_OPT_END, NULL, 0);
 
lib/pcapng/rte_pcapng.h +21 -9
index d8d328f710..172455af60 100644
@@ -178,21 +178,33 @@ ssize_t
 rte_pcapng_write_packets(rte_pcapng_t *self,
 			 struct rte_mbuf *pkts[], uint16_t nb_pkts);
 
+/**
+ * A structure to store interface statistics in pcapng
+ * Interface statistics block.
+ * If the statistic is unavailable or unknown, use UINT64_MAX.
+ *
+ * Subset of definitions come from IETF pcapng standard.
+ * The osdrop and usrdeliv statistics are not included because
+ * DPDK does not use OS and does not deliver to application over sockets.
+ */
+struct rte_pcapng_interface_stats {
+	uint64_t ifrecv;	/**< Packets received on interface during capture. */
+	uint64_t ifdrop;	/**< Packets dropped by interface due to lack of resources. */
+	uint64_t filteraccept;	/**< Packets accepted by filter. */
+};
+
 /**
  * Write an Interface statistics block.
- * For statistics, use 0 if don't know or care to report it.
  * Should be called before closing capture to report results.
  *
  * @param self
  *  The handle to the packet capture file
  * @param port
  *  The Ethernet port to report stats on.
- * @param ifrecv
- *  The number of packets received by capture.
- *  Optional: use UINT64_MAX if not known.
- * @param ifdrop
- *  The number of packets missed by the capture process.
- *  Optional: use UINT64_MAX if not known.
+ * @param stats
+ *  The statistics to write.
+ * @param stats_sz
+ *  The sizeof statistics structure.
  * @param comment
  *  Optional comment to add to statistics.
  * @return
@@ -203,8 +215,8 @@ rte_pcapng_write_packets(rte_pcapng_t *self,
  */
 ssize_t
 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port,
-		       uint64_t ifrecv, uint64_t ifdrop,
-		       const char *comment);
+		       const struct rte_pcapng_interface_stats *stats,
+		       size_t stats_sz, const char *comment);
 
 #ifdef __cplusplus
 }
Signature · 1 line
2.53.0
#2 lore raw

PATCH v6 2/5 capture: infrastructure wireshark packet capture

In reply to Stephen Hemminger

This provides a telemetry extension to provide packet capture. It is intended to be used with a front end script to provide external packet capture for wireshark.

---
 MAINTAINERS                            |    1 +
 doc/guides/rel_notes/release_26_11.rst |    4 +
 lib/capture/capture.c                  | 1032 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  108 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 7 files changed, 1221 insertions(+)
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
MAINTAINERS +1 -0
index e99a65d197..fcd350ad94 100644
@@ -1720,6 +1720,7 @@ F: doc/guides/sample_app_ug/qos_scheduler.rst
 Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
+F: lib/capture/
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
doc/guides/rel_notes/release_26_11.rst +4 -0
index b27494fee7..8291c2c4e5 100644
@@ -55,6 +55,10 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added wireshark capture support.**
+
+  * Added ``capture`` library for packet capture via telemetry API.
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +1032 -0

1,032 lines not on this page · raw message

lib/capture/capture_impl.h new file +56 -0

56 lines not on this page · raw message

lib/capture/filter.c new file +108 -0

108 lines not on this page · raw message

lib/capture/meson.build new file +19 -0
new file mode 100644
index 0000000000..4dbe0d1a78
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+if is_windows
+    build = false
+    reason = 'not supported on Windows'
+    subdir_done()
+endif
+
+sources = files('capture.c')
+
+deps += ['ethdev', 'pcapng', 'bpf']
+
+if dpdk_conf.has('RTE_HAS_LIBPCAP')
+    sources += files('filter.c')
+    ext_deps += pcap_dep
+else
+    warning('libpcap is missing, capture filtering will be disabled')
+endif
lib/meson.build +1 -0
index af5c160cb8..6d9992f61f 100644
@@ -49,6 +49,7 @@ libraries = [
         'lpm',
         'member',
         'pcapng',
+        'capture', # depends on pcapng and bpf
         'power',
         'rawdev',
         'regexdev',
Signature · 1 line
2.53.0
#3 lore raw

PATCH v6 3/5 test: add test for capture hooks

In reply to Stephen Hemminger

Provide tests to exercise telemetry based packet capture.

---
 MAINTAINERS             |   2 +
 app/test/meson.build    |   1 +
 app/test/test_capture.c | 512 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 515 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +2 -0
index fcd350ad94..5ce969d02f 100644
@@ -1721,6 +1721,8 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: usertools/dpdk-wireshark-extcap.py
+F: doc/guides/tools/wireshark_extcap.rst
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
app/test/meson.build +1 -0
index 51abeeb732..b73ae8ca07 100644
@@ -37,6 +37,7 @@ source_file_deps = {
     'test_bpf.c': ['bpf', 'net'],
     'test_bpf_validate.c': ['bpf'],
     'test_byteorder.c': [],
+    'test_capture.c': ['net_null', 'net', 'ethdev', 'bus_vdev', 'capture'],
     'test_cfgfile.c': ['cfgfile'],
     'test_cksum.c': ['net'],
     'test_cksum_perf.c': ['net'],
app/test/test_capture.c new file +512 -0

512 lines not on this page · raw message

Signature · 1 line
2.53.0
#4 lore raw

PATCH v6 4/5 usertools/dpdk-wireshark-extcap.py: script for external capture

In reply to Stephen Hemminger

Provide glue script that wireshark can use to access telemetry based packet capture. It is dual licensed because it maybe desirable to put this in wireshark repository.

See https://www.wireshark.org/docs/man-pages/extcap.html

---
 doc/guides/rel_notes/release_26_11.rst |   1 +
 doc/guides/tools/index.rst             |   1 +
 doc/guides/tools/wireshark_extcap.rst  | 144 ++++++++++
 usertools/dpdk-wireshark-extcap.py     | 374 +++++++++++++++++++++++++
 4 files changed, 520 insertions(+)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100755 usertools/dpdk-wireshark-extcap.py
doc/guides/rel_notes/release_26_11.rst +1 -0
index 8291c2c4e5..9835807fcc 100644
@@ -58,6 +58,7 @@ New Features
 * **Added wireshark capture support.**
 
   * Added ``capture`` library for packet capture via telemetry API.
+  * Added python script for wireshark external capture integration.
 
 
 Removed Items
doc/guides/tools/index.rst +1 -0
index 13f75a5bc6..01db27511a 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     telemetrywatcher
     dmaperf
     flow-perf
doc/guides/tools/wireshark_extcap.rst new file +144 -0

144 lines not on this page · raw message

usertools/dpdk-wireshark-extcap.py new file +374 -0

374 lines not on this page · raw message

Signature · 1 line
2.53.0
#5 lore raw

PATCH v6 5/5 usertools/dpdk-dumpcap: add script for file capture

In reply to Stephen Hemminger

This is a python version using capture library that provides the same syntax and functionality as wireshark dumpcap and the existing secondary process version dpdk-dumpcap.

Since it is a python script and uses capture it does not need secondary process support and should be portable to other OS environments.

It is designed to be a replacement for dpdk-dumpcap program which uses pdump.

---
 MAINTAINERS                            |   1 +
 doc/guides/rel_notes/release_26_11.rst |   1 +
 usertools/dpdk-dumpcap.py              | 426 +++++++++++++++++++++++++
 3 files changed, 428 insertions(+)
 create mode 100755 usertools/dpdk-dumpcap.py
MAINTAINERS +1 -0
index 5ce969d02f..e682823df9 100644
@@ -1722,6 +1722,7 @@ M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
 F: usertools/dpdk-wireshark-extcap.py
+F: usertools/dpdk-dumpcap.py
 F: doc/guides/tools/wireshark_extcap.rst
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
doc/guides/rel_notes/release_26_11.rst +1 -0
index 9835807fcc..6590899585 100644
@@ -59,6 +59,7 @@ New Features
 
   * Added ``capture`` library for packet capture via telemetry API.
   * Added python script for wireshark external capture integration.
+  * Added python version of dpdk-dumpcap.
 
 
 Removed Items
usertools/dpdk-dumpcap.py new file +426 -0

426 lines not on this page · raw message

Signature · 1 line
2.53.0
#6 lore raw

v2 cover Wireshark external capture interface

In reply to Stephen Hemminger

This series adds live packet capture from a running DPDK primary over the telemetry socket. A new capture library installs Rx/Tx callbacks on an ethdev port and writes pcapng to a caller-supplied path or FIFO, with an optional libpcap filter and per-queue selection. No application changes are needed beyond linking the library.

The pcapng interface-statistics block gains a filter-accepted count, which changes the rte_pcapng_write_stats() signature.

v2 - review feedback from checkpatch and AI
- defer dpdk-dumpcap.py until later
- add more documentation

Stephen Hemminger (4):
pcapng: extend interface statistics
capture: infrastructure wireshark packet capture
test: add test for capture hooks
usertools: add script for wireshark capture

 MAINTAINERS                            |    4 +
 app/dumpcap/main.c                     |   16 +-
 app/test/meson.build                   |    1 +
 app/test/test_capture.c                |  660 +++++++++++++
 app/test/test_pcapng.c                 |   10 +-
 doc/guides/prog_guide/capture_lib.rst  |  168 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |   14 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  144 +++
 lib/capture/capture.c                  | 1199 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  110 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 lib/pcapng/rte_pcapng.c                |   50 +-
 lib/pcapng/rte_pcapng.h                |   33 +-
 usertools/dpdk-wireshark-extcap.py     |  416 ++++++++
 usertools/meson.build                  |    1 +
 19 files changed, 2871 insertions(+), 33 deletions(-)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100755 usertools/dpdk-wireshark-extcap.py
Signature · 1 line
2.53.0
#7 lore raw

PATCH v2 1/4 pcapng: extend interface statistics

The number of packets filtered was not implemented in original code but useful for analysis.
Modify the API for writing pcapng statistics.
Use a structure and make it extensible in future.

---
 app/dumpcap/main.c                     | 16 ++++-----
 app/test/test_pcapng.c                 | 10 +++---
 doc/guides/rel_notes/release_26_11.rst |  9 +++++
 lib/pcapng/rte_pcapng.c                | 50 +++++++++++++++++++-------
 lib/pcapng/rte_pcapng.h                | 33 ++++++++++++-----
 5 files changed, 85 insertions(+), 33 deletions(-)
app/dumpcap/main.c +8 -8
index 46a6cb251e..baec68b0b9 100644
@@ -574,8 +574,8 @@ static void
 report_packet_stats(dumpcap_out_t out)
 {
 	struct rte_pdump_stats pdump_stats;
+	struct rte_pcapng_interface_stats isb;
 	struct interface *intf;
-	uint64_t ifrecv, ifdrop;
 	double percent;
 
 	fputc('\n', stderr);
@@ -584,22 +584,22 @@ report_packet_stats(dumpcap_out_t out)
 			continue;
 
 		/* do what Wiretap does */
-		ifrecv = pdump_stats.accepted + pdump_stats.filtered;
-		ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.ifrecv = pdump_stats.accepted + pdump_stats.filtered;
+		isb.ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.filteraccept = pdump_stats.accepted;
 
 		if (use_pcapng)
-			rte_pcapng_write_stats(out.pcapng, intf->port,
-					       ifrecv, ifdrop, NULL);
+			rte_pcapng_write_stats(out.pcapng, intf->port, &isb, sizeof(isb), NULL);
 
-		if (ifrecv == 0)
+		if (isb.ifrecv == 0)
 			percent = 0;
 		else
-			percent = 100. * ifrecv / (ifrecv + ifdrop);
+			percent = 100. * isb.ifrecv / (isb.ifrecv + isb.ifdrop);
 
 		fprintf(stderr,
 			"Packets received/dropped on interface '%s': "
 			"%"PRIu64 "/%" PRIu64 " (%.1f)\n",
-			intf->name, ifrecv, ifdrop, percent);
+			intf->name, isb.ifrecv, isb.ifdrop, percent);
 	}
 }
 
app/test/test_pcapng.c +6 -4
index d14ea84f0d..c62fdc1458 100644
@@ -558,8 +558,9 @@ test_write_packets(void)
 		goto fail;
 	}
 
-	/* write a statistics block */
-	ret = rte_pcapng_write_stats(pcapng, port_id, 0, 0, NULL);
+	/* write an initial statistics block */
+	struct rte_pcapng_interface_stats isb = { };
+	ret = rte_pcapng_write_stats(pcapng, port_id, &isb, sizeof(isb), NULL);
 	if (ret <= 0) {
 		printf("Write of statistics failed\n");
 		goto fail;
@@ -569,9 +570,10 @@ test_write_packets(void)
 	if (count < 0)
 		goto fail;
 
-	/* write a statistics block */
+	/* write a final statistics block with comment */
+	isb.ifrecv = count;
 	ret = rte_pcapng_write_stats(pcapng, port_id,
-				     count, 0, "end of test");
+				     &isb, sizeof(isb), "end of test");
 	if (ret <= 0) {
 		printf("Write of statistics failed\n");
 		goto fail;
doc/guides/rel_notes/release_26_11.rst +9 -0
index c8cc86295d..cdc3c99f64 100644
@@ -93,6 +93,11 @@ API Changes
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+* **pcapng: add packet filtering statistic.**
+
+  The API for ``rte_pcapng_write_stats`` was changed to include
+  recording the number of filtered packets.
+
 
 ABI Changes
 -----------
@@ -109,6 +114,10 @@ ABI Changes
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+* **pcapng: add packet filtering statistic.**
+
+  The ABI for ``rte_pcapng_write_stats`` now takes pointer to statistics.
+
 
 Known Issues
 ------------
lib/pcapng/rte_pcapng.c +38 -12

91 lines not on this page · raw message

lib/pcapng/rte_pcapng.h +24 -9
index d8d328f710..495b6d3204 100644
@@ -178,21 +178,36 @@ ssize_t
 rte_pcapng_write_packets(rte_pcapng_t *self,
 			 struct rte_mbuf *pkts[], uint16_t nb_pkts);
 
+/**
+ * A structure to store interface statistics in pcapng
+ * Interface statistics block.
+ * If the statistic is unavailable or unknown, use UINT64_MAX.
+ *
+ * Subset of definitions come from IETF pcapng standard.
+ * The osdrop and usrdeliv statistics are not included because
+ * DPDK does not use OS and does not deliver to application over sockets.
+ */
+struct rte_pcapng_interface_stats {
+	uint64_t ifrecv;	/**< Packets received on interface during capture. */
+	uint64_t ifdrop;	/**< Packets dropped by interface due to lack of resources. */
+	uint64_t filteraccept;	/**< Packets accepted by filter. */
+};
+
 /**
  * Write an Interface statistics block.
- * For statistics, use 0 if don't know or care to report it.
  * Should be called before closing capture to report results.
  *
  * @param self
  *  The handle to the packet capture file
  * @param port
  *  The Ethernet port to report stats on.
- * @param ifrecv
- *  The number of packets received by capture.
- *  Optional: use UINT64_MAX if not known.
- * @param ifdrop
- *  The number of packets missed by the capture process.
- *  Optional: use UINT64_MAX if not known.
+ * @param stats
+ *  The statistics to write.
+ * @param stats_sz
+ *  The sizeof statistics structure.
+ *  Must be greater than 0 and not more than sizeof(*stats).
+ *  This allows for future expansion of interface statistics but
+ *  with ABI compatibility.
  * @param comment
  *  Optional comment to add to statistics.
  * @return
@@ -203,8 +218,8 @@ rte_pcapng_write_packets(rte_pcapng_t *self,
  */
 ssize_t
 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port,
-		       uint64_t ifrecv, uint64_t ifdrop,
-		       const char *comment);
+		       const struct rte_pcapng_interface_stats *stats,
+		       size_t stats_sz, const char *comment);
 
 #ifdef __cplusplus
 }
Signature · 1 line
2.53.0
#8 lore raw

PATCH v2 2/4 capture: infrastructure wireshark packet capture

In reply to Stephen Hemminger

This provides a telemetry extension to provide packet capture. It is intended to be used with a front end script to provide external packet capture for wireshark.

---
 MAINTAINERS                            |    1 +
 doc/guides/prog_guide/capture_lib.rst  |  168 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |    4 +
 lib/capture/capture.c                  | 1199 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  110 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 9 files changed, 1559 insertions(+)
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
MAINTAINERS +1 -0
index e99a65d197..fcd350ad94 100644
@@ -1720,6 +1720,7 @@ F: doc/guides/sample_app_ug/qos_scheduler.rst
 Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
+F: lib/capture/
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
doc/guides/prog_guide/capture_lib.rst new file +168 -0

168 lines not on this page · raw message

doc/guides/prog_guide/index.rst +1 -0
index b9c0d59728..7e869db132 100644
@@ -129,6 +129,7 @@ Utility Libraries
     log_lib
     metrics_lib
     telemetry_lib
+    capture_lib
     pdump_lib
     pcapng_lib
     bpf_lib
doc/guides/rel_notes/release_26_11.rst +4 -0
index cdc3c99f64..00acc02ac3 100644
@@ -55,6 +55,10 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added wireshark capture support.**
+
+  * Added ``capture`` library for packet capture via telemetry API.
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +1199 -0

1,199 lines not on this page · raw message

lib/capture/capture_impl.h new file +56 -0

56 lines not on this page · raw message

lib/capture/filter.c new file +110 -0

110 lines not on this page · raw message

lib/capture/meson.build new file +19 -0
new file mode 100644
index 0000000000..4dbe0d1a78
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+if is_windows
+    build = false
+    reason = 'not supported on Windows'
+    subdir_done()
+endif
+
+sources = files('capture.c')
+
+deps += ['ethdev', 'pcapng', 'bpf']
+
+if dpdk_conf.has('RTE_HAS_LIBPCAP')
+    sources += files('filter.c')
+    ext_deps += pcap_dep
+else
+    warning('libpcap is missing, capture filtering will be disabled')
+endif
lib/meson.build +1 -0
index af5c160cb8..6d9992f61f 100644
@@ -49,6 +49,7 @@ libraries = [
         'lpm',
         'member',
         'pcapng',
+        'capture', # depends on pcapng and bpf
         'power',
         'rawdev',
         'regexdev',
Signature · 1 line
2.53.0
#9 lore raw

PATCH v2 3/4 test: add test for capture hooks

In reply to Stephen Hemminger

Provide tests to exercise telemetry based packet capture.

---
 MAINTAINERS             |   1 +
 app/test/meson.build    |   1 +
 app/test/test_capture.c | 660 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 662 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +1 -0
index fcd350ad94..608cb4b77d 100644
@@ -1721,6 +1721,7 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: app/test/test_capture.c
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
app/test/meson.build +1 -0
index 51abeeb732..b73ae8ca07 100644
@@ -37,6 +37,7 @@ source_file_deps = {
     'test_bpf.c': ['bpf', 'net'],
     'test_bpf_validate.c': ['bpf'],
     'test_byteorder.c': [],
+    'test_capture.c': ['net_null', 'net', 'ethdev', 'bus_vdev', 'capture'],
     'test_cfgfile.c': ['cfgfile'],
     'test_cksum.c': ['net'],
     'test_cksum_perf.c': ['net'],
app/test/test_capture.c new file +660 -0

660 lines not on this page · raw message

Signature · 1 line
2.53.0
#10 lore raw

PATCH v2 4/4 usertools: add script for wireshark capture

In reply to Stephen Hemminger

Provide glue script that wireshark can use to access telemetry based packet capture. It is dual licensed because it maybe desirable to put this in wireshark repository.

See https://www.wireshark.org/docs/man-pages/extcap.html

---
 MAINTAINERS                            |   2 +
 doc/guides/rel_notes/release_26_11.rst |   1 +
 doc/guides/tools/index.rst             |   1 +
 doc/guides/tools/wireshark_extcap.rst  | 144 +++++++++
 usertools/dpdk-wireshark-extcap.py     | 416 +++++++++++++++++++++++++
 usertools/meson.build                  |   1 +
 6 files changed, 565 insertions(+)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100755 usertools/dpdk-wireshark-extcap.py
MAINTAINERS +2 -0
index 608cb4b77d..7f220cc2c7 100644
@@ -1732,6 +1732,8 @@ F: app/pdump/
 F: doc/guides/tools/pdump.rst
 F: app/dumpcap/
 F: doc/guides/tools/dumpcap.rst
+F: usertools/dpdk-wireshark-extcap.py
+F: doc/guides/tools/wireshark_extcap.rst
 
 
 Packet Framework
doc/guides/rel_notes/release_26_11.rst +1 -0
index 00acc02ac3..c79ffb38cf 100644
@@ -58,6 +58,7 @@ New Features
 * **Added wireshark capture support.**
 
   * Added ``capture`` library for packet capture via telemetry API.
+  * Added python script for wireshark external capture integration.
 
 
 Removed Items
doc/guides/tools/index.rst +1 -0
index 13f75a5bc6..01db27511a 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     telemetrywatcher
     dmaperf
     flow-perf
doc/guides/tools/wireshark_extcap.rst new file +144 -0

144 lines not on this page · raw message

usertools/dpdk-wireshark-extcap.py new file +416 -0

416 lines not on this page · raw message

usertools/meson.build +1 -0
index 114d0a65b4..5debf73702 100644
@@ -13,6 +13,7 @@ install_data([
             'dpdk-rss-flows.py',
             'dpdk-telemetry-exporter.py',
             'dpdk-telemetry-watcher.py',
+            'dpdk-wireshark-extcap.py',
         ],
         install_dir: 'bin')
 
Signature · 1 line
2.53.0
#11 lore raw

Re: [PATCH v2 4/4] usertools: add script for wireshark capture

Quoted 8 lines · On Mon, 27 Jul 2026 15:42:47 -0700 Stephen Hemminger…

Provide glue script that wireshark can use to access telemetry based packet capture. It is dual licensed because it maybe desirable to put this in wireshark repository.

See https://www.wireshark.org/docs/man-pages/extcap.html

---

Recheck-request: iol-unit-arm64-testing

#12 lore raw

v3 cover Wireshark external capture

In reply to Stephen Hemminger

This series adds live packet capture from a running DPDK primary over the telemetry socket. A new capture library installs Rx/Tx callbacks on an ethdev port and writes pcapng to a caller-supplied path or FIFO, with an optional libpcap filter and per-queue selection.

Advantages of this:
- no primary/secondary needed; works on Linux and FreeBSD.
can also work on Windows with pcap support.
- installation is just putting script in Wireshark directory.
- script has no dependency on DPDK libraries; can be packaged with Wireshark.
- allows for live capture
- supports BPF (with JIT) for filtering

How it works:
- The capture library registers telemetry commands (/ethdev/capture/*)
- Callbacks are installed on the specified port/queues to copy packets
- Packets are formatted as pcapng and written to the specified output
- No packet data passes through the telemetry socket itself

The pcapng statistics interface has been extended to include the filter-accepted packet count, which was previously missing.

Testing:
- Run: dpdk-wireshark-extcap.py --extcap-interfaces to list available ports
- The script should be installed in Wireshark's extcap directory for GUI integration
- Comprehensive unit tests are included in app/test/test_capture.c
- Tested on Linux and FreeBSD

v3 - fixed AI review feedback

Stephen Hemminger (4):
pcapng: extend interface statistics
capture: infrastructure wireshark packet capture
test: add test for capture hooks
usertools: add script for wireshark capture

 MAINTAINERS                            |    4 +
 app/dumpcap/main.c                     |   16 +-
 app/test/meson.build                   |    1 +
 app/test/test_capture.c                |  660 +++++++++++++
 app/test/test_pcapng.c                 |   10 +-
 doc/guides/prog_guide/capture_lib.rst  |  168 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |   14 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  144 +++
 lib/capture/capture.c                  | 1202 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  110 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 lib/pcapng/rte_pcapng.c                |   50 +-
 lib/pcapng/rte_pcapng.h                |   33 +-
 usertools/dpdk-wireshark-extcap.py     |  416 ++++++++
 usertools/meson.build                  |    1 +
 19 files changed, 2874 insertions(+), 33 deletions(-)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100755 usertools/dpdk-wireshark-extcap.py
Signature · 1 line
2.53.0
#13 lore raw

PATCH v3 1/4 pcapng: extend interface statistics

The number of packets filtered was not implemented in original code but useful for analysis.
Modify the API for writing pcapng statistics.
Use a structure and make it extensible in future.

---
 app/dumpcap/main.c                     | 16 ++++-----
 app/test/test_pcapng.c                 | 10 +++---
 doc/guides/rel_notes/release_26_11.rst |  9 +++++
 lib/pcapng/rte_pcapng.c                | 50 +++++++++++++++++++-------
 lib/pcapng/rte_pcapng.h                | 33 ++++++++++++-----
 5 files changed, 85 insertions(+), 33 deletions(-)
app/dumpcap/main.c +8 -8
index 46a6cb251e..baec68b0b9 100644
@@ -574,8 +574,8 @@ static void
 report_packet_stats(dumpcap_out_t out)
 {
 	struct rte_pdump_stats pdump_stats;
+	struct rte_pcapng_interface_stats isb;
 	struct interface *intf;
-	uint64_t ifrecv, ifdrop;
 	double percent;
 
 	fputc('\n', stderr);
@@ -584,22 +584,22 @@ report_packet_stats(dumpcap_out_t out)
 			continue;
 
 		/* do what Wiretap does */
-		ifrecv = pdump_stats.accepted + pdump_stats.filtered;
-		ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.ifrecv = pdump_stats.accepted + pdump_stats.filtered;
+		isb.ifdrop = pdump_stats.nombuf + pdump_stats.ringfull;
+		isb.filteraccept = pdump_stats.accepted;
 
 		if (use_pcapng)
-			rte_pcapng_write_stats(out.pcapng, intf->port,
-					       ifrecv, ifdrop, NULL);
+			rte_pcapng_write_stats(out.pcapng, intf->port, &isb, sizeof(isb), NULL);
 
-		if (ifrecv == 0)
+		if (isb.ifrecv == 0)
 			percent = 0;
 		else
-			percent = 100. * ifrecv / (ifrecv + ifdrop);
+			percent = 100. * isb.ifrecv / (isb.ifrecv + isb.ifdrop);
 
 		fprintf(stderr,
 			"Packets received/dropped on interface '%s': "
 			"%"PRIu64 "/%" PRIu64 " (%.1f)\n",
-			intf->name, ifrecv, ifdrop, percent);
+			intf->name, isb.ifrecv, isb.ifdrop, percent);
 	}
 }
 
app/test/test_pcapng.c +6 -4
index d14ea84f0d..c62fdc1458 100644
@@ -558,8 +558,9 @@ test_write_packets(void)
 		goto fail;
 	}
 
-	/* write a statistics block */
-	ret = rte_pcapng_write_stats(pcapng, port_id, 0, 0, NULL);
+	/* write an initial statistics block */
+	struct rte_pcapng_interface_stats isb = { };
+	ret = rte_pcapng_write_stats(pcapng, port_id, &isb, sizeof(isb), NULL);
 	if (ret <= 0) {
 		printf("Write of statistics failed\n");
 		goto fail;
@@ -569,9 +570,10 @@ test_write_packets(void)
 	if (count < 0)
 		goto fail;
 
-	/* write a statistics block */
+	/* write a final statistics block with comment */
+	isb.ifrecv = count;
 	ret = rte_pcapng_write_stats(pcapng, port_id,
-				     count, 0, "end of test");
+				     &isb, sizeof(isb), "end of test");
 	if (ret <= 0) {
 		printf("Write of statistics failed\n");
 		goto fail;
doc/guides/rel_notes/release_26_11.rst +9 -0
index c8cc86295d..cdc3c99f64 100644
@@ -93,6 +93,11 @@ API Changes
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+* **pcapng: add packet filtering statistic.**
+
+  The API for ``rte_pcapng_write_stats`` was changed to include
+  recording the number of filtered packets.
+
 
 ABI Changes
 -----------
@@ -109,6 +114,10 @@ ABI Changes
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+* **pcapng: add packet filtering statistic.**
+
+  The ABI for ``rte_pcapng_write_stats`` now takes pointer to statistics.
+
 
 Known Issues
 ------------
lib/pcapng/rte_pcapng.c +38 -12

91 lines not on this page · raw message

lib/pcapng/rte_pcapng.h +24 -9
index d8d328f710..495b6d3204 100644
@@ -178,21 +178,36 @@ ssize_t
 rte_pcapng_write_packets(rte_pcapng_t *self,
 			 struct rte_mbuf *pkts[], uint16_t nb_pkts);
 
+/**
+ * A structure to store interface statistics in pcapng
+ * Interface statistics block.
+ * If the statistic is unavailable or unknown, use UINT64_MAX.
+ *
+ * Subset of definitions come from IETF pcapng standard.
+ * The osdrop and usrdeliv statistics are not included because
+ * DPDK does not use OS and does not deliver to application over sockets.
+ */
+struct rte_pcapng_interface_stats {
+	uint64_t ifrecv;	/**< Packets received on interface during capture. */
+	uint64_t ifdrop;	/**< Packets dropped by interface due to lack of resources. */
+	uint64_t filteraccept;	/**< Packets accepted by filter. */
+};
+
 /**
  * Write an Interface statistics block.
- * For statistics, use 0 if don't know or care to report it.
  * Should be called before closing capture to report results.
  *
  * @param self
  *  The handle to the packet capture file
  * @param port
  *  The Ethernet port to report stats on.
- * @param ifrecv
- *  The number of packets received by capture.
- *  Optional: use UINT64_MAX if not known.
- * @param ifdrop
- *  The number of packets missed by the capture process.
- *  Optional: use UINT64_MAX if not known.
+ * @param stats
+ *  The statistics to write.
+ * @param stats_sz
+ *  The sizeof statistics structure.
+ *  Must be greater than 0 and not more than sizeof(*stats).
+ *  This allows for future expansion of interface statistics but
+ *  with ABI compatibility.
  * @param comment
  *  Optional comment to add to statistics.
  * @return
@@ -203,8 +218,8 @@ rte_pcapng_write_packets(rte_pcapng_t *self,
  */
 ssize_t
 rte_pcapng_write_stats(rte_pcapng_t *self, uint16_t port,
-		       uint64_t ifrecv, uint64_t ifdrop,
-		       const char *comment);
+		       const struct rte_pcapng_interface_stats *stats,
+		       size_t stats_sz, const char *comment);
 
 #ifdef __cplusplus
 }
Signature · 1 line
2.53.0
#14 lore raw

PATCH v3 2/4 capture: infrastructure wireshark packet capture

In reply to Stephen Hemminger

This provides a telemetry extension to provide packet capture. It is intended to be used with a front end script to provide external packet capture for wireshark.

---
 MAINTAINERS                            |    1 +
 doc/guides/prog_guide/capture_lib.rst  |  168 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |    5 +
 lib/capture/capture.c                  | 1202 ++++++++++++++++++++++++
 lib/capture/capture_impl.h             |   56 ++
 lib/capture/filter.c                   |  110 +++
 lib/capture/meson.build                |   19 +
 lib/meson.build                        |    1 +
 9 files changed, 1563 insertions(+)
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/capture_impl.h
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
MAINTAINERS +1 -0
index e99a65d197..fcd350ad94 100644
@@ -1720,6 +1720,7 @@ F: doc/guides/sample_app_ug/qos_scheduler.rst
 Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
+F: lib/capture/
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
doc/guides/prog_guide/capture_lib.rst new file +168 -0

168 lines not on this page · raw message

doc/guides/prog_guide/index.rst +1 -0
index b9c0d59728..7e869db132 100644
@@ -129,6 +129,7 @@ Utility Libraries
     log_lib
     metrics_lib
     telemetry_lib
+    capture_lib
     pdump_lib
     pcapng_lib
     bpf_lib
doc/guides/rel_notes/release_26_11.rst +5 -0
index cdc3c99f64..cd53fc6b9f 100644
@@ -55,6 +55,11 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added wireshark capture support.**
+
+  * New ``capture`` library for packet capture accessed via telemetry API.
+
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +1202 -0

1,202 lines not on this page · raw message

lib/capture/capture_impl.h new file +56 -0

56 lines not on this page · raw message

lib/capture/filter.c new file +110 -0

110 lines not on this page · raw message

lib/capture/meson.build new file +19 -0
new file mode 100644
index 0000000000..4dbe0d1a78
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+if is_windows
+    build = false
+    reason = 'not supported on Windows'
+    subdir_done()
+endif
+
+sources = files('capture.c')
+
+deps += ['ethdev', 'pcapng', 'bpf']
+
+if dpdk_conf.has('RTE_HAS_LIBPCAP')
+    sources += files('filter.c')
+    ext_deps += pcap_dep
+else
+    warning('libpcap is missing, capture filtering will be disabled')
+endif
lib/meson.build +1 -0
index af5c160cb8..6d9992f61f 100644
@@ -49,6 +49,7 @@ libraries = [
         'lpm',
         'member',
         'pcapng',
+        'capture', # depends on pcapng and bpf
         'power',
         'rawdev',
         'regexdev',
Signature · 1 line
2.53.0
#15 lore raw

PATCH v3 3/4 test: add test for capture hooks

In reply to Stephen Hemminger

Provide tests to exercise telemetry based packet capture.

---
 MAINTAINERS             |   1 +
 app/test/meson.build    |   1 +
 app/test/test_capture.c | 660 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 662 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +1 -0
index fcd350ad94..608cb4b77d 100644
@@ -1721,6 +1721,7 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: app/test/test_capture.c
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
app/test/meson.build +1 -0
index 51abeeb732..b73ae8ca07 100644
@@ -37,6 +37,7 @@ source_file_deps = {
     'test_bpf.c': ['bpf', 'net'],
     'test_bpf_validate.c': ['bpf'],
     'test_byteorder.c': [],
+    'test_capture.c': ['net_null', 'net', 'ethdev', 'bus_vdev', 'capture'],
     'test_cfgfile.c': ['cfgfile'],
     'test_cksum.c': ['net'],
     'test_cksum_perf.c': ['net'],
app/test/test_capture.c new file +660 -0

660 lines not on this page · raw message

Signature · 1 line
2.53.0
#16 lore raw

PATCH v3 4/4 usertools: add script for wireshark capture

In reply to Stephen Hemminger

Provide glue script that wireshark can use to access telemetry based packet capture. It is dual licensed because it maybe desirable to put this in wireshark repository.

See https://www.wireshark.org/docs/man-pages/extcap.html

---
 MAINTAINERS                            |   2 +
 doc/guides/rel_notes/release_26_11.rst |   2 +-
 doc/guides/tools/index.rst             |   1 +
 doc/guides/tools/wireshark_extcap.rst  | 144 +++++++++
 usertools/dpdk-wireshark-extcap.py     | 416 +++++++++++++++++++++++++
 usertools/meson.build                  |   1 +
 6 files changed, 565 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100755 usertools/dpdk-wireshark-extcap.py
MAINTAINERS +2 -0
index 608cb4b77d..7f220cc2c7 100644
@@ -1732,6 +1732,8 @@ F: app/pdump/
 F: doc/guides/tools/pdump.rst
 F: app/dumpcap/
 F: doc/guides/tools/dumpcap.rst
+F: usertools/dpdk-wireshark-extcap.py
+F: doc/guides/tools/wireshark_extcap.rst
 
 
 Packet Framework
doc/guides/rel_notes/release_26_11.rst +1 -1
index cd53fc6b9f..8d4f57cef4 100644
@@ -58,7 +58,7 @@ New Features
 * **Added wireshark capture support.**
 
   * New ``capture`` library for packet capture accessed via telemetry API.
-
+  * Added python script for wireshark external capture integration.
 
 
 Removed Items
doc/guides/tools/index.rst +1 -0
index 13f75a5bc6..01db27511a 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     telemetrywatcher
     dmaperf
     flow-perf
doc/guides/tools/wireshark_extcap.rst new file +144 -0

144 lines not on this page · raw message

usertools/dpdk-wireshark-extcap.py new file +416 -0

416 lines not on this page · raw message

usertools/meson.build +1 -0
index 114d0a65b4..5debf73702 100644
@@ -13,6 +13,7 @@ install_data([
             'dpdk-rss-flows.py',
             'dpdk-telemetry-exporter.py',
             'dpdk-telemetry-watcher.py',
+            'dpdk-wireshark-extcap.py',
         ],
         install_dir: 'bin')
 
Signature · 1 line
2.53.0
#17 lore raw

v4 cover wireshark capture implementation

In reply to Stephen Hemminger

This series adds live packet capture from a running DPDK application over the telemetry socket. A new capture library installs Rx/Tx callbacks on an ethdev port and writes pcapng to a FIFO, with an optional libpcap filter and per-queue selection. A helper program presents those ports to Wireshark as capture interfaces.

Advantages of this:
- no secondary process needed to capture
- installation is just putting the helper in the Wireshark extcap directory
- the helper has no dependency on DPDK libraries; can be packaged with Wireshark
- allows for live capture
- supports BPF (with JIT) for filtering

How it works:
- The capture library registers telemetry commands (/ethdev/capture/*)
- Callbacks are installed on the specified port/queues to copy packets
- Packets are formatted as pcapng and written to the specified output
- No packet data passes through the telemetry socket itself

Packets handled by a secondary process are captured too, using EAL IPC as pdump does.

The helper is a C program so that it can be installed with privilege, which is what lets Wireshark capture from a root application without itself running as root. See doc/guides/tools/wireshark_extcap.rst.

Linux and FreeBSD only. Windows needs the transport first: telemetry has no socket server there and uses SOCK_SEQPACKET, which Windows AF_UNIX lacks. A stream socket would need the replies framed.

Testing:
- dpdk-wireshark-extcap --extcap-interfaces lists the ports. Reasons for an empty list go to stderr, which the Wireshark GUI hides.
- Unit tests are in app/test/test_capture.c
- Tested on Linux capturing from a root application as a non-root user. The unit test also passes on FreeBSD.

v4
- helper rewritten in C, and can be installed with privilege so Wireshark need not run as the same user as the DPDK application
- capture packets handled by secondary processes
- split the library into several files by area
- dropped the pcapng change adding the filter-accepted count to the interface statistics block. Still reported through telemetry.

v3 - fixed AI review feedback

Stephen Hemminger (3):
capture: infrastructure wireshark packet capture
test: add test for capture hooks
usertools: add script for wireshark capture

 MAINTAINERS                            |    4 +
 app/test/meson.build                   |    1 +
 app/test/test_capture.c                |  688 ++++++++++++++
 doc/guides/prog_guide/capture_lib.rst  |  167 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |    5 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  198 ++++
 lib/capture/capture.c                  |  560 ++++++++++++
 lib/capture/datapath.c                 |  420 +++++++++
 lib/capture/filter.c                   |  180 ++++
 lib/capture/meson.build                |   24 +
 lib/capture/multiproc.c                |  246 +++++
 lib/capture/output.c                   |  294 ++++++
 lib/capture/private.h                  |  214 +++++
 lib/meson.build                        |    1 +
 usertools/dpdk-wireshark-extcap.c      | 1145 ++++++++++++++++++++++++
 usertools/meson.build                  |   23 +
 18 files changed, 4172 insertions(+)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/datapath.c
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100644 lib/capture/multiproc.c
 create mode 100644 lib/capture/output.c
 create mode 100644 lib/capture/private.h
 create mode 100644 usertools/dpdk-wireshark-extcap.c
Signature · 1 line
2.53.0
#18 lore raw

PATCH v4 1/3 capture: infrastructure wireshark packet capture

This provides a telemetry extension to provide packet capture. It is intended to be used with a front end script to provide external packet capture for wireshark.

Captures packets from both primary and secondary.
The notification mechanism is similar to what is already done in pdump.

---
 MAINTAINERS                            |   1 +
 doc/guides/prog_guide/capture_lib.rst  | 159 +++++++
 doc/guides/prog_guide/index.rst        |   1 +
 doc/guides/rel_notes/release_26_11.rst |   4 +
 lib/capture/capture.c                  | 560 +++++++++++++++++++++++++
 lib/capture/datapath.c                 | 420 +++++++++++++++++++
 lib/capture/filter.c                   | 180 ++++++++
 lib/capture/meson.build                |  24 ++
 lib/capture/multiproc.c                | 246 +++++++++++
 lib/capture/output.c                   | 294 +++++++++++++
 lib/capture/private.h                  | 214 ++++++++++
 lib/meson.build                        |   1 +
 12 files changed, 2104 insertions(+)
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/datapath.c
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100644 lib/capture/multiproc.c
 create mode 100644 lib/capture/output.c
 create mode 100644 lib/capture/private.h
MAINTAINERS +1 -0
index edc0cbc801..96adaebc1d 100644
@@ -1717,6 +1717,7 @@ F: doc/guides/sample_app_ug/qos_scheduler.rst
 Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
+F: lib/capture/
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
doc/guides/prog_guide/capture_lib.rst new file +159 -0

159 lines not on this page · raw message

doc/guides/prog_guide/index.rst +1 -0
index b9c0d59728..7e869db132 100644
@@ -129,6 +129,7 @@ Utility Libraries
     log_lib
     metrics_lib
     telemetry_lib
+    capture_lib
     pdump_lib
     pcapng_lib
     bpf_lib
doc/guides/rel_notes/release_26_11.rst +4 -0
index a6df347411..bc1d62d423 100644
@@ -163,6 +163,10 @@ New Features
   Added ``rte_bbdev_queue_stats_get()`` function to retrieve statistics
   for a specific queue, complementing the existing device-level statistics API.
 
+* **Added wireshark capture support.**
+
+  * New ``capture`` library for packet capture accessed via telemetry API.
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +560 -0

560 lines not on this page · raw message

lib/capture/datapath.c new file +420 -0

420 lines not on this page · raw message

lib/capture/filter.c new file +180 -0

180 lines not on this page · raw message

lib/capture/meson.build new file +24 -0
new file mode 100644
index 0000000000..f6a3b3a1f8
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+if is_windows
+    build = false
+    reason = 'not supported on Windows'
+    subdir_done()
+endif
+
+sources = files(
+        'capture.c',
+        'datapath.c',
+        'multiproc.c',
+        'output.c',
+)
+
+deps += ['ethdev', 'pcapng', 'bpf']
+
+if dpdk_conf.has('RTE_HAS_LIBPCAP')
+    sources += files('filter.c')
+    ext_deps += pcap_dep
+else
+    warning('libpcap is missing, capture filtering will be disabled')
+endif
lib/capture/multiproc.c new file +246 -0

246 lines not on this page · raw message

lib/capture/output.c new file +294 -0

294 lines not on this page · raw message

lib/capture/private.h new file +214 -0

214 lines not on this page · raw message

lib/meson.build +1 -0
index af5c160cb8..6d9992f61f 100644
@@ -49,6 +49,7 @@ libraries = [
         'lpm',
         'member',
         'pcapng',
+        'capture', # depends on pcapng and bpf
         'power',
         'rawdev',
         'regexdev',
Signature · 1 line
2.53.0
#19 lore raw

PATCH v4 2/3 test: add test for capture hooks

In reply to Stephen Hemminger

Provide tests to exercise telemetry based packet capture.

---
 MAINTAINERS             |   1 +
 app/test/meson.build    |   1 +
 app/test/test_capture.c | 688 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 690 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +1 -0
index 96adaebc1d..2192de83e3 100644
@@ -1718,6 +1718,7 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: app/test/test_capture.c
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
app/test/meson.build +1 -0
index 881b919b63..872d1ecfbe 100644
@@ -41,6 +41,7 @@ source_file_deps = {
     'test_bpf.c': ['bpf', 'net'],
     'test_bpf_validate.c': ['bpf'],
     'test_byteorder.c': [],
+    'test_capture.c': ['net_null', 'net', 'ethdev', 'bus_vdev', 'capture'],
     'test_cfgfile.c': ['cfgfile'],
     'test_cksum.c': ['net'],
     'test_cksum_perf.c': ['net'],
app/test/test_capture.c new file +688 -0

688 lines not on this page · raw message

Signature · 1 line
2.53.0
#20 lore raw

PATCH v4 3/3 usertools: add script for wireshark capture

In reply to Stephen Hemminger

Provide glue executable that wireshark can use to access telemetry based packet capture. It is a C program so that it can be installed setuid if desired and it is standalone and does not depend on any DPDK libraries or infrastructure.

It is dual licensed because it maybe desirable to put this in wireshark repository later.

See https://www.wireshark.org/docs/man-pages/extcap.html

---
 MAINTAINERS                            |    2 +
 doc/guides/prog_guide/capture_lib.rst  |    8 +
 doc/guides/rel_notes/release_26_11.rst |    1 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  198 ++++
 usertools/dpdk-wireshark-extcap.c      | 1145 ++++++++++++++++++++++++
 usertools/meson.build                  |   23 +
 7 files changed, 1378 insertions(+)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 usertools/dpdk-wireshark-extcap.c
MAINTAINERS +2 -0
index 2192de83e3..5679d67f34 100644
@@ -1729,6 +1729,8 @@ F: app/pdump/
 F: doc/guides/tools/pdump.rst
 F: app/dumpcap/
 F: doc/guides/tools/dumpcap.rst
+F: usertools/dpdk-wireshark-extcap.c
+F: doc/guides/tools/wireshark_extcap.rst
 
 
 Packet Framework
doc/guides/prog_guide/capture_lib.rst +8 -0
index a9c9591bf2..d195b45e04 100644
@@ -145,6 +145,14 @@ capture fails to start if the FIFO has no reader::
    --> /ethdev/capture/stop,0
    {"/ethdev/capture/stop": {"status": "stopped"}}
 
+Using Wireshark
+---------------
+
+The ``dpdk-wireshark-extcap`` program presents the ports of a running DPDK
+application as Wireshark capture interfaces, using these telemetry commands
+with a FIFO created by Wireshark as the output.
+See :doc:`../tools/wireshark_extcap`.
+
 Limitations
 -----------
 
doc/guides/rel_notes/release_26_11.rst +1 -0
index bc1d62d423..7460cd0672 100644
@@ -166,6 +166,7 @@ New Features
 * **Added wireshark capture support.**
 
   * New ``capture`` library for packet capture accessed via telemetry API.
+  * Added ``dpdk-wireshark-extcap`` for wireshark external capture integration.
 
 
 Removed Items
doc/guides/tools/index.rst +1 -0
index 13f75a5bc6..01db27511a 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     telemetrywatcher
     dmaperf
     flow-perf
doc/guides/tools/wireshark_extcap.rst new file +198 -0

198 lines not on this page · raw message

usertools/dpdk-wireshark-extcap.c new file +1145 -0

1,145 lines not on this page · raw message

usertools/meson.build +23 -0
index 114d0a65b4..c2bc8715a3 100644
@@ -20,3 +20,26 @@ install_subdir(
         'telemetry-endpoints',
         install_dir: 'share/dpdk',
         strip_directory: false)
+
+# Wireshark extcap helper does not depend on anything from DPDK
+# and speaks the telemetry socket protocol directly.
+if not is_windows
+    extcap_cflags = []
+    extcap_deps = []
+
+    cap_dep = dependency('libcap', required: false)
+    if cap_dep.found()
+        extcap_cflags += '-DHAVE_LIBCAP'
+        extcap_deps += cap_dep
+    endif
+
+    executable('dpdk-wireshark-extcap',
+            files('dpdk-wireshark-extcap.c'),
+            # only for the project-wide '-include rte_config.h'
+            include_directories: config_inc,
+            c_args: extcap_cflags,
+            dependencies: extcap_deps,
+            pie: true,
+            install: true,
+            install_dir: 'bin')
+endif
Signature · 1 line
2.53.0
#21 lore raw

Re: [PATCH v4 0/3] wireshark capture implementation

In reply to Stephen Hemminger

Hi Stephen,

A live Wireshark capture capability via extcap and telemetry is a highly anticipated feature for runtime debugging. In our previous high-throughput testing with file-based captures, we frequently encountered severe bottlenecks where packets could not be written to disk fast enough, leading to massive ring buffer overflows and packet drops. Therefore, the implementation details of this feature are of great interest to us.

Reviewing the current v4 architecture, I have two major concerns:

1) Security Aspect & Telemetry Attack Surface
The introduction of control operations (such as dynamically registering rx/tx callbacks and passing arbitrary FIFO paths) drastically expands the attack surface of the otherwise read-only telemetry interface. Could we introduce a dedicated "debug mode" configuration to strictly guard these write paths? Furthermore, it would be beneficial to know if this mode plans to support more control interfaces down the road, such as a "stats_reset" command.

2) Performance Impact & Thread Isolation
The current implementation enforces a deep copy for captured packets. Have you considered an adaptive approach? For instance, allowing a lightweight shallow copy (mbuf clone) under certain conditions to save CPU cycles, while reverting to a deep copy only when conflicting offloads (like FAST_FREE) are active on the TX path.

Additionally, how is the actual packet writing thread managed and controlled? To prevent I/O blocking from introducing jitter into the fast path, should we consider isolating this writing worker thread onto a dedicated, isolated core (ecore/lcore)?

Thanks

Quoted 84 lines · Stephen Hemminger

This series adds live packet capture from a running DPDK application over the telemetry socket. A new capture library installs Rx/Tx callbacks on an ethdev port and writes pcapng to a FIFO, with an optional libpcap filter and per-queue selection. A helper program presents those ports to Wireshark as capture interfaces.

Advantages of this:
- no secondary process needed to capture
- installation is just putting the helper in the Wireshark extcap directory
- the helper has no dependency on DPDK libraries; can be packaged with Wireshark
- allows for live capture
- supports BPF (with JIT) for filtering

How it works:
- The capture library registers telemetry commands (/ethdev/capture/*)
- Callbacks are installed on the specified port/queues to copy packets
- Packets are formatted as pcapng and written to the specified output
- No packet data passes through the telemetry socket itself

Packets handled by a secondary process are captured too, using EAL IPC as pdump does.

The helper is a C program so that it can be installed with privilege, which is what lets Wireshark capture from a root application without itself running as root. See doc/guides/tools/wireshark_extcap.rst.

Linux and FreeBSD only. Windows needs the transport first: telemetry has no socket server there and uses SOCK_SEQPACKET, which Windows AF_UNIX lacks. A stream socket would need the replies framed.

Testing:
- dpdk-wireshark-extcap --extcap-interfaces lists the ports. Reasons for an empty list go to stderr, which the Wireshark GUI hides.
- Unit tests are in app/test/test_capture.c
- Tested on Linux capturing from a root application as a non-root user. The unit test also passes on FreeBSD.

v4
- helper rewritten in C, and can be installed with privilege so Wireshark need not run as the same user as the DPDK application
- capture packets handled by secondary processes
- split the library into several files by area
- dropped the pcapng change adding the filter-accepted count to the interface statistics block. Still reported through telemetry.

v3 - fixed AI review feedback

Stephen Hemminger (3):
capture: infrastructure wireshark packet capture
test: add test for capture hooks
usertools: add script for wireshark capture

 MAINTAINERS                            |    4 +
 app/test/meson.build                   |    1 +
 app/test/test_capture.c                |  688 ++++++++++++++
 doc/guides/prog_guide/capture_lib.rst  |  167 ++++
 doc/guides/prog_guide/index.rst        |    1 +
 doc/guides/rel_notes/release_26_11.rst |    5 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  198 ++++
 lib/capture/capture.c                  |  560 ++++++++++++
 lib/capture/datapath.c                 |  420 +++++++++
 lib/capture/filter.c                   |  180 ++++
 lib/capture/meson.build                |   24 +
 lib/capture/multiproc.c                |  246 +++++
 lib/capture/output.c                   |  294 ++++++
 lib/capture/private.h                  |  214 +++++
 lib/meson.build                        |    1 +
 usertools/dpdk-wireshark-extcap.c      | 1145 ++++++++++++++++++++++++
 usertools/meson.build                  |   23 +
 18 files changed, 4172 insertions(+)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/datapath.c
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100644 lib/capture/multiproc.c
 create mode 100644 lib/capture/output.c
 create mode 100644 lib/capture/private.h
 create mode 100644 usertools/dpdk-wireshark-extcap.c
#22 lore raw

Re: [PATCH v4 0/3] wireshark capture implementation

Quoted 7 lines · On Tue, 13 Oct 2026 16:28:41 +0800 fengchengwen <[email protected]> wrote:

Hi Stephen,

A live Wireshark capture capability via extcap and telemetry is a highly anticipated feature for runtime debugging. In our previous high-throughput testing with file-based captures, we frequently encountered severe bottlenecks where packets could not be written to disk fast enough, leading to massive ring buffer overflows and packet drops. Therefore, the implementation details of this feature are of great interest to us.

Live capture into Wireshark will not help if disk can't keep up; Wireshark is slower than disk. For high rate, use a capture filter and a short snaplen. Existing dpdk-dumpcap can already feed Wireshark through a pipe.

Quoted 9 lines

Reviewing the current v4 architecture, I have two major concerns:

1) Security Aspect & Telemetry Attack Surface
The introduction of control operations (such as dynamically registering rx/tx callbacks and passing arbitrary FIFO paths) drastically expands the attack surface of the otherwise read-only telemetry interface. Could we introduce a dedicated "debug mode" configuration to strictly guard these write paths? Furthermore, it would be beneficial to know if this mode plans to support more control interfaces down the road, such as a "stats_reset" command.

I am going to add a "--no-capture" option to command line like "--no-telemetry". The problem is that if the feature is "opt-in" then users have trouble using especially if command line is buried in application.

The launchpad script already has lots of hardening to let it run with privilege escalation. It resets itself after opening the socket. This is to allow setups (which is normal on most Linux distros) where any user in group wireshark can run capture.

The capture setup does checks to make sure that it can only be passed a FIFO and rejects symlinks etc.

The telemetry socket already has same permissions as the DPDK primary process. I.e if you can get to the telemetry you can read/modify shared memory etc.

Not sure where Bruce intends to go with telemetry

The other option is making a clone of telemetry (different socket and startup) but that duplicates effort.

Quoted 6 lines

2) Performance Impact & Thread Isolation
The current implementation enforces a deep copy for captured packets. Have you considered an adaptive approach? For instance, allowing a lightweight shallow copy (mbuf clone) under certain conditions to save CPU cycles, while reverting to a deep copy only when conflicting offloads (like FAST_FREE) are active on the TX path.

Looked at this before but:

- Rx: most applications assume the mbuf is writeable and having a capture break application is non starter.
- Tx: many drivers assume the mbuf is writeable (arguably a bug).
- FAST_FREE requires refcnt == 1.
- A clone pins the original buffer. If the reader falls behind, the capture ring holds Rx mempool buffers and can starve the NIC.

The most efficient way to handle this is to set snapshot length and get the relevant headers.

Quoted 4 lines

Additionally, how is the actual packet writing thread managed and controlled? To prevent I/O blocking from introducing jitter into the fast path, should we consider isolating this writing worker thread onto a dedicated, isolated core (ecore/lcore)?

The writer is just a control thread, it is going to block on the FIFO write system call if reader does not keep up. Then the packets back pressure is in the ring. The callback increments a statistic if ring is full.

The capture writers inherit the control cpuset so already isolated.

#23 lore raw

v5 cover wireshark extcap support

In reply to Stephen Hemminger

This series adds live packet capture from a running DPDK application over the telemetry socket which is usable as a source of Wireshark external capture (https://www.wireshark.org/docs/man-pages/extcap.html)

Capture is avaliable by default but can be disabled on the command line with --no-capture. It works on Linux and FreeBSD.

How it works:
- The capture library registers telemetry commands (/ethdev/capture/*)
- Callbacks are installed on the specified port/queues to copy packets
- Packets are formatted as pcapng and written to the specified output
- No packet data passes through the telemetry socket itself

Advantages of this:
- no secondary process needed to capture
- installation is just putting the helper in the extcap directory
- the helper has no dependency on DPDK libraries,
so it can be packaged with Wireshark
- allows for live capture
- supports BPF (with JIT) for filtering

Implementation Details:
- uses it is own version of userspace RCU to allow for callback to not need read-modify-write operations. Existing DPDK QSBR is ununsuitable because it requires the application to report quiescent states, and the point here is that the application stays unchanged. This RCU implementation could be integrated later into existing library.
- helper is a C program so that it can be installed with privilege. That is what lets Wireshark capture from a root application without itself running as root.
See doc/guides/tools/wireshark_extcap.rst.
- Windows support is not possible with current design because telemetry is not available on DPDK for Windows.

Testing:
- dpdk-wireshark-extcap --extcap-interfaces lists the ports. Reasons for an empty list go to stderr, which the GUI hides.
- Unit tests are in app/test/test_capture.c
- Tested on Linux capturing from a root application as a non-root user. The unit test also passes on FreeBSD.

v5
- fix build errors on FreeBSD
- split into smaller files
- callbacks use a local userspace RCU instead of a use count, so the datapath has no atomic read-modify-write
- added the --no-capture EAL option
- renamed the internal filter API, it was using an rte_ prefix for something private to the library

Stephen Hemminger (4):
capture: infrastructure wireshark packet capture
eal: add --no-capture option
test: add test for capture hooks
usertools: add script for wireshark capture

 MAINTAINERS                                   |    5 +
 app/test/meson.build                          |    1 +
 app/test/test_capture.c                       |  688 ++++++++++
 doc/guides/linux_gsg/eal_args.include.rst     |    4 +
 doc/guides/prog_guide/capture_lib.rst         |  196 +++
 .../prog_guide/img/capture_overview.svg       |   49 +
 doc/guides/prog_guide/index.rst               |    1 +
 doc/guides/rel_notes/release_26_11.rst        |    5 +
 doc/guides/tools/index.rst                    |    1 +
 doc/guides/tools/wireshark_extcap.rst         |  203 +++
 lib/capture/capture.c                         |  661 ++++++++++
 lib/capture/datapath.c                        |  414 ++++++
 lib/capture/filter.c                          |  179 +++
 lib/capture/meson.build                       |   42 +
 lib/capture/multiproc.c                       |  250 ++++
 lib/capture/output.c                          |  311 +++++
 lib/capture/private.h                         |  233 ++++
 lib/capture/rcu.c                             |  258 ++++
 lib/capture/rcu.h                             |  112 ++
 lib/eal/common/eal_common_config.c            |    7 +
 lib/eal/common/eal_common_options.c           |    3 +
 lib/eal/common/eal_internal_cfg.h             |    1 +
 lib/eal/common/eal_option_list.h              |    1 +
 lib/eal/include/rte_eal.h                     |    9 +
 lib/meson.build                               |    1 +
 usertools/dpdk-wireshark-extcap.c             | 1131 +++++++++++++++++
 usertools/meson.build                         |   23 +
 27 files changed, 4789 insertions(+)
 create mode 100644 app/test/test_capture.c
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/prog_guide/img/capture_overview.svg
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/datapath.c
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100644 lib/capture/multiproc.c
 create mode 100644 lib/capture/output.c
 create mode 100644 lib/capture/private.h
 create mode 100644 lib/capture/rcu.c
 create mode 100644 lib/capture/rcu.h
 create mode 100644 usertools/dpdk-wireshark-extcap.c
Signature · 1 line
2.53.0
#24 lore raw

PATCH v5 1/4 capture: infrastructure wireshark packet capture

This provides a telemetry extension to provide packet capture. It is intended to be used with a front end program to provide external packet capture for wireshark.

Captures packets from both primary and secondary. The mechanism is similar to what is already done in pdump but does not use pdump itself.

It uses its own implementation of userspace RCU so that the receive and transmit callbacks need no atomic read-modify-write operations. This relies on the OS being able to force a memory barrier on every CPU running a thread of the process.
That is available on all the operating systems DPDK supports.

The DPDK QSBR is unsuitable here because it requires the application to report quiescent states, and the point of this library is that the application is unchanged.
If this type of RCU proves generally useful it can be moved into lib/rcu later.

---
 MAINTAINERS                                   |   1 +
 doc/guides/prog_guide/capture_lib.rst         | 185 +++++
 .../prog_guide/img/capture_overview.svg       |  49 ++
 doc/guides/prog_guide/index.rst               |   1 +
 doc/guides/rel_notes/release_26_11.rst        |   4 +
 lib/capture/capture.c                         | 656 ++++++++++++++++++
 lib/capture/datapath.c                        | 414 +++++++++++
 lib/capture/filter.c                          | 179 +++++
 lib/capture/meson.build                       |  42 ++
 lib/capture/multiproc.c                       | 245 +++++++
 lib/capture/output.c                          | 311 +++++++++
 lib/capture/private.h                         | 233 +++++++
 lib/capture/rcu.c                             | 258 +++++++
 lib/capture/rcu.h                             | 112 +++
 lib/meson.build                               |   1 +
 15 files changed, 2691 insertions(+)
 create mode 100644 doc/guides/prog_guide/capture_lib.rst
 create mode 100644 doc/guides/prog_guide/img/capture_overview.svg
 create mode 100644 lib/capture/capture.c
 create mode 100644 lib/capture/datapath.c
 create mode 100644 lib/capture/filter.c
 create mode 100644 lib/capture/meson.build
 create mode 100644 lib/capture/multiproc.c
 create mode 100644 lib/capture/output.c
 create mode 100644 lib/capture/private.h
 create mode 100644 lib/capture/rcu.c
 create mode 100644 lib/capture/rcu.h
MAINTAINERS +1 -0
index 93ad53027d..71af3542e6 100644
@@ -1723,6 +1723,7 @@ F: doc/guides/sample_app_ug/qos_scheduler.rst
 Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
+F: lib/capture/
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
doc/guides/prog_guide/capture_lib.rst new file +185 -0

185 lines not on this page · raw message

doc/guides/prog_guide/img/capture_overview.svg new file +49 -0

49 lines not on this page · raw message

doc/guides/prog_guide/index.rst +1 -0
index b9c0d59728..7e869db132 100644
@@ -129,6 +129,7 @@ Utility Libraries
     log_lib
     metrics_lib
     telemetry_lib
+    capture_lib
     pdump_lib
     pcapng_lib
     bpf_lib
doc/guides/rel_notes/release_26_11.rst +4 -0
index be758a0c02..0a43628aed 100644
@@ -264,6 +264,10 @@ New Features
   Added ``dpdk-validate-bpf`` tool to pre-validate eBPF programs
   for compatibility with the ``lib/bpf`` execution context.
 
+* **Added wireshark capture support.**
+
+  * New ``capture`` library for packet capture accessed via telemetry API.
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +656 -0

656 lines not on this page · raw message

lib/capture/datapath.c new file +414 -0

414 lines not on this page · raw message

lib/capture/filter.c new file +179 -0

179 lines not on this page · raw message

lib/capture/meson.build new file +42 -0

42 lines not on this page · raw message

lib/capture/multiproc.c new file +245 -0

245 lines not on this page · raw message

lib/capture/output.c new file +311 -0

311 lines not on this page · raw message

lib/capture/private.h new file +233 -0

233 lines not on this page · raw message

lib/capture/rcu.c new file +258 -0

258 lines not on this page · raw message

lib/capture/rcu.h new file +112 -0

112 lines not on this page · raw message

lib/meson.build +1 -0
index 458951054c..73fc64aaf5 100644
@@ -49,6 +49,7 @@ libraries = [
         'lpm',
         'member',
         'pcapng',
+        'capture', # depends on pcapng and bpf
         'power',
         'rawdev',
         'regexdev',
Signature · 1 line
2.53.0
#25 lore raw

PATCH v5 2/4 eal: add --no-capture option

In reply to Stephen Hemminger

Not every deployment wants packet capture available. The capture library registers its telemetry commands from a constructor, before EAL has parsed arguments, so it cannot decline to register; add an EAL option and have the library refuse at use instead.

Capture is reached over the telemetry socket, so --no-telemetry implies --no-capture.

The option is per-process like --no-telemetry: a secondary started with it refuses to attach callbacks, and the primary treats that refusal as a configured choice rather than an error.

---
 doc/guides/linux_gsg/eal_args.include.rst |  4 ++++
 doc/guides/prog_guide/capture_lib.rst     |  3 +++
 lib/capture/capture.c                     |  5 +++++
 lib/capture/multiproc.c                   | 11 ++++++++---
 lib/eal/common/eal_common_config.c        |  7 +++++++
 lib/eal/common/eal_common_options.c       |  3 +++
 lib/eal/common/eal_internal_cfg.h         |  1 +
 lib/eal/common/eal_option_list.h          |  1 +
 lib/eal/include/rte_eal.h                 |  9 +++++++++
 9 files changed, 41 insertions(+), 3 deletions(-)
doc/guides/linux_gsg/eal_args.include.rst +4 -0
index 32c24c8e41..7925084c5c 100644
@@ -293,6 +293,10 @@ Other options
 
     Disable telemetry.
 
+*   ``--no-capture``:
+
+    Disable packet capture. Implied by ``--no-telemetry``.
+
 *   ``--force-max-simd-bitwidth=<val>``:
 
     Specify the maximum SIMD bitwidth size to handle. This limits which vector paths,
doc/guides/prog_guide/capture_lib.rst +3 -0
index 43823ffc87..bafa194fd4 100644
@@ -67,6 +67,9 @@ Requirements
   commands if the call does not work at startup, so capture is simply
   unavailable rather than unsafe.
 
+* Capture can be refused at runtime with the ``--no-capture`` EAL option,
+  which is also implied by ``--no-telemetry``.
+
 Telemetry commands
 ------------------
 
lib/capture/capture.c +5 -0
index 62b95c9de4..af5800017f 100644
@@ -384,6 +384,11 @@ capture_start_req(const char *cmd, const char *params, struct rte_tel_data *d)
 		return -1;
 	}
 
+	if (!rte_eal_has_capture()) {
+		capture_err(d, "capture disabled by --no-capture");
+		return 0;
+	}
+
 	/* Note: params is const so need non-const copy for parsing
 	 * Alternative would be to change telemetry to allow this.
 	 */
lib/capture/multiproc.c +8 -3
index ab29710210..9de9d8117e 100644
@@ -70,6 +70,10 @@ capture_mp_attach(struct capture *cap)
 	struct rte_eth_dev_info dev_info;
 	uint16_t num_queues;
 
+	/* each process decides for itself */
+	if (!rte_eal_has_capture())
+		return -EPERM;
+
 	if (rte_eth_dev_info_get(cap->port_id, &dev_info) < 0)
 		return -EINVAL;
 
@@ -223,10 +227,11 @@ capture_mp_broadcast(struct capture *cap, enum capture_mp_op op)
 			= (const struct capture_mp_response *)mp_reply.msgs[i].param;
 
 		/*
-		 * A secondary that has no callbacks to detach replies ENOENT,
-		 * which happens whenever it was not polling this port.
+		 * ENOENT: nothing to detach, it was not polling this port.
+		 * EPERM: started with --no-capture, which is not an error.
 		 */
-		if (resp->err != 0 && resp->err != -ENOENT) {
+		if (resp->err != 0 && resp->err != -ENOENT &&
+		    resp->err != -EPERM) {
 			CAPTURE_LOG(ERR, "Secondary could not %s capture: %s",
 				    op == CAPTURE_MP_START ? "start" : "stop",
 				    rte_strerror(-resp->err));
lib/eal/common/eal_common_config.c +7 -0
index e2e69a75fb..953a5f7ef8 100644
@@ -109,3 +109,10 @@ rte_eal_has_pci(void)
 {
 	return !internal_config.no_pci;
 }
+
+RTE_EXPORT_SYMBOL(rte_eal_has_capture)
+int
+rte_eal_has_capture(void)
+{
+	return !internal_config.no_capture;
+}
lib/eal/common/eal_common_options.c +3 -0
index b2c0744447..3c347e1a01 100644
@@ -2350,6 +2350,9 @@ eal_parse_args(void)
 		int_cfg->no_shconf = 1;
 	if (args.no_telemetry)
 		int_cfg->no_telemetry = 1;
+	/* capture is reached over the telemetry socket, so it goes with it */
+	if (args.no_capture || args.no_telemetry)
+		int_cfg->no_capture = 1;
 	if (args.match_allocations)
 		int_cfg->match_allocations = 1;
 	if (args.create_uio_dev)
lib/eal/common/eal_internal_cfg.h +1 -0
index 07cd35167d..27e3a7990f 100644
@@ -109,6 +109,7 @@ struct internal_config {
 	volatile unsigned int init_complete;
 	/**< indicates whether EAL has completed initialization */
 	unsigned int no_telemetry; /**< true to disable Telemetry */
+	unsigned int no_capture; /**< true to disable packet capture */
 	struct simd_bitwidth max_simd_bitwidth;
 	/**< max simd bitwidth path to use */
 	size_t huge_worker_stack_size; /**< worker thread stack size */
lib/eal/common/eal_option_list.h +1 -0
index b72f243cc6..c8a1665d44 100644
@@ -53,6 +53,7 @@ STR_ARG("--memory-channels", "-n", "Number of memory channels per socket", memor
 STR_ARG("--memory-ranks", "-r", "Force number of memory ranks (don't detect)", memory_ranks)
 STR_ARG("--memory-size", "-m", "Total size of memory to allocate initially", memory_size)
 BOOL_ARG("--no-auto-probing", "-A", "Do not probe any devices unless some -a option is set", no_auto_probing)
+BOOL_ARG("--no-capture", NULL, "Disable packet capture", no_capture)
 BOOL_ARG("--no-hpet", NULL, "Disable HPET timer", no_hpet)
 BOOL_ARG("--no-huge", NULL, "Disable hugetlbfs support", no_huge)
 BOOL_ARG("--no-pci", NULL, "Disable all PCI devices", no_pci)
lib/eal/include/rte_eal.h +9 -0
index 7241f3be5d..ded7be9196 100644
@@ -392,6 +392,15 @@ int rte_eal_has_hugepages(void);
  */
 int rte_eal_has_pci(void);
 
+/**
+ * Whether packet capture is allowed.
+ * Disabled by the --no-capture and --no-telemetry options.
+ *
+ * @return
+ *   Nonzero if capture is enabled.
+ */
+int rte_eal_has_capture(void);
+
 /**
  * Whether the EAL was asked to create UIO device.
  *
Signature · 1 line
2.53.0
#26 lore raw

PATCH v5 3/4 test: add test for capture hooks

In reply to Stephen Hemminger

Provide tests to exercise telemetry based packet capture.

---
 MAINTAINERS             |   1 +
 app/test/meson.build    |   1 +
 app/test/test_capture.c | 688 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 690 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +1 -0
index 71af3542e6..843fc3a6c6 100644
@@ -1724,6 +1724,7 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: app/test/test_capture.c
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
 F: app/test/test_pdump.*
app/test/meson.build +1 -0
index 9805cf5bee..72c4903f30 100644
@@ -41,6 +41,7 @@ source_file_deps = {
     'test_bpf.c': ['bpf', 'net'],
     'test_bpf_validate.c': ['bpf'],
     'test_byteorder.c': [],
+    'test_capture.c': ['net_null', 'net', 'ethdev', 'bus_vdev', 'capture'],
     'test_cfgfile.c': ['cfgfile'],
     'test_cksum.c': ['net'],
     'test_cksum_perf.c': ['net'],
app/test/test_capture.c new file +688 -0

688 lines not on this page · raw message

Signature · 1 line
2.53.0
#27 lore raw

PATCH v5 4/4 usertools: add script for wireshark capture

In reply to Stephen Hemminger

Provide glue executable that wireshark can use to access telemetry based packet capture. It is a C program so that it can be installed setuid if desired and it is standalone and does not depend on any DPDK libraries or infrastructure.

It is dual licensed because it maybe desirable to put this in wireshark repository later.

See https://www.wireshark.org/docs/man-pages/extcap.html

---
 MAINTAINERS                            |    3 +
 doc/guides/prog_guide/capture_lib.rst  |    8 +
 doc/guides/rel_notes/release_26_11.rst |    1 +
 doc/guides/tools/index.rst             |    1 +
 doc/guides/tools/wireshark_extcap.rst  |  203 +++++
 usertools/dpdk-wireshark-extcap.c      | 1131 ++++++++++++++++++++++++
 usertools/meson.build                  |   23 +
 7 files changed, 1370 insertions(+)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100644 usertools/dpdk-wireshark-extcap.c
MAINTAINERS +3 -0
index 843fc3a6c6..a1a053c954 100644
@@ -1724,6 +1724,7 @@ Packet capture
 M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
+F: doc/guides/prog_guide/capture_lib.rst
 F: app/test/test_capture.c
 F: lib/pdump/
 F: doc/guides/prog_guide/pdump_lib.rst
@@ -1735,6 +1736,8 @@ F: app/pdump/
 F: doc/guides/tools/pdump.rst
 F: app/dumpcap/
 F: doc/guides/tools/dumpcap.rst
+F: usertools/dpdk-wireshark-extcap.c
+F: doc/guides/tools/wireshark_extcap.rst
 
 
 Packet Framework
doc/guides/prog_guide/capture_lib.rst +8 -0
index bafa194fd4..690f5feeb2 100644
@@ -169,6 +169,14 @@ capture fails to start if the FIFO has no reader::
    --> /ethdev/capture/stop,0
    {"/ethdev/capture/stop": {"status": "stopped"}}
 
+Using Wireshark
+---------------
+
+The ``dpdk-wireshark-extcap`` program presents the ports of a running DPDK
+application as Wireshark capture interfaces, using these telemetry commands
+with a FIFO created by Wireshark as the output.
+See :doc:`../tools/wireshark_extcap`.
+
 Limitations
 -----------
 
doc/guides/rel_notes/release_26_11.rst +1 -0
index 0a43628aed..095e4a9903 100644
@@ -267,6 +267,7 @@ New Features
 * **Added wireshark capture support.**
 
   * New ``capture`` library for packet capture accessed via telemetry API.
+  * Added ``dpdk-wireshark-extcap`` for wireshark external capture integration.
 
 
 Removed Items
doc/guides/tools/index.rst +1 -0
index c6a145a9fe..dccf9a7daa 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     telemetrywatcher
     dmaperf
     flow-perf
doc/guides/tools/wireshark_extcap.rst new file +203 -0

203 lines not on this page · raw message

usertools/dpdk-wireshark-extcap.c new file +1131 -0

1,131 lines not on this page · raw message

usertools/meson.build +23 -0
index 114d0a65b4..c2bc8715a3 100644
@@ -20,3 +20,26 @@ install_subdir(
         'telemetry-endpoints',
         install_dir: 'share/dpdk',
         strip_directory: false)
+
+# Wireshark extcap helper does not depend on anything from DPDK
+# and speaks the telemetry socket protocol directly.
+if not is_windows
+    extcap_cflags = []
+    extcap_deps = []
+
+    cap_dep = dependency('libcap', required: false)
+    if cap_dep.found()
+        extcap_cflags += '-DHAVE_LIBCAP'
+        extcap_deps += cap_dep
+    endif
+
+    executable('dpdk-wireshark-extcap',
+            files('dpdk-wireshark-extcap.c'),
+            # only for the project-wide '-include rte_config.h'
+            include_directories: config_inc,
+            c_args: extcap_cflags,
+            dependencies: extcap_deps,
+            pie: true,
+            install: true,
+            install_dir: 'bin')
+endif
Signature · 1 line
2.53.0
#28 lore raw

Re: [PATCH v5 0/4] wireshark extcap support

In reply to Stephen Hemminger
Quoted 4 lines · On Fri, 16 Oct 2026 15:30:30 -0700 Stephen Hemminger…

This series adds live packet capture from a running DPDK application over the telemetry socket which is usable as a source of Wireshark external capture (https://www.wireshark.org/docs/man-pages/extcap.html)

Quoted 8 lines

Capture is avaliable by default but can be disabled on the command line with --no-capture. It works on Linux and FreeBSD.

How it works:
- The capture library registers telemetry commands (/ethdev/capture/*)
- Callbacks are installed on the specified port/queues to copy packets
- Packets are formatted as pcapng and written to the specified output
- No packet data passes through the telemetry socket itself

I am going to suggest deferring this to 27.03.
Not happy with the security model, and using telemetry as the control channel. It needs to have its own control channel, and the destination file needs to come from the helper not get opened by DPDK process (primary).