VirtualBox USB passthrough

Yes, this topic is very easy via VirtualBox UI and many people would not have in mind to do these actions with command line. But as I do mostly all tasks while development via terminal, I thought some other persons are interested in the solution, too. So here now a short tutorial to attach/detach USB devices on VirtualBox machines.

Requirements

Objective

Learn and understand the basics for command line USB passthrough for VirtualBox.

Gather informations of USB devices

In a first step it’s important to gather all informations about possible USB devices. There are 3 important values ​​to be determined.

  • UUID
  • VendorId
  • ProductId

In order to better understand which devices are involved, the product name is also an advantage.

# list all usb devices
$ VBoxManage list usbhost

# list all usb devices with specific information
$ VBoxManage list usbhost | grep -i "UUID\|VendorId\|ProductId\|Product\|Current State"

The value of “Current State” can provide you the information if a USB device is in usage or captured by a VM already.

Analysis of VM’s

In the second step, it is advisable to check whether the respective USB standard is configured in the target VM (and whether USB is turned on). There are currently 3 options that VirtualBox supports.

  • USB 1.1: OHCI
  • USB 2.0: OHCI + EHCI
  • USB 3.0: xHCI

Note: My VM is named Debian in all examples, please change this value for your specific needs!

# show all informations for specific vm
$ VBoxManage showvminfo "Debian"

# show usb status for specific vm
$ VBoxManage showvminfo "Debian" | grep -i "ohci\|ehci\|xhci"

Add/remove USB devices

In many cases, USB 1.1 is enabled by default and deactivation leads to a misconfiguration. But there are, as almost always, exceptions.

  • USB 1.1: --usb on|off
  • USB 2.0: --usbehci on|off
  • USB 3.0: --usbxhci on|off

Note: For these kind of configurations the VM should be stopped (turned off).

# enable USB 2.0 for specific vm
$ VBoxManage modifyvm "Debian" --usbehci on

# disable USB 2.0 for specific vm
$ VBoxManage modifyvm "Debian" --usbehci off

# enable USB 3.0 for specific vm
$ VBoxManage modifyvm "Debian" --usbxhci on

# disable USB 3.0 for specific vm
$ VBoxManage modifyvm "Debian" --usbxhci off

If you know the UUID (see first step), you can now attach/detach the respective USB devices.

Note: You can make the following changes during the VM is running. Don’t forget to change the UUID value from my examples.

# attach specifc usb device to specifc vm
$ VBoxManage controlvm "Debian" usbattach "076866d4-436e-424d-be64-660c23248f37"

# detach specifc usb device to specifc vm
$ VBoxManage controlvm "Debian" usbdetach "076866d4-436e-424d-be64-660c23248f37"

Nothing more is needed for this very simple task. But you can save some time and automate these steps with the following section!

Usage of USB filters

VirtualBox USB filters will help you to automatically assign USB devices to your VM. With other words – As soon as the VM starts (or is started) and the USB device is recognized by VirtualBox (and it’s not in use by the host), it will be made available to the guest.

Additionally it’s important to understand that there are two kind of filters (global and machine specifc). Global filters (IHostUSBDeviceFilter) are applied before any machine specific filter (IUSBDeviceFilter).

  • --target <uuid|vmname>|global
  • --action ignore|hold (global filters only)
  • --active yes|no

In this tutorial I focus only on machine specific filters.

# verify for filter on specific vm
$ VBoxManage showvminfo "Debian" | awk '/^USB Device Filters:/,/^Available remote USB devices:/'

Important is the value “index” from 0 to n! If you create the first filter – the index starts with an 0, the second filter with an 1 and so on. To add a filter you must provide the VendorId and ProductId (as minimum) from first section (values inside the brackets), the name is can be chosen free.

Note: you have to adjust the following values in my examples ​​for your environment.

# show help for usb filters
$ VBoxManage usbfilter --help

# create usb filter for specifc vm
$ VBoxManage usbfilter add 0 --target "Debian" --name 'YARD Stick One' --vendorid 1d50 --productid 605b --remote no

# modify usb filter for specifc vm
$ VBoxManage usbfilter modify 0 --target "Debian" --name 'YARD Stick One' --vendorid 1d50 --productid 605b --remote no --manufacturer 'great scott gadgets'

# delete usb filter for specifc vm
$ VBoxManage usbfilter remove 0 --target "Debian"

USB filters are a very nice feature of VirtualBox, just play around and do some further research on it – I’m sure you will love it!