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

[Stephen Hemminger <stephen@networkplumber.org>]

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.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 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

diff --git a/MAINTAINERS b/MAINTAINERS
index 5ce969d02f..e682823df9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1722,6 +1722,7 @@ M: Reshma Pattan <reshma.pattan@intel.com>
 M: Stephen Hemminger <stephen@networkplumber.org>
 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
diff --git a/doc/guides/rel_notes/release_26_11.rst b/doc/guides/rel_notes/release_26_11.rst
index 9835807fcc..6590899585 100644
--- a/doc/guides/rel_notes/release_26_11.rst
+++ b/doc/guides/rel_notes/release_26_11.rst
@@ -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
diff --git a/usertools/dpdk-dumpcap.py b/usertools/dpdk-dumpcap.py
new file mode 100755
index 0000000000..bdec55964a
--- /dev/null
+++ b/usertools/dpdk-dumpcap.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""
+dpdk-dumpcap: capture packets from a running DPDK primary process.
+
+A tcpdump/dumpcap-style front end for the DPDK 'capture' library. Unlike the
+legacy secondary-process dpdk-dumpcap (which used pdump and required the primary
+to initialise the capture framework), this drives the primary directly over its
+telemetry socket: the primary opens the output file itself and writes pcapng
+into it. It works with any primary that links lib/capture; no application
+changes are needed.
+
+Examples:
+    dpdk-dumpcap --list-interfaces
+    dpdk-dumpcap -i 0 -w /tmp/port0.pcapng
+    dpdk-dumpcap -i 0 -c 100 -f 'tcp port 80'
+"""
+
+import argparse
+import json
+import os
+import signal
+import socket
+import sys
+import tempfile
+import time
+
+TELEMETRY_SOCKET = "dpdk_telemetry.v2"
+CAPTURE_START_CMD = "/ethdev/capture/start"
+CAPTURE_STOP_CMD = "/ethdev/capture/stop"
+CAPTURE_STATS_CMD = "/ethdev/capture/stats"
+ETHDEV_LIST = "/ethdev/list"
+ETHDEV_INFO = "/ethdev/info"
+DEFAULT_SNAPLEN = 262144
+COUNT_POLL_INTERVAL = 0.1  # fast stats poll cadence when -c is set
+POLL_TICK = 0.5  # loop wake granularity; bounds Ctrl-C latency when idle
+DEFAULT_STATS_INTERVAL = 0.5  # seconds between liveness updates
+
+
+# --- DPDK runtime directory / socket discovery ---------------------------
+
+
+def dpdk_dir():
+    override = os.environ.get("DPDK_EXTCAP_PATH")
+    if override:
+        return override
+    base = (
+        "/var/run" if os.geteuid() == 0 else os.environ.get("XDG_RUNTIME_DIR", "/tmp")
+    )
+    return os.path.join(base, "dpdk")
+
+
+def socket_path(prefix):
+    return os.path.join(dpdk_dir(), prefix, TELEMETRY_SOCKET)
+
+
+def list_prefixes():
+    """Yield (prefix, path) for each DPDK telemetry socket found."""
+    root = dpdk_dir()
+    try:
+        entries = os.listdir(root)
+    except FileNotFoundError:
+        return
+    except PermissionError:
+        sys.stderr.write(
+            f"cannot read {root}: permission denied. The DPDK runtime directory "
+            "is mode 0700, so capture must run as the same user as the DPDK "
+            "application, or set DPDK_EXTCAP_PATH.\n"
+        )
+        return
+    for prefix in sorted(entries):
+        path = os.path.join(root, prefix, TELEMETRY_SOCKET)
+        if os.path.exists(path):
+            yield prefix, path
+
+
+def resolve_prefix(requested):
+    """Pick the file-prefix to talk to. If one was requested, use it; else use
+    the sole running prefix, or error if there are zero or several."""
+    prefixes = [p for p, _ in list_prefixes()]
+    if requested is not None:
+        if requested not in prefixes:
+            raise SystemExit(f"no DPDK process with file-prefix '{requested}'")
+        return requested
+    if not prefixes:
+        raise SystemExit("no running DPDK process found")
+    if len(prefixes) > 1:
+        raise SystemExit(
+            "multiple DPDK processes running; select one with --file-prefix: "
+            + ", ".join(prefixes)
+        )
+    return prefixes[0]
+
+
+# --- Telemetry transport -------------------------------------------------
+
+
+class Telemetry:
+    """Minimal client for the DPDK v2 telemetry socket (SOCK_SEQPACKET)."""
+
+    def __init__(self, path):
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_SEQPACKET)
+        self.sock.connect(path)
+        info = json.loads(self.sock.recv(1024).decode())
+        self.max_output_len = info.get("max_output_len", 16384)
+
+    def command(self, cmd):
+        self.sock.send(cmd.encode())
+        reply = self.sock.recv(self.max_output_len)
+        if not reply:
+            return None
+        return json.loads(reply.decode())
+
+    def close(self):
+        self.sock.close()
+
+
+# --- operations ----------------------------------------------------------
+
+
+def port_name(tel, port):
+    """Device name for a port via /ethdev/info, or 'port<N>' if unreadable.
+    For a physical port this is the PCI address; for a vdev, the vdev name."""
+    try:
+        reply = tel.command(f"{ETHDEV_INFO},{port}")
+    except OSError:
+        reply = None
+    info = (reply or {}).get(ETHDEV_INFO) or {}
+    return info.get("name") or f"port{port}"
+
+
+def list_interfaces():
+    """List ports as '<port>. <name>', matching Wireshark/C dpdk-dumpcap -D.
+    Port ids are per-primary; if several primaries run, capture disambiguates
+    with --file-prefix (see resolve_prefix)."""
+    any_found = False
+    for _prefix, path in list_prefixes():
+        try:
+            tel = Telemetry(path)
+        except OSError as e:
+            sys.stderr.write(f"cannot query {path}: {e}\n")
+            continue
+        try:
+            ports = (tel.command(ETHDEV_LIST) or {}).get(ETHDEV_LIST) or []
+            for port in ports:
+                any_found = True
+                print(f"{port}. {port_name(tel, port)}")
+        except OSError as e:
+            sys.stderr.write(f"cannot query {path}: {e}\n")
+        finally:
+            tel.close()
+    if not any_found:
+        sys.stderr.write("no DPDK interfaces available for capture\n")
+
+
+def resolve_interface(tel, spec):
+    """Port id to capture on the connected primary. spec None selects the first
+    interface (like Wireshark and the C dpdk-dumpcap); otherwise it is a port id
+    or a device name as shown by --list-interfaces."""
+    ports = (tel.command(ETHDEV_LIST) or {}).get(ETHDEV_LIST) or []
+    if not ports:
+        raise SystemExit("no interfaces on this DPDK process")
+    if spec is None:
+        return ports[0]
+    try:
+        port = int(spec)
+    except ValueError:
+        port = None
+    if port is not None:
+        if port in ports:
+            return port
+        raise SystemExit(f"no port {port} on this DPDK process")
+    for port in ports:
+        if port_name(tel, port) == spec:
+            return port
+    raise SystemExit(f"no interface '{spec}' on this DPDK process")
+
+
+def default_output(name):
+    r"""Auto-named output in the temp dir, matching how current Wireshark
+    dumpcap names its default file: '<tool>_<iface><unique>.pcapng', with a
+    random unique suffix and no timestamp.
+    basename() strips any path-like parts of the device name, as Wireshark does;
+    mkstemp pre-creates the file empty, which is what the capture library wants."""
+    basename = os.path.basename(name)
+    fd, path = tempfile.mkstemp(prefix=f"dpdk-dumpcap_{basename}", suffix=".pcapng")
+    os.close(fd)
+    return path
+
+
+def read_stats(tel, cap_id):
+    """Return the stats dict, or None if the telemetry peer has closed (the
+    primary exited). An empty reply from a SEQPACKET socket is EOF."""
+    reply = tel.command(f"{CAPTURE_STATS_CMD},{cap_id}")
+    if reply is None:
+        return None
+    return reply.get(CAPTURE_STATS_CMD) or {}
+
+
+def print_progress(stats):
+    """Live packet counter, overwritten in place (carriage return, no newline)
+    like Wireshark: the running line reads 'Packets:', and print_summary
+    finalises it as 'Packets captured:' with a trailing newline."""
+    captured = stats.get("accepted", 0) - stats.get("ringfull", 0)
+    sys.stderr.write(f"\rPackets: {captured} ")
+    sys.stderr.flush()
+
+
+def print_summary(stats, name):
+    r"""dumpcap-style end-of-capture summary on stderr. The leading '\r'
+    finalises the in-place live counter (same line, overwritten). Counters map
+    onto the pcapng ISB the primary writes, so this agrees with the file trailer:
+        received (ifrecv) = accepted + filtered + nombuf   -- true total seen
+        dropped  (ifdrop) = nombuf + ringfull
+        captured          = accepted - ringfull            -- written to file
+    The percentage is 'fraction not dropped', off the true total (ifrecv already
+    includes the drops). An empty capture prints 0.0%, as dumpcap does."""
+    accepted = stats.get("accepted", 0)
+    filtered = stats.get("filtered", 0)
+    nombuf = stats.get("nombuf", 0)
+    ringfull = stats.get("ringfull", 0)
+
+    captured = accepted - ringfull
+    received = accepted + filtered + nombuf
+    dropped = nombuf + ringfull
+    pct = 100.0 * (received - dropped) / received if received else 0.0
+
+    print(f"\rPackets captured: {captured}", file=sys.stderr)
+    print(
+        f"Packets received/dropped on interface '{name}': "
+        f"{received}/{dropped} ({pct:.1f}%)",
+        file=sys.stderr,
+    )
+
+
+def capture(args):
+    prefix = resolve_prefix(args.file_prefix)
+    path = socket_path(prefix)
+
+    try:
+        tel = Telemetry(path)
+    except OSError as e:
+        raise SystemExit(f"cannot connect to DPDK telemetry at {path}: {e}")
+
+    port = resolve_interface(tel, args.interface)
+    name = port_name(tel, port)
+
+    output = args.write or default_output(name)
+
+    # The capture library opens the output O_WRONLY|O_NOFOLLOW without O_CREAT
+    # and rejects a non-empty file, so create/truncate it to an empty regular
+    # file here before handing over the path.
+    try:
+        open(output, "wb").close()
+    except OSError as e:
+        tel.close()
+        raise SystemExit(f"cannot create output {output}: {e}")
+
+    params = [str(port), f"out={output}"]
+    if args.snaplen is not None:
+        params.append(f"snaplen={args.snaplen}")
+    if args.queue is not None and args.queue >= 0:
+        params.append(f"queue={args.queue}")
+    if args.filter:
+        params.append(f"filter={args.filter}")
+    cmd = CAPTURE_START_CMD + "," + ",".join(params)
+
+    result = (tel.command(cmd) or {}).get(CAPTURE_START_CMD) or {}
+    if "error" in result:
+        tel.close()
+        raise SystemExit(f"capture start failed: {result['error']}")
+    cap_id = result.get("id")
+    if cap_id is None:
+        tel.close()
+        raise SystemExit("capture start did not return an id")
+
+    qnote = "" if args.queue is None or args.queue < 0 else f" queue {args.queue}"
+    print(f"File: {output}", file=sys.stderr)
+    print(f"Capturing on '{name}'{qnote}", file=sys.stderr)
+
+    # Stop on Ctrl-C/SIGTERM; the handler flips a flag the loop checks.
+    stop = {"now": False}
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(sig, lambda *_: stop.update(now=True))
+
+    interval = args.stats_interval
+    # Wake on a short tick so a signal stops us promptly; poll fast when -c must
+    # bound overshoot, otherwise just often enough to notice the signal. Stats
+    # are read only when -c is set or a heartbeat is due, so an idle capture
+    # barely touches the telemetry socket.
+    tick = COUNT_POLL_INTERVAL if args.count is not None else POLL_TICK
+    next_beat = time.monotonic() + interval if interval > 0 else None
+
+    stats = {}
+    try:
+        while not stop["now"]:
+            time.sleep(tick)
+            now = time.monotonic()
+            due = next_beat is not None and now >= next_beat
+            if args.count is not None or due:
+                # The stats round-trip is itself the liveness check: if the
+                # primary has exited, the telemetry socket errors or returns
+                # EOF, and the capture (and its half-written pcapng) is gone.
+                try:
+                    latest = read_stats(tel, cap_id)
+                except OSError:
+                    latest = None
+                if latest is None:
+                    print(
+                        "\nDPDK telemetry connection lost; capture stopped",
+                        file=sys.stderr,
+                    )
+                    break
+                if "error" in latest:
+                    break  # capture instance no longer present
+                if latest:
+                    stats = latest
+                if args.count is not None and stats.get("accepted", 0) >= args.count:
+                    break
+            if due:
+                print_progress(stats)
+                next_beat = now + interval
+        # snapshot final counters while the instance is still alive, then stop:
+        # after stop the primary tears the instance down and stats disappear.
+        try:
+            latest = read_stats(tel, cap_id)
+            if latest and "error" not in latest:
+                stats = latest
+        except OSError:
+            pass
+    finally:
+        try:
+            tel.command(f"{CAPTURE_STOP_CMD},{cap_id}")
+        except OSError:
+            pass
+
+    print_summary(stats, name)
+    tel.close()
+
+
+# --- entry point ---------------------------------------------------------
+
+
+def main():
+    p = argparse.ArgumentParser(
+        prog="dpdk-dumpcap",
+        description="Capture packets from a running DPDK primary process.",
+    )
+    p.add_argument(
+        "-D",
+        "--list-interfaces",
+        action="store_true",
+        help="list available DPDK interfaces and exit",
+    )
+    p.add_argument(
+        "-i",
+        "--interface",
+        metavar="IFACE",
+        help="port id or device name to capture from "
+        "(default: first interface; see --list-interfaces)",
+    )
+    p.add_argument(
+        "--file-prefix",
+        help="EAL file-prefix of the target primary "
+        "(required only if several are running)",
+    )
+    p.add_argument(
+        "-w", "--write", metavar="FILE", help="output pcapng file (default: auto-named)"
+    )
+    p.add_argument(
+        "-s",
+        "--snapshot-length",
+        dest="snaplen",
+        type=int,
+        metavar="LEN",
+        help="bytes to capture per packet (0 = all)",
+    )
+    p.add_argument(
+        "--queue",
+        type=int,
+        metavar="ID",
+        help="capture a single hardware queue (default: all queues)",
+    )
+    p.add_argument(
+        "-c",
+        "--packet-count",
+        dest="count",
+        type=int,
+        metavar="N",
+        help="stop after roughly N packets",
+    )
+    p.add_argument(
+        "--stats-interval",
+        type=float,
+        metavar="SECS",
+        default=DEFAULT_STATS_INTERVAL,
+        help="seconds between liveness updates "
+        f"(0 to disable; default {DEFAULT_STATS_INTERVAL})",
+    )
+    p.add_argument(
+        "-f",
+        "--filter",
+        dest="filter",
+        metavar="EXPR",
+        help="capture filter in libpcap syntax",
+    )
+    p.add_argument(
+        "filter_args", nargs="*", help="capture filter (if not given with -f)"
+    )
+    args = p.parse_args()
+
+    if args.list_interfaces:
+        list_interfaces()
+        return
+
+    # tcpdump-style trailing filter expression, if -f was not used.
+    if not args.filter and args.filter_args:
+        args.filter = " ".join(args.filter_args)
+
+    capture(args)
+
+
+if __name__ == "__main__":
+    main()
-- 
2.53.0