Capture (pcap)

Record every transfer to a PCAPNG file that Wireshark opens with its usual USB dissectors. Capture normally turns on by itself via the USBIP_PCAPNG environment variable (Capturing traffic); this module is the in-code alternative. submit() / complete() are called by the transport internals - applications only need open(), close() and is_enabled().

pcap

Optional USB-traffic capture to a PCAPNG file (for Wireshark).

Off by default. Enable by setting USBIP_PCAPNG=<path> (a %p in the path expands to the PID, so concurrent processes don't clobber one file) or by calling open(path). Every USB transfer is written as the Linux usbmon Submit ('S') -> Complete ('C') event pair using DLT_USB_LINUX_MMAPPED (220), so Wireshark applies its USB and class dissectors exactly as for a real usbmon capture of the same device - the USB/IP CMD_SUBMIT/RET_SUBMIT pair maps 1:1 onto it.

The capture's Section Header / Interface blocks are stamped with identifying options (shb_userappl = usbip <version>, shb_os/shb_hardware from uname, if_name/if_description) so Wireshark/capinfos show context.

This module only OBSERVES: it never alters traffic, and when disabled (the default) every entry point is a single cheap boolean check.

The C library has a byte-compatible twin in its src/pcap.c.

open

open(path=None)

Begin capturing (truncating the file). With no path - or a flag value like "1" - the filename is derived from the script/executable name (fallback usb_traffic.pcapng). %p in an explicit path expands to the PID. Idempotent.

Source code in usbip/pcap.py

def open(path: str | None = None) -> None:
    """Begin capturing (truncating the file). With no path - or a flag value like
    ``"1"`` - the filename is derived from the script/executable name (fallback
    ``usb_traffic.pcapng``). ``%p`` in an explicit path expands to the PID. Idempotent."""
    global _fp, _enabled, _checked
    _checked = True
    if path is None or path.strip().lower() in _FLAG_VALUES:
        path = _default_name()
    path = path.replace("%p", str(os.getpid()))
    with _lock:
        if _fp is not None:
            return
        fp = builtins.open(path, "wb")
        fp.write(_shb())
        fp.write(_idb(LINKTYPE_USB_LINUX_MMAPPED))
        fp.flush()
        _fp = fp
        _enabled = True

close

close()

Source code in usbip/pcap.py

def close() -> None:
    global _fp, _enabled
    with _lock:
        if _fp is not None:
            _fp.close()
            _fp = None
        _enabled = False

is_enabled

is_enabled()

Source code in usbip/pcap.py

def is_enabled() -> bool:
    if not _checked:
        _ensure()
    return _enabled