Additional USB pass-through documentation for hardware security tokens #660

New Issue

adam · 2025-12-29T01:24:18+01:00

adam commented

2025-12-29 01:24:18 +01:00

Originally created by @cmosetick on GitHub (May 21, 2025).

Greetings, and thanks again for this wonderful project.

Overview:
I've recently been testing USB pass-through from a Linux PC into Docker-OSX Sonoma and Sequoia.

Issue:
The current documentation does not seem to sufficiently cover USB pass-through for devices such as a hardware security token.
e.g. a Yubikey or similar.

Method:
Hot-Plug
I can run the recommended options as noted in the current documentation:
e.g. usbredirserver -p 7700 1e3d:2096 substituting the correct ID's for my specific hardware token.

Current Behavior:
When I run the usbredirserver and do the chardev-add using the correct ID's for the the hardware token on the Linux PC, the docker-osx MacOS system immediately goes unresponsive and then typically kernel panics.

(I've seen this both with Sonoma and Sequoia.)

Possible Reasons:

The current documentation repeatedly says "USB Drive" which makes me think of "disk" or "mass storage device". note 1
Also it says that things can be configured as hot-plug or at boot-time. I've only tried the hot-plug method as I'm testing with a hardware token which are typically more transient than a disk drive.

Linux PC host kernel:
5.15.0-140

CPU:
AMD Ryzen 9 with svm and svm_lock

Requests:

If we need to make sure the hardware security token is present at MacOS boot-time to avoid kernel panics and forceful shutdowns of otherwise 100% stable systems, some documentation explicitly stating this would be wonderful.
Additional documentation for common [non-disk] USB hardware security tokens. I might be missing something simple, but more instructions on how to pass-through a physical device would be very useful.

Originally created by @cmosetick on GitHub (May 21, 2025). Greetings, and thanks again for this wonderful project. **Overview:** I've recently been testing USB pass-through from a Linux PC into Docker-OSX Sonoma and Sequoia. **Issue:** The current documentation does not seem to sufficiently cover USB pass-through for devices such as a hardware security token. e.g. a Yubikey or similar. **Method:** Hot-Plug I can run the recommended options as noted in the current documentation: e.g. `usbredirserver -p 7700 1e3d:2096` substituting the correct ID's for my specific hardware token. **Current Behavior:** When I run the `usbredirserver` and do the `chardev-add` using the correct ID's for the the hardware token on the Linux PC, the docker-osx MacOS system immediately goes unresponsive and then typically kernel panics. (I've seen this both with Sonoma and Sequoia.) Possible Reasons: - The current documentation repeatedly says "USB Drive" which makes me think of "disk" or "mass storage device". [note 1](https://github.com/sickcodes/Docker-OSX#mount-usb-drive-hotplughot-plug-usb) - Also it says that things can be configured as hot-plug or at boot-time. I've only tried the hot-plug method as I'm testing with a hardware token which are typically more transient than a disk drive. Linux PC host kernel: `5.15.0-140` **CPU:** AMD Ryzen 9 with svm and svm_lock **Requests:** - If we need to make sure the hardware security token is present at MacOS boot-time to avoid kernel panics and forceful shutdowns of otherwise 100% stable systems, some documentation explicitly stating this would be wonderful. - Additional documentation for common [non-disk] USB hardware security tokens. I might be missing something simple, but more instructions on how to pass-through a physical device would be very useful.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/Docker-OSX#660