Last active
November 1, 2025 00:19
-
-
Save gpoole/c89807e9de9cb5c87bbcc2da27e0c3e4 to your computer and use it in GitHub Desktop.
Xen/XCP-ng script to attach physical USB devices via passthrough to a VM
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/bash | |
| function get-uuid() { | |
| grep ^uuid | sed -E 's/^.*: //g' | |
| } | |
| function get-vm-uuid-by-name() { | |
| vm_name="$1" | |
| xe vm-list name-label="$vm_name" | get-uuid | |
| } | |
| function get-usb-uuid-by() { | |
| key="$1" | |
| value="$2" | |
| xe pusb-list $key="$value" | get-uuid | |
| } | |
| # Below list all the connections you want made automatically on boot | |
| # The name here ("Example Disk Name") is the pusb product-desc, | |
| # which you can find with: xe pusb-list params=uuid,product-desc | |
| plug-usb "`get-usb-uuid-by product-desc "Example Disk Name"`" "`get-vm-uuid-by-name "Some VM Name"`" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| [Unit] | |
| Description=Automatically attach USB devices on startup | |
| Wants=xapi-init-complete.target | |
| # Runs BEFORE xapi-domains.service which is when VMS are autostarted | |
| Before=xapi-domains.service | |
| After=remote-fs.target xapi-init-complete.target xapi.service | |
| [Service] | |
| Type=oneshot | |
| RemainAfterExit=yes | |
| ExecStart=/usr/bin/attach-usb-devices | |
| [Install] | |
| WantedBy=multi-user.target |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #/bin/bash | |
| cp attach-usb-devices plug-usb unplug-usb /usr/bin | |
| chmod +x /usr/bin/attach-usb-devices /usr/bin/plug-usb /usr/bin/unplug-usb | |
| cp attach-usb-devices.service /etc/systemd/system | |
| systemctl enable attach-usb-devices | |
| # You can try running systemctl start attach-usb-devices but it'll fail to attach any VMs that are already running. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/bash | |
| function get-uuid() { | |
| grep ^uuid | sed -E 's/^.*: //g' | |
| } | |
| pusb_uuid="$1" | |
| vm_uuid="$2" | |
| if [ -z "$pusb_uuid" ] || [ -z "$vm_uuid" ]; then | |
| echo "Usage: plug-usb <pusb-device-uuid> <vm-uuid>" | |
| exit 1 | |
| fi | |
| vm_name=`xe vm-list uuid="$vm_uuid" | grep name-label | sed -E 's/^.*: //g'` | |
| pusb_name=`xe pusb-list uuid="$pusb_uuid" | grep product-desc | sed -E 's/^.*: //g'` | |
| if ! [ -z "`xe vm-list uuid="$vm_uuid" power-state=running`" ]; then | |
| echo "VM $vm_name must be stopped first." | |
| exit 1 | |
| fi | |
| echo -n "Attaching $pusb_name ($pusb_uuid) to $vm_name ($vm_uuid)..." | |
| group_uuid=`xe usb-group-list PUSB-uuids="$pusb_uuid" | get-uuid` | |
| xe pusb-param-set uuid="$pusb_uuid" passthrough-enabled=true | |
| if [ -z "`xe vusb-list vm-uuid="$vm_uuid" usb-group-uuid="$group_uuid"`" ]; then | |
| xe vusb-create usb-group-uuid="$group_uuid" vm-uuid="$vm_uuid" > /dev/null | |
| if [ $? -eq 0 ]; then | |
| echo "Attached" | |
| else | |
| echo "Failed." | |
| fi | |
| else | |
| echo "Already attached." | |
| fi |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/bin/bash | |
| pusb_uuid="$1" | |
| if [ -z "$pusb_uuid" ]; then | |
| echo "Usage: usb-unplug <pusb-uuid>" | |
| exit 1 | |
| fi | |
| function get-uuid() { | |
| grep ^uuid | sed -E 's/^.*: //g' | |
| } | |
| group_uuid=`xe usb-group-list PUSB-uuids="$pusb_uuid" | get-uuid` | |
| if [ -z "$group_uuid" ]; then | |
| echo "Could not find USB group." | |
| exit 1 | |
| fi | |
| vusb_uuid=`xe vusb-list usb-group-uuid="$group_uuid" | get-uuid` | |
| if [ -z "$vusb_uuid" ]; then | |
| echo "Failed to find virtual USB." | |
| exit 1 | |
| fi | |
| # Unplug from running VM | |
| vm_uuid=`xe vusb-list usb-group-uuid="$group_uuid" | grep vm-uuid | sed -E 's/^.*: //g'` | |
| if ! [ -z "`xe vm-list uuid="$vm_uuid" power-state=running`" ]; then | |
| xe vusb-unplug uuid="$vusb_uuid" | |
| fi | |
| xe vusb-destroy uuid="$vusb_uuid" |
Instead of your custom get-uuid I think you can use params=uuid --minimal
Example: xe vusb-list vm-uuid=$someId params=uuid --minimal
Author
Nice, thanks @martijnhazebroek 👍
i have a related issue and i was hoping you could address it in the attach-usb-devices. i have a usb keyboard i need to pass thru to a VM. in order to do that, i have to edit the /etc/xensource/usb-policy.conf to ALLOW keyboards. however, every time i run a xcp-ng patch update, that file gets overwritten, and i lose my edits. would it be possible for your script to copy over a user-usb-policy.conf and then rescan the devices before doing the usb attach to VM?
Thank you gpoole for this, appreciated!
@stoneobscurity I had the same problem, this is my proposal, a new file called add-custom-usb-policies with the following contents:
#!/bin/bash
# find information about which device you want to add a policy for with:
# lsusb
# Bus 001 Device 049: ID 1cf1:0030 Dresden Elektronik
# =>
# ALLOW:vid=1cf1 pid=0030 # Dresden Elektronik
# add the following policies to usb-policy.conf if they don't already exist
POLICY_FILE="/etc/xensource/usb-policy.conf"
USB_POLICY_DRESDEN="ALLOW:vid=1cf1 pid=0030 # Dresden Elektronik"
USB_POLICY_BLUETOOTH="ALLOW:vid=0b05 pid=190e # Asus USB-BT500"
for POLICY in "${USB_POLICY_DRESDEN}" "${USB_POLICY_BLUETOOTH}"; do
# -q be quiet
# -x match the whole line
# -F pattern is a plain string
grep -xqF -- "$POLICY" "$POLICY_FILE" || sed -i "1s/^/${POLICY}\n/" "$POLICY_FILE"
done
# NOTE: assumes you only have one host...
xe pusb-scan host-uuid=$(xe host-list --minimal)
# device should now show up in xe pusb-list
Kept my two devices in there just for illustration, make sure to read through and edit to your needs.
Then, in attach-usb-devices, just add add-custom-usb-policies before the plug-usb calls.
And make sure to add the add-custom-usb-policies file to install.sh
Author
Thanks for that @brumwald, I have updated to include your script with a few formatting changes and notes on usage. This set of scripts has grown a lot beyond the original one-script gist I had so I really should move it to a dedicated repo.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
This could be useful on a pool master to store VM meta data on a local USB storage device pre and post upgrade backup/recovery
Would like to see how this could be done to expose it as an SR to XCP-ng
Found this: https://support.citrix.com/article/CTX121282/how-to-back-up-virtual-machine-metadata-to-a-usb-device