USB basics and troubleshooting

[socratis]

Despite its reputation, USB is not always plug and play, even more so in a virtual environment. You have to talk almost directly to the hardware via a series of software layers. The more layers, the more complicated things become. That explains the length of this article. If things were so easy, this FAQ would be very small and it wouldn't require a Table Of Contents:

1. Sharing USB devices
2. Capturing a USB device in VirtualBox
3. Device categories
4. USB Filters
5. Common problems
6. Guest support
7. Troubleshooting
8. Asking for help
9. Distinguish multiple identical USB devices

#1: Sharing USB devices
USB devices cannot be shared at the bus level. That means that two computers (a host and a guest) cannot share the same device. Think of it as having a USB stick, a printer, a webcam or a WiFi adapter hooked into two computers at the same time. You simply can't.

There are other means of sharing for some device categories. Such as: shared or network folders for mass storage devices, printer sharing for printer/scanners/fax devices. You simply cannot have direct resource sharing.

IMPORTANT

• If you can share the device from the host (be it Shared/Network Folders, or Printer sharing), go for that option! It's much easier, and both the host and the guest can access the shared USB resources.

[socratis]

#2: Capturing a USB device in VirtualBox
There are two ways to capture a USB device in a guest in VirtualBox:

• On-the-fly
  • A "transient" solution, either by using the icon on the bottom of the window, or the menu "Devices » USB » ...". The captured devices are indicated by the check next to them. The rest of the devices in the list, simply show you the devices currently present in the host. That does NOT mean you can capture them at will. See "Device categories" below.
• USB filter
  • A more "permanent" solution and one that captures the device as soon as it is inserted into the host, but only after the VM is already up and running. A filter should be ideally created specifically for each device. See "USB Filters" below.
    
    NB: You can have both a filter, and use the transient nature of the list. So, for example, you have setup a filter for a USB stick. As soon as you insert the stick, the filter captures it, and it shows in the list as "checked" (captured). You can then check/uncheck the device in the list at will to make it available in your host. But since you used a filter, the guest has the first saying.
  The "USB filter" option is strongly suggested, compared to the "On-the-fly" option (Devices » USB » ...), because it's more robust and it works in the majority of cases.
  

  ---

  NOTE for Linux hosts
  For Linux hosts, please make sure that you are a part of the "vboxusers" group and verify your membership with the "id" command, after a logout or a reboot. Otherwise you will not see any USB devices. Also remember that only the official download from VirtualBox is supported, not your distro's.

[socratis]

#3: Device categories
There are several categories of USB devices:

• Uncapturable
  • These are USB devices that are captured by the host with a daemon or service (e.g. Bluetooth controller). Not only you can't make the on-the-fly option work, but you can't even get it to work with a filter, unless you disable the host service/daemon. The device then becomes "Idling", see below.
• Ejectable
  • These are USB devices that are captured by the host and are actively used (e.g. USB sticks, external HDs). You have to eject them first to be able to use them with the on-the-fly option. If you have a filter and you plug the device after the VM has started, it gets captured by the filter.
    
    NB 1: In some OSes (Linux, Windows) you don't have to eject such a device specifically from the host in order to capture it with the on-the-fly option. That would place them in the "Idling" category, see below.
    
    NB 2: I haven't tried what happens if you have multiple VMs with the same filter active.
• Un-ejectable
  • These are USB devices that are captured by the host, but cannot be ejected (e.g. gamepads, joysticks, mice, keyboards). You have to unplug them and use a USB filter. The on-the-fly option doesn't work, simply because you cannot release them from your host.
• Idling
  • These are USB devices that are sitting, waiting to be used (e.g. gamepads, joysticks, IR receivers, ejected devices). You can capture them with either the on-the-fly or the filter option.

NB: You may have noticed that some devices are listed both in the "Un-ejectable" and in the "Idling" categories (e.g. gamepads, joysticks). The answer to that is that it depends both on the device and the host. You cannot know a priori.

[socratis]

#4: USB Filters
A USB filter is a series of "AND" conditional statements. So when you're filling in the filter values, you're telling the filter:

Capture a device with this VendorID, AND that ProductID, AND ...

A blank filter (not recommended!) will match anything, which is good if the device appears as a composite, i.e. presents as a number of different devices all connected at once. However the danger of a blank filter is the potential to grab the wrong device, e.g. you do not want to grab the host's USB keyboard and assign it to the guest! If you have a problem with the wrong device being grabbed then you'll need to add just enough information to the filter so that it matches your device only. But don't define the filter too narrowly, as that can lead to problems too. That's why your safest bet for a basic filter is to fill in the VendorID and ProductID only. The proper checklist for capturing a USB device with a filter is:

1. Make sure that the Extension Pack (ExtPack) is installed on the host. The ExtPack must be the same version as the main VirtualBox program. The ExtPack is not the same as the Guest Additions! The ExtPack is installed on the host and adds support for a virtual USB2 host controller. VirtualBox 5.x.x added USB3 (xHCI) support as well. NOTE: VirtualBox v7.x removed the need to install the extension pack for this purpose, i.e. the base program now has built-in support for USB2/USB3.
2. Under VM Settings » USB, make sure that at least USB2 (EHCI) is enabled in your VM settings. If your guest supports USB3 (xHCI), use that. See "Guest support" below. It is important to note that if your guest can support USB3, you should definitely enable that, even if your host does NOT support USB3 at the hardware or software level, mainly because the USB3 stack is much better designed compared to USB1 and USB2.
3. Under VM Settings » USB, create a USB filter in your guest settings while the device is plugged in the host. Delete all values except Name, VendorID and ProductID. The Name is nothing more than a label and is not actively participating in the filtering process. You can change it at will. I usually use "Stick: XYZ" or "Joystick: ABC" or "Other: IJK".
   
4. Unplug the device.
5. Start your guest (the one that you applied the filter to). Let it start completely. Log in if you have to, reach the desktop, and wait until any disk activity has stopped.
6. Plug your device. The filter should capture it and pass control to your guest.

[socratis]

#5: Common problems

• Error: Busy with a previous request (VERR_RESOURCE_BUSY)
  • The error means that something else (most probably the host) is using the device. Take a look at the "Basics - Device categories" and see which category your device falls under and take appropriate action: eject it, uncapture it, stop the service/daemon that uses it, unplug it and create a filter.
  • This error can also mean that another filter is installed on your host and is actively monitoring/filtering your USB connections. Such filters can be installed with antivirus programs, AMD USB Filter, Microsoft's RemoteFX USB Redirection, NoMachine, Dell DPE, or Wireshark and its USBPcap component. Or any other application with a USB filtering mechanism. Or custom USB drivers for your host.
  • This error can mean a lot of other not so common things. Take a look at the "Troubleshooting" section.
• VERR_PDM_NO_USB_PORTS
  • You are trying to use a USB3 device with a guest that does not support USB3 (see the "Guest support" section), or you haven't enabled the USB3 option in the VM settings.
• No USB devices are listed
  • Something is not right with the installation of the VirtualBox USB filter. If you are on Linux, are you a member of the "vboxusers" group? Did you verify it? Did you logout/login or reboot? If you're on Windows did you try reinstalling VirtualBox with the Run-As-Administrator option?
• Device gets randomly disconnected
  • Check the power options for that device. Make sure that the guest OS does not shut down the device in order to save power.
• Unknown USB device detected
  • Actually, this message has been removed from the latest VirtualBox versions, because there was actually nothing that VirtualBox could do about it. VirtualBox gets the USB VendorID/ProductID information from "The USB ID Repository", so it's actually them that you have to notify. See the "Submit new data" section for more information.
• Distinguish identical devices
  • Sometimes you have to plug two identical devices and you cannot distinguish them. You have to activate more criteria in the filter, like the "Serial No." or the "Port" that they're connected to. See Distinguish multiple identical USB devices below. (mod edit - link added by scottgus1)

[socratis]

#6: Guest support
Not all guest systems support all levels of USB. This is a general guideline, but for more specifics you've got to check with your guest OS's documentation:

• No USB
  • DOS, Minix, Win 3.11, Win NT* and other OS of the 80's and early 90's do not support USB at all.
• USB1 only
  • Win9* and early Linux kernels. However these early examples still have no native support for any device class (e.g. mass storage).
• USB2 only
  • OSX up to 10.6, Linux up to around 2010, Win9* , XP, Windows 7.
  • Especially for Win9*, and other old guests, the real problem usually isn't the host controller drivers but rather drivers for specific devices. Something like a USB mouse or keyboard or joystick typically works. See Tutorial: Windows 95/98 guest OSes.
• USB3 with external drivers
  • WinXP: you need to install the Renesas drivers in your Windows XP guest. The instructions are in the article "USB 3.0 support in XP guests".
  • Win7: you need to install the "Intel USB 3.0 eXtensible Host Controller Driver" in your Windows 7 guest:
    Update 2019-11-20: Intel seems to have removed the driver from its official site, you can get it from the Archive.org site: http://web.archive.org/web/201901092235 ... Driver.zip
• USB3
  • Most modern OSes (since 2010) support USB3.

[socratis]

#7: Troubleshooting

1. Connect your device directly to the computer and not through a hub.
2. Shutdown your guest from within your guest, normal shutdown. Shutdown your host. Reboot your host. Relaunch your guest. This has helped at times, to have a clean start of both host and guest.
3. If the device shows up in your host and is not captured by the filter, either the filter is incorrect, or there might be a problem with your filter installation. For example you may have a blank filter, or a narrowly defined filter (too many conditionals).
4. If the device shows up, but as "Unavailable", eject it from your host (if you can), but leave it plugged in. It should show up as available.
5. Do you have the VendorID and DeviceID correct? On Linux hosts, check the output of "lsusb". On Mac hosts, check the "System Information". On Windows hosts, check the device manager, or get USBDeview, or USBView, or UsbTreeView.
6. If you're using a USB3 device, make sure that both your host and your guest support USB3. And of course you have to be using 5.x.x series of VirtualBox or later. If you plug a USB3 device into a USB3 port then it will only work with VirtualBox > 5, as that's when VirtualBox introduced a virtual xHCI controller.
7. If on a Linux host, are you a member of the 'vboxusers' group? If not, add yourself with the following command and then reboot your host, or logout and login to activate the change in group membership:

   • sudo usermod -a -G vboxusers <your_username>

8. If on Windows host, check that the VirtualBox USB Driver is installed in your host. Make sure your host didn't silently reject non-MS drivers (Google for Driver Signature Enforcement). Usually a re-installation of VirtualBox with the "right-click on the installer & Run-as-Administrator" trick, fixes this.
9. If on a Windows host, check out these Windows-specific ways to troubleshoot potential driver installation issues:
   1. USB not working
   2. SOLVED: Failed to access the USB subsystem on Windows 7 host
   3. Remove Driver Filters to Resolve Device Manager Errors on Windows 7

[socratis]

#8: Asking for help

If you've tried everything so far, and you had no luck, maybe it's time to open a new thread. Please read the Minimum information needed for assistance. Use the complete version numbers (including the build numbers) to identify software.

Once again, the "USB filter" option is strongly suggested, compared to the "On-the-fly" option (Devices » USB » ...), because it's more robust and it works in the majority of cases.

Connect your device directly to the computer, not through a hub.

Now, with the USB device plugged in and the VM not running, post the output of the following commands. Note that the 1st command applies to Windows hosts only, and the 2nd to Linux hosts only. It would be best if you unplugged any other unnecessary USB devices, for simplicity:

• cd "C:\Program Files\Oracle\VirtualBox"   <-- For Windows only, change if not the default installation folder
  id                                        <-- For Linux hosts only
  VBoxManage -version
  VBoxManage list extpacks
  VBoxManage list usbhost
  VBoxManage list usbfilters
  VBoxManage showvminfo "Your Virtual Machine Name"

Finally, a log from a cold_start / login / plug_USB / unplug_USB / complete_shutdown cycle:

1. Start the VM from cold-boot (not from a paused or saved state).
2. After you've logged in, plug the USB device. Wait (idling) for a minute or two. Unplug the USB device.
3. Shutdown the VM (not paused or saved).
4. Right-click on the VM in the VirtualBox Manager and select "Show Log".
5. Save only the first "VBox.log", ZIP it and attach it to your response (see the "Attachments" tab below the reply form).
6. You need to also find, ZIP and attach the "VBoxSVC.log", because the USB device enumeration and capturing is all done from VBoxSVC^[1]:
   • Linux: "/home/<you>/.config/VirtualBox/VBoxSVC.log" (note the period in the folder name, ".")
   • OSX: "/Users/<you>/Library/VirtualBox/VBoxSVC.log"
   • Windows: "C:\Users\<you>\.VirtualBox\VBoxSVC.log" (note the period in the folder name, ".")

---

^[1]: Friendly developer on IRC...

[scottgus1]

#9: Distinguish multiple identical USB devices

Virtualbox can tell apart "identical" USB devices and pass the desired device into the correct guest, as long as the identical devices appear on different USB "Port" numbers in 'vboxmanage list usbhost'.

This feature was experimentally used at least as of 5.2.20 and 6.0.0, and was officially documented starting in 6.1.0.

A discussion topic for using identical USB devices is here: Discussion

How to do it:

1. Get each USB device to successfully go into the guest(s) using the above tutorial steps 1-8.
2. Run 'vboxmanage list usbhost' with none of the devices plugged in, to get a baseline view of the host's present USB devices.
3. Insert one of the devices and let the host fully recognize it.
4. Run 'vboxmanage list usbhost' again, noting the new device and what port number it is on.
5. Repeat steps 3 and 4, inserting another of the identical USB devices in a different USB port.
6. On each guest's USB filter, add the port number for the desired USB device. See Caveat C below if the port number is greater than 9. (Note that the number you enter will be leading-0-padded to display as 4 digits when you open the filter in the future: you enter 2, it will show later as 0002. In my tests this was not a problem.)
7. Eject the USB devices from the host and reinsert them. Each port-filtered identical sibling should go in its desired guest or remain on the host if no filters match.

Caveats:
A. The USB devices must be inserted into the same physical USB ports on the host each time to go where they are supposed to go in Virtualbox. Plug into the wrong port and the results won't be as planned.

B. 'Vboxmanage list usbhost' must show different port numbers for each identical USB device. It could be possible, due to the layout of the USB subsystem in the host (built-in or added USB root hubs?), that there may be more than one physical USB port that will show the same 'port number' in 'vboxmanage list usbhost'. You may have to experiment with which USB device gets plugged in where, or shift other USB devices around, to get different port numbers in 'vboxmanage list usbhost' for each identical device.

C. In VirtualBox versions before 6.1.42 and 7.0.6, configuring USB port numbers greater than 9 need special considerations.
(See viewtopic.php?f=6&t=108063 credit to 'fantinel' and 'fth0' for discovering and developing a workaround for this situation.)
When you enter a USB port number in the Port field of a USB Device Filter, the number is erroneously interpreted as a hexadecimal number. This creates a problem for port numbers greater than 9. For example, if you enter the digits "10", the filter will match port 16, because the hexadecimal number "10" equals the decimal number "16". Because the Port field only accepts digits, and the decimal numbers from 10 to 15 are equivalent to the hexadecimal numbers "a" to "f", you cannot create a filter to match those port numbers. As a workaround, you can manually edit the VM's .vbox file to enter the hexadecimal value for the greater-than-9 port number:

1. Make a USB filter in the VM with a temporary 0-9 regular port number, to get the XML for the filter recorded in the VM's .vbox file.
2. Restart the host so no Virtualbox processes are running. (The background VboxSVC service must not be running when manually editing a .vbox file.)
3. Open the VM's .vbox file in a text editor. (Linux-like hosts should be able to use any text editor; for Windows hosts, Wordpad works well instead of Notepad.)
   Find the XML section for the USB filter:
   

   Code: Select all

   <USB>
     <Controllers>
        ...
     </Controllers>
     <DeviceFilters>
       <DeviceFilter name="Filter Name" active="true" vendorId="xxxx" productId="yyyy" port="000#" remote="0"/>
     </DeviceFilters>
    </USB>

   You're looking for the port="000#", where # is the single digit you entered.
4. Change the "000#" to the hexadecimal letter for the 10-or-above port number you need:
   • 10: 000a
   • 11: 000b
   • 12: 000c
   • 13: 000d
   • 14: 000e
   • 15: 000f
   • port numbers above 16 are untested, but 16 could be 0010, 27 would be 001b, etc...
5. Save the .vbox file as text only.
6. Start Virtualbox, and check that the hexadecimal value for the port number shows in the USB filter.