Skip to contentSkip to conversation

alternative capture mechanism

RFC In review Stephen Hemminger 2 participants 9 messages Jun 9 – Jun 16

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

cover alternative capture mechanism

This is an RFC for an alternative way to capture packets from a DPDK application. I did brief demo of similar mechanism at DPDK summit but this is more complete. Capture runs in the primary process and is driven entirely over telemetry; no secondary process is involved.

A client asks the application to start capturing and passes it a file descriptor to write to. The application writes pcapng to that descriptor. A Wireshark extcap script is the intended front end, but the control path is just telemetry and the output is just a pipe, so other front ends are possible.

  1/4  telemetry: let a command receive file descriptors from the client
  2/4  capture: the library
  3/4  test: functional test
  4/4  app: the Wireshark extcap script and its documentation

Setup and usage are in doc/guides/tools/wireshark_extcap.rst.

Primary process only for now; secondary-process capture is possible as follow-on. Posting as RFC to get feedback on the approach.

The extcap script is dual licensed (BSD-3-Clause OR GPL-2.0-or-later) as it may be more useful in the Wireshark tree.

Stephen Hemminger (4):
telemetry: allow commands to receive file descriptors
capture: infrastructure wireshark packet capture
test: add test for capture hooks usertools/dpdk-wireshark-extcap.py: script for external capture

 MAINTAINERS                            |   4 +
 app/test/meson.build                   |   1 +
 app/test/test_capture.c                | 365 +++++++++++
 doc/guides/rel_notes/release_26_07.rst |  12 +
 doc/guides/tools/index.rst             |   1 +
 doc/guides/tools/wireshark_extcap.rst  | 155 +++++
 lib/capture/capture.c                  | 821 +++++++++++++++++++++++++
 lib/capture/capture_impl.h             |  56 ++
 lib/capture/filter.c                   | 108 ++++
 lib/capture/meson.build                |  19 +
 lib/meson.build                        |   1 +
 lib/telemetry/rte_telemetry.h          |  66 ++
 lib/telemetry/telemetry.c              | 115 +++-
 usertools/dpdk-wireshark-extcap.py     | 274 +++++++++
 14 files changed, 1986 insertions(+), 12 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-wireshark-extcap.py
Signature · 1 line
2.53.0
#1 lore raw

RFC 1/4 telemetry: allow commands to receive file descriptors

Add rte_telemetry_register_cmd_fd_arg() to register a command whose callback also receives file descriptors passed by the client as SCM_RIGHTS ancillary data. The callback owns the descriptors and must close them.

This lets a client open a file itself and hand the descriptor to the primary process, so DPDK never opens the path. That avoids path and permission problems and works across container filesystem namespaces.

Existing commands and clients are unaffected. If unsolicited file descriptor is passed, it is closed.

---
 doc/guides/rel_notes/release_26_07.rst |   5 ++
 lib/telemetry/rte_telemetry.h          |  66 ++++++++++++++
 lib/telemetry/telemetry.c              | 115 ++++++++++++++++++++++---
 3 files changed, 174 insertions(+), 12 deletions(-)
doc/guides/rel_notes/release_26_07.rst +5 -0
index b5285af5fe..d7a2df88c1 100644
@@ -141,6 +141,11 @@ New Features
   Added AGENTS.md file for AI review
   and supporting scripts to review patches and documentation.
 
+* **Added telemetry support for passing file descriptors.**
+
+  Add experimental telemetry callback ``rte_telemetry_register_cmd_fd_arg()``
+  to allow command to receive file descriptors passed by client.
+
 
 Removed Items
 -------------
lib/telemetry/rte_telemetry.h +66 -0

78 lines not on this page · raw message

lib/telemetry/telemetry.c +103 -12

180 lines not on this page · raw message

Signature · 1 line
2.53.0
#2 lore raw

Re: [RFC 1/4] telemetry: allow commands to receive file descriptors

Quoted 5 lines · Stephen Hemminger

Add rte_telemetry_register_cmd_fd_arg() to register a command whose callback also receives file descriptors passed by the client as SCM_RIGHTS ancillary data. The callback owns the descriptors and must close them.

Quoted 7 lines

This lets a client open a file itself and hand the descriptor to the primary process, so DPDK never opens the path. That avoids path and permission problems and works across container filesystem namespaces.

Existing commands and clients are unaffected. If unsolicited file descriptor is passed, it is closed.

This scheme seems reasonable in general. My only concern is whether the lack of potential windows support is an issue? For regular telemetry, there was always the option of a windows implementation using regular TCP/UDP/SCTP sockets bound to localhost. However, AFAIK there is no windows implementation of anything that supports file descriptors or handles between processes.

Some other pieces of feedback inline below.

/Bruce

Quoted 52 lines
---
 doc/guides/rel_notes/release_26_07.rst |   5 ++
 lib/telemetry/rte_telemetry.h          |  66 ++++++++++++++
 lib/telemetry/telemetry.c              | 115 ++++++++++++++++++++++---
 3 files changed, 174 insertions(+), 12 deletions(-)
doc/guides/rel_notes/release_26_07.rst +5 -0
index b5285af5fe..d7a2df88c1 100644
@@ -141,6 +141,11 @@ New Features
   Added AGENTS.md file for AI review
   and supporting scripts to review patches and documentation.
 
+* **Added telemetry support for passing file descriptors.**
+
+  Add experimental telemetry callback ``rte_telemetry_register_cmd_fd_arg()``
+  to allow command to receive file descriptors passed by client.
+
 
 Removed Items
 -------------
lib/telemetry/rte_telemetry.h +21 -0
index 0a58e518f7..3e32d2902b 100644
@@ -325,6 +325,37 @@ typedef int (*telemetry_cb)(const char *cmd, const char *params,
 typedef int (*telemetry_arg_cb)(const char *cmd, const char *params, void *arg,
 		struct rte_tel_data *info);
 
+/**
+ * This telemetry callback is used when registering a telemetry command with
+ * rte_telemetry_register_cmd_fd_arg().
+ *
+ * It behaves like telemetry_arg_cb, but additionally receives any file
+ * descriptors the client passed alongside the command as SCM_RIGHTS ancillary
+ * data. The callback takes ownership of these descriptors and is responsible
+ * for closing them.
+ *
+ * @param cmd
+ *   The cmd that was requested by the client.
+ * @param params
+ *   Contains data required by the callback function.
+ * @param arg
+ *   The opaque value that was passed to rte_telemetry_register_cmd_fd_arg().
+ * @param fds
+ *   Array of file descriptors received from the client. May be NULL when
+ *   n_fds is zero.
+ * @param n_fds
+ *   Number of file descriptors in the fds array.
+ * @param info

lib/telemetry/rte_telemetry.h typedef int (*telemetry_cb)(const char *cmd, const char *params, · line 358

Quoted 10 lines
lib/telemetry/rte_telemetry.h +10 -0
+ *   The information to be returned to the caller.
+ *
+ * @return
+ *   Length of buffer used on success.
+ * @return
+ *   Negative integer on error.
+ */
+typedef int (*telemetry_fd_cb)(const char *cmd, const char *params, void *arg,
+		const int *fds, unsigned int n_fds, struct rte_tel_data *info);
+

Do we anticipate in future having callbacks taking more than one FD? Would it not be simpler just to a single fd parameter (which is -1 on no fd passed).

Quoted 32 lines
lib/telemetry/rte_telemetry.h +25 -0
 /**
  * Used when registering a command and callback function with telemetry.
  *
@@ -368,6 +399,41 @@ __rte_experimental
 int
 rte_telemetry_register_cmd_arg(const char *cmd, telemetry_arg_cb fn, void *arg, const char *help);
 
+/**
+ * Register a command and a file-descriptor-aware callback with telemetry.
+ *
+ * The callback is invoked like rte_telemetry_register_cmd_arg(), but also
+ * receives any file descriptors the client passed alongside the command as
+ * SCM_RIGHTS ancillary data. This lets a client open a file (for example a
+ * capture output file) itself and hand the descriptor to the DPDK process,
+ * which never opens the path - avoiding path and permission concerns and
+ * working across container filesystem namespaces.
+ *
+ * Descriptors sent to a command registered with rte_telemetry_register_cmd()
+ * or rte_telemetry_register_cmd_arg() are rejected and the connection is
+ * closed.
+ *
+ * @param cmd
+ *   The command to register with telemetry.
+ * @param fn
+ *   Callback function to be called when the command is requested.
+ * @param arg
+ *   An opaque value that will be passed to the callback function.
+ * @param help
+ *   Help text for the command.
+ *
+ * @return
+ *   0 on success.

lib/telemetry/rte_telemetry.h __rte_experimental · line 436

Quoted 10 lines
lib/telemetry/rte_telemetry.h +10 -0
+ * @return
+ *   -EINVAL for invalid parameters failure.
+ * @return
+ *   -ENOMEM for mem allocation failure.
+ */
+__rte_experimental
+int
+rte_telemetry_register_cmd_fd_arg(const char *cmd, telemetry_fd_cb fn, void *arg,
+		const char *help);
+

Do we want to make this experimental for later stabilization, or is this an API that is best kept as internal-only? I'd tend towards keeping it internal-only, rather than allowing apps to define callbacks which take FDs.

Quoted 8 lines
lib/telemetry/rte_telemetry.h +0 -0
 /**
  * @internal
  * Free a container that has memory allocated.
lib/telemetry/telemetry.c +0 -0
index b109d076d4..30d3ae3a13 100644

lib/telemetry/telemetry.c line 34

Quoted 6 lines
lib/telemetry/telemetry.c +2 -0
@@ -29,6 +29,8 @@
 #define MAX_CMD_LEN 56
 #define MAX_OUTPUT_LEN (1024 * 16)
 #define MAX_CONNECTIONS 10
+/* Maximum number of file descriptors a client may pass with one command. */
+#define MAX_FDS 8
 

As above, do we really need multiple FDs?

Quoted 167 lines
lib/telemetry/telemetry.c +90 -12
 #ifndef RTE_EXEC_ENV_WINDOWS
 static void *
@@ -39,6 +41,7 @@ struct cmd_callback {
 	char cmd[MAX_CMD_LEN];
 	telemetry_cb fn;
 	telemetry_arg_cb fn_arg;
+	telemetry_fd_cb fn_fd;
 	void *arg;
 	char help[RTE_TEL_MAX_STRING_LEN];
 };
@@ -72,15 +75,15 @@ static RTE_ATOMIC(uint16_t) v2_clients;
 #endif /* !RTE_EXEC_ENV_WINDOWS */
 
 static int
-register_cmd(const char *cmd, const char *help,
-	     telemetry_cb fn, telemetry_arg_cb fn_arg, void *arg)
+register_cmd(const char *cmd, const char *help, telemetry_cb fn,
+	     telemetry_arg_cb fn_arg, telemetry_fd_cb fn_fd, void *arg)
 {
 	struct cmd_callback *new_callbacks;
 	const char *cmdp = cmd;
 	int i = 0;
 
-	if (strlen(cmd) >= MAX_CMD_LEN || (fn == NULL && fn_arg == NULL) || cmd[0] != '/'
-			|| strlen(help) >= RTE_TEL_MAX_STRING_LEN)
+	if (strlen(cmd) >= MAX_CMD_LEN || (fn == NULL && fn_arg == NULL && fn_fd == NULL)
+			|| cmd[0] != '/' || strlen(help) >= RTE_TEL_MAX_STRING_LEN)
 		return -EINVAL;
 
 	while (*cmdp != '\0') {
@@ -107,6 +110,7 @@ register_cmd(const char *cmd, const char *help,
 	strlcpy(callbacks[i].cmd, cmd, MAX_CMD_LEN);
 	callbacks[i].fn = fn;
 	callbacks[i].fn_arg = fn_arg;
+	callbacks[i].fn_fd = fn_fd;
 	callbacks[i].arg = arg;
 	strlcpy(callbacks[i].help, help, RTE_TEL_MAX_STRING_LEN);
 	num_callbacks++;
@@ -119,14 +123,22 @@ RTE_EXPORT_SYMBOL(rte_telemetry_register_cmd)
 int
 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help)
 {
-	return register_cmd(cmd, help, fn, NULL, NULL);
+	return register_cmd(cmd, help, fn, NULL, NULL, NULL);
 }
 
 RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_telemetry_register_cmd_arg, 24.11)
 int
 rte_telemetry_register_cmd_arg(const char *cmd, telemetry_arg_cb fn, void *arg, const char *help)
 {
-	return register_cmd(cmd, help, NULL, fn, arg);
+	return register_cmd(cmd, help, NULL, fn, NULL, arg);
+}
+
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_telemetry_register_cmd_fd_arg, 26.07)
+int
+rte_telemetry_register_cmd_fd_arg(const char *cmd, telemetry_fd_cb fn, void *arg,
+		const char *help)
+{
+	return register_cmd(cmd, help, NULL, NULL, fn, arg);
 }
 
 #ifndef RTE_EXEC_ENV_WINDOWS
@@ -368,13 +380,70 @@ output_json(const char *cmd, const struct rte_tel_data *d, int s)
 		TMTY_LOG_LINE(ERR, "Error writing to socket: %s", strerror(errno));
 }
 
+/*
+ * Receive a command and any file descriptors the client passed alongside it
+ * as SCM_RIGHTS ancillary data. The payload length is returned (0 if the
+ * client sent an empty message or closed the connection, negative on error).
+ * Descriptors that arrive are returned in fds[]/n_fds and are owned by the
+ * caller. MSG_CTRUNC means more descriptors were sent than the control buffer
+ * could hold; *ctrunc is set so the caller can reject the command, but the
+ * descriptors that did fit are still returned so they can be closed rather
+ * than leaked.
+ */
+static int
+recv_with_fds(int s, char *buf, size_t buf_len, int *fds, unsigned int *n_fds,
+	      bool *ctrunc)
+{
+	char cmsgbuf[CMSG_SPACE(sizeof(int) * MAX_FDS)];
+	struct iovec iov = { .iov_base = buf, .iov_len = buf_len };
+	struct msghdr msg = {
+		.msg_iov = &iov,
+		.msg_iovlen = 1,
+		.msg_control = cmsgbuf,
+		.msg_controllen = sizeof(cmsgbuf),
+	};
+	struct cmsghdr *cmsg;
+	int bytes;
+
+	*n_fds = 0;
+	*ctrunc = false;
+
+	bytes = recvmsg(s, &msg, 0);
+	if (bytes < 0)
+		return bytes;
+
+	if (msg.msg_flags & MSG_CTRUNC)
+		*ctrunc = true;
+
+	for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+		if (cmsg->cmsg_level != SOL_SOCKET || cmsg->cmsg_type != SCM_RIGHTS)
+			continue;
+		*n_fds = (cmsg->cmsg_len - CMSG_LEN(0)) / sizeof(int);
+		memcpy(fds, CMSG_DATA(cmsg), *n_fds * sizeof(int));
+		break;
+	}
+	return bytes;
+}
+
 static void
-perform_command(const struct cmd_callback *cb, const char *cmd, const char *param, int s)
+close_fds(const int *fds, unsigned int n_fds)
+{
+	unsigned int i;
+
+	for (i = 0; i < n_fds; i++)
+		close(fds[i]);
+}
+
+static void
+perform_command(const struct cmd_callback *cb, const char *cmd, const char *param,
+		const int *fds, unsigned int n_fds, int s)
 {
 	struct rte_tel_data data = {0};
 	int ret;
 
-	if (cb->fn_arg != NULL)
+	if (cb->fn_fd != NULL)
+		ret = cb->fn_fd(cmd, param, cb->arg, fds, n_fds, &data);
+	else if (cb->fn_arg != NULL)
 		ret = cb->fn_arg(cmd, param, cb->arg, &data);
 	else
 		ret = cb->fn(cmd, param, &data);
@@ -412,8 +481,11 @@ client_handler(void *sock_id)
 	}
 
 	/* receive data is not null terminated */
-	int bytes = read(s, buffer, sizeof(buffer) - 1);
-	while (bytes > 0) {
+	int fds[MAX_FDS];
+	unsigned int n_fds = 0;
+	bool ctrunc = false;
+	int bytes = recv_with_fds(s, buffer, sizeof(buffer) - 1, fds, &n_fds, &ctrunc);
+	while (bytes > 0 || (bytes == 0 && n_fds > 0)) {
 		buffer[bytes] = 0;
 		const char *cmd = strtok(buffer, ",");
 		const char *param = strtok(NULL, "\0");
@@ -429,9 +501,28 @@ client_handler(void *sock_id)
 				}
 			rte_spinlock_unlock(&callback_sl);
 		}
-		perform_command(&cb, cmd, param, s);
 
-		bytes = read(s, buffer, sizeof(buffer) - 1);
+		/*
+		 * File descriptors go only to a command that registered to
+		 * receive them. A command that did not, or a truncated control
+		 * message, is a client error: close the descriptors and drop the
+		 * connection rather than silently discarding them.
+		 */
+		if (n_fds > 0 && (cb.fn_fd == NULL || ctrunc)) {
+			TMTY_LOG_LINE(ERR,
+				"Closing connection: %u file descriptor(s) passed to '%s'%s",
+				n_fds, cmd ? cmd : "(none)",

lib/telemetry/telemetry.c client_handler(void *sock_id) · line 524

Quoted 10 lines
lib/telemetry/telemetry.c +10 -0
+				ctrunc ? " (truncated)" : " which does not accept them");
+			close_fds(fds, n_fds);
+			break;
+		}
+
+		/* an fd-aware callback takes ownership of the descriptors */
+		perform_command(&cb, cmd, param, fds, n_fds, s);
+
+		n_fds = 0;
+		ctrunc = false;

the receive function always resets this to false anyway, so you may be able to omit this line (assuming compiler doesn't complain).

Quoted 7 lines
lib/telemetry/telemetry.c +1 -0
+		bytes = recv_with_fds(s, buffer, sizeof(buffer) - 1, fds, &n_fds, &ctrunc);
 	}
 exit:
 	close(s);
Signature · 1 line
2.53.0
#3 lore raw

Re: [RFC 1/4] telemetry: allow commands to receive file descriptors

Quoted 21 lines · On Tue, 16 Jun 2026 13:32:28 +0100 Bruce Richardson…
Quoted 5 lines · Stephen Hemminger

Add rte_telemetry_register_cmd_fd_arg() to register a command whose callback also receives file descriptors passed by the client as SCM_RIGHTS ancillary data. The callback owns the descriptors and must close them.

Quoted 7 lines

This lets a client open a file itself and hand the descriptor to the primary process, so DPDK never opens the path. That avoids path and permission problems and works across container filesystem namespaces.

Existing commands and clients are unaffected. If unsolicited file descriptor is passed, it is closed.

This scheme seems reasonable in general. My only concern is whether the lack of potential windows support is an issue? For regular telemetry, there was always the option of a windows implementation using regular TCP/UDP/SCTP sockets bound to localhost. However, AFAIK there is no windows implementation of anything that supports file descriptors or handles between processes.

Quoted 3 lines

Some other pieces of feedback inline below.

/Bruce

I have new version (testing) that passes filename as parameter. That should work without the fd passing.

#4 lore raw

RFC 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/rel_notes/release_26_07.rst |   7 +
 lib/capture/capture.c                  | 821 +++++++++++++++++++++++++
 lib/capture/capture_impl.h             |  56 ++
 lib/capture/filter.c                   | 108 ++++
 lib/capture/meson.build                |  19 +
 lib/meson.build                        |   1 +
 7 files changed, 1013 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 4a68a19b32..dd359d956e 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/rel_notes/release_26_07.rst +7 -0
index d7a2df88c1..309a6078bd 100644
@@ -146,6 +146,13 @@ New Features
   Add experimental telemetry callback ``rte_telemetry_register_cmd_fd_arg()``
   to allow command to receive file descriptors passed by client.
 
+* **Added packet capture library.**
+
+  Added a new ``capture`` library which provides a mechanism via telemetry
+  interface for capturing packets to a file descriptor. This mechanism
+  is used by the new ``dpdk-wireshark-extcap.py`` script which provides
+  seamless integration with Wireshark.
+
 
 Removed Items
 -------------
lib/capture/capture.c new file +821 -0

821 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
#5 lore raw

RFC 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 | 365 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 367 insertions(+)
 create mode 100644 app/test/test_capture.c
MAINTAINERS +1 -0
index dd359d956e..ff5f31c770 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 61024125a7..e1806ec4ca 100644
@@ -137,6 +137,7 @@ source_file_deps = {
     'test_net_ip6.c': ['net'],
     'test_pcapng.c': ['net_null', 'net', 'ethdev', 'pcapng', 'bus_vdev'],
     'test_pdcp.c': ['eventdev', 'pdcp', 'net', 'timer', 'security'],
+    'test_capture.c': ['net_ring', 'net', 'ethdev', 'bus_vdev', 'telemetry'],
     'test_pdump.c': ['pdump'] + sample_packet_forward_deps,
     'test_per_lcore.c': [],
     'test_pflock.c': [],
app/test/test_capture.c new file +365 -0

365 lines not on this page · raw message

Signature · 1 line
2.53.0
#6 lore raw

RFC 4/4 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

Also add MAINTAINERS and release note.

---
 MAINTAINERS                           |   2 +
 doc/guides/tools/index.rst            |   1 +
 doc/guides/tools/wireshark_extcap.rst | 155 +++++++++++++++
 usertools/dpdk-wireshark-extcap.py    | 274 ++++++++++++++++++++++++++
 4 files changed, 432 insertions(+)
 create mode 100644 doc/guides/tools/wireshark_extcap.rst
 create mode 100755 usertools/dpdk-wireshark-extcap.py
MAINTAINERS +2 -0
index ff5f31c770..7cb8782910 100644
@@ -1725,6 +1725,8 @@ M: Reshma Pattan <[email protected]>
 M: Stephen Hemminger <[email protected]>
 F: lib/capture/
 F: app/test/test_capture.c
+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.*
doc/guides/tools/index.rst +1 -0
index 8ec429ec53..580c7d28b1 100644
@@ -14,6 +14,7 @@ DPDK Tools User Guides
     pmdinfo
     dumpcap
     pdump
+    wireshark_extcap
     dmaperf
     flow-perf
     securityperf
doc/guides/tools/wireshark_extcap.rst new file +155 -0

155 lines not on this page · raw message

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

274 lines not on this page · raw message

Signature · 1 line
2.53.0
#7 lore raw
In reply to Stephen Hemminger
Quoted 16 lines · Stephen Hemminger

This is an RFC for an alternative way to capture packets from a DPDK application. I did brief demo of similar mechanism at DPDK summit but this is more complete. Capture runs in the primary process and is driven entirely over telemetry; no secondary process is involved.

A client asks the application to start capturing and passes it a file descriptor to write to. The application writes pcapng to that descriptor. A Wireshark extcap script is the intended front end, but the control path is just telemetry and the output is just a pipe, so other front ends are possible.

  1/4  telemetry: let a command receive file descriptors from the client
  2/4  capture: the library
  3/4  test: functional test
  4/4  app: the Wireshark extcap script and its documentation
Quoted 8 lines

Setup and usage are in doc/guides/tools/wireshark_extcap.rst.

Primary process only for now; secondary-process capture is possible as follow-on. Posting as RFC to get feedback on the approach.

The extcap script is dual licensed (BSD-3-Clause OR GPL-2.0-or-later) as it may be more useful in the Wireshark tree.

One concern I have though - does this cause system-calls to be made in the fast-path because we are writting to a passed in FD? For performance reasons, would it not be better to use a memory buffer for this, thereby avoiding syscalls? For example, rather than passing in an FD to telemetry, we could pass in a key to be passed to shmget (going old-school!), or name parameter for shm_open. Thereafter with the memory buffer we can use a circular ring or similar to pass the data from app to client.

/Bruce

Quoted 32 lines

Stephen Hemminger (4):
telemetry: allow commands to receive file descriptors
capture: infrastructure wireshark packet capture
test: add test for capture hooks usertools/dpdk-wireshark-extcap.py: script for external capture

 MAINTAINERS                            |   4 +
 app/test/meson.build                   |   1 +
 app/test/test_capture.c                | 365 +++++++++++
 doc/guides/rel_notes/release_26_07.rst |  12 +
 doc/guides/tools/index.rst             |   1 +
 doc/guides/tools/wireshark_extcap.rst  | 155 +++++
 lib/capture/capture.c                  | 821 +++++++++++++++++++++++++
 lib/capture/capture_impl.h             |  56 ++
 lib/capture/filter.c                   | 108 ++++
 lib/capture/meson.build                |  19 +
 lib/meson.build                        |   1 +
 lib/telemetry/rte_telemetry.h          |  66 ++
 lib/telemetry/telemetry.c              | 115 +++-
 usertools/dpdk-wireshark-extcap.py     | 274 +++++++++
 14 files changed, 1986 insertions(+), 12 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-wireshark-extcap.py
Signature · 1 line
2.53.0
#8 lore raw
Quoted 34 lines · On Tue, 16 Jun 2026 13:37:34 +0100 Bruce Richardson…
Quoted 16 lines · Stephen Hemminger

This is an RFC for an alternative way to capture packets from a DPDK application. I did brief demo of similar mechanism at DPDK summit but this is more complete. Capture runs in the primary process and is driven entirely over telemetry; no secondary process is involved.

A client asks the application to start capturing and passes it a file descriptor to write to. The application writes pcapng to that descriptor. A Wireshark extcap script is the intended front end, but the control path is just telemetry and the output is just a pipe, so other front ends are possible.

  1/4  telemetry: let a command receive file descriptors from the client
  2/4  capture: the library
  3/4  test: functional test
  4/4  app: the Wireshark extcap script and its documentation
Quoted 8 lines

Setup and usage are in doc/guides/tools/wireshark_extcap.rst.

Primary process only for now; secondary-process capture is possible as follow-on. Posting as RFC to get feedback on the approach.

The extcap script is dual licensed (BSD-3-Clause OR GPL-2.0-or-later) as it may be more useful in the Wireshark tree.

One concern I have though - does this cause system-calls to be made in the fast-path because we are writting to a passed in FD? For performance reasons, would it not be better to use a memory buffer for this, thereby avoiding syscalls? For example, rather than passing in an FD to telemetry, we could pass in a key to be passed to shmget (going old-school!), or name parameter for shm_open. Thereafter with the memory buffer we can use a circular ring or similar to pass the data from app to client.

Quoted 1 line

/Bruce

The system calls are contained inside the thread spawned when capture starts. The flow is:

         callback -> ring -> capture thread -> FIFO -> wireshark