USB Capture Setup

USB Capture Setup

To create a USB capture, follow the steps from one of the two sections below. A Wireshark USB capture is preferred.

These instructions work both for native packet captures with ckb-next-daemon, and with Windows software running inside a VirtualBox VM with USB passthrough.

Wireshark USB Capture

First time setup

The following three steps need to be followed only once.

1. Install Wireshark through your package manager.

   • On Debian/Ubuntu based distributions: sudo apt install wireshark

2. Add yourself to the wireshark group

   • sudo usermod -aG wireshark $USER

3. IMPORTANT: Log out of your desktop session and log back in.

Capture process

The following steps need to be followed after every system boot to perform a capture.

1. Load the usbmon kernel module

   • sudo modprobe usbmon

2. Set the appropriate permissions

   • sudo setfacl -m u:$USER:r /dev/usbmon*

3. Identify the USB bus the device is attached to by running lsusb

   • For example: Bus 001 Device 002: ID 1b1c:1b5c Corsair CORSAIR NIGHTSWORD RGB Gaming Mouse

4. Run Wireshark

5. Double click on the correct usbmonX option in Wireshark, where X is the bus number

   • In the above example, it would be usbmon1
   • WARNING:⚠️ All devices reported by lsusb on the same bus will be captured. If lsusb reports USB headphones/headset, a webcam, or other sensitive device on the bus that will be captured, unplug it or make sure it is not running at the time of the capture. Make sure to not type any passwords while capturing.

6. Perform the requested or necessary actions on the USB device that need to be captured

7. Click on the stop button in Wireshark

8. Save and share the capture

   • Enable "Compress with gzip" in the save dialogue if you intend to attach the file on GitHub issues.

9. Recommended: Ensure Wireshark is not running and unload the usbmon module

   • sudo modprobe -r usbmon

Plaintext capture

To collect a raw text trace, execute following steps.

1. Load the usbmon kernel module

   • sudo modprobe usbmon

2. Set the appropriate permissions

   • sudo setfacl -m u:$USER:r /dev/usbmon*

3. Identify the USB bus the device is attached to by running lsusb

   • For example: Bus 001 Device 002: ID 1b1c:1b5c Corsair CORSAIR NIGHTSWORD RGB Gaming Mouse

4. Verify that bus sockets are present.

   • sudo ls /sys/kernel/debug/usb/usbmon
   • Example output: 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u

5. Run cat on the correct Xu path, where X is the bus number from step #3, and pipe to a file

   • Example for Bus 001: sudo cat /sys/kernel/debug/usb/usbmon/1u > /tmp/usbmon.out
   • WARNING:⚠️ All devices reported by lsusb on the same bus will be captured. If lsusb reports USB headphones/headset, a webcam, or other sensitive device on the bus that will be captured, unplug it or make sure it is not running at the time of the capture. Make sure to not type any passwords while capturing.

6. Perform the requested or necessary actions on the USB device that need to be captured

7. Stop the capture

   • Press Ctrl + C in the terminal running the cat command above.

8. Share the capture

   • It is located at /tmp/usbmon.out.

9. Recommended: Unload the usbmon module

   • sudo modprobe -r usbmon

Notes

Some instructions have been copied from The official Wireshark USB Capture guide.

Context on using usbmon and Wireshark to capture USB traffic on Linux can be found in the following issue comments:

#543 K95 RGB Platinum XT / New Protocol
#81 Void headset support

The most exhaustive example can be found in Nightsword RGB support #656.