7.32. VBoxManage usbfilter add/modify/remove

VBoxManage usbfilter        add <index,0-N>
                          --target <uuid|vmname>global
                          --name <string>
                          --action ignore|hold (global filters only)
                         [--active yes|no (yes)]
                         [--vendorid <XXXX> (null)]
                         [--productid <XXXX> (null)]
                         [--revision <IIFF> (null)]
                         [--manufacturer <string> (null)]
                         [--product <string> (null)]
                         [--remote yes|no (null, VM filters only)]
                         [--serialnumber <string> (null)]
                         [--maskedinterfaces <XXXXXXXX>]
    
VBoxManage usbfilter        modify <index,0-N>
                          --target <uuid|vmname>global
                         [--name <string>]
                         [--action ignore|hold (global filters only)]
                         [--active yes|no]
                         [--vendorid <XXXX>]
                         [--productid <XXXX>]
                         [--revision <IIFF>]
                         [--manufacturer <string>]
                         [--product <string>]
                         [--remote yes|no (null, VM filters only)]
                         [--serialnumber <string>]
                         [--maskedinterfaces <XXXXXXXX>]
    
VBoxManage usbfilter        remove <index,0-N>
                          --target <uuid|vmname>global
    

The usbfilter commands are used for working with USB filters in virtual machines, or global filters which affect the whole Oracle VM VirtualBox setup. Global filters are applied before machine-specific filters, and may be used to prevent devices from being captured by any virtual machine. Global filters are always applied in a particular order, and only the first filter which fits a device is applied. For example, if the first global filter says to hold, or make available, a particular Kingston memory stick device and the second filter says to ignore all Kingston devices. That particular Kingston memory stick will be available to any machine with the appropriate filter, but no other Kingston device will.

When creating a USB filter using usbfilter add, you must supply three or four mandatory parameters. The index specifies the position in the list at which the filter should be placed. If there is already a filter at that position, then it and the following ones will be shifted back one place. Otherwise, the new filter will be added onto the end of the list. The target parameter selects the virtual machine that the filter should be attached to or use global to apply it to all virtual machines. name is a name for the new filter. For global filters, action says whether to allow VMs access to devices that fit the filter description (hold) or not to give them access (ignore). In addition, you should specify parameters to filter by. You can find the parameters for devices attached to your system using VBoxManage list usbhost. Finally, you can specify whether the filter should be active. For local filters, whether they are for local devices, remote devices over an RDP connection, or either.

When you modify a USB filter using usbfilter modify, you must specify the filter by index and by target, which is either a virtual machine or global. See the output of VBoxManage list usbfilters to find global filter indexes and VBoxManage showvminfo to find indexes for individual machines. The properties which can be changed are the same as for usbfilter add. To remove a filter, use usbfilter remove and specify the index and the target.

The following is a list of the additional usbfilter add and usbfilter modify options, with details of how to use them.

  • --action ignore|hold: Specifies whether devices that fit the filter description are allowed access by machines (hold), or have access denied (ignore). Applies to global filters only.

  • --active yes|no: Specifies whether the USB Filter is active or temporarily disabled. For usbfilter create the default is active.

  • --vendorid <XXXX>|"": Specifies a vendor ID filter. The string representation for an exact match has the form XXXX, where X is the hexadecimal digit, including leading zeroes.

  • --productid <XXXX>|"": Specifies a product ID filter. The string representation for an exact match has the form XXXX, where X is the hexadecimal digit, including leading zeroes.

  • --revision <IIFF>|"": Specifies a revision ID filter. The string representation for an exact match has the form IIFF, where I is the decimal digit of the integer part of the revision, and F is the decimal digit of its fractional part, including leading and trailing zeros. Note that for interval filters, it is best to use the hexadecimal form, because the revision is stored as a 16-bit packed BCD value. Therefore, the expression int:0x0100-0x0199 will match any revision from 1.0 to 1.99 inclusive.

  • --manufacturer <string>|"": Specifies a manufacturer ID filter, as a string.

  • --product <string>|"": Specifies a product ID filter, as a string.

  • --remote yes|no"": Specifies a remote filter, indicating whether the device is physically connected to a remote VRDE client or to a local host machine. Applies to VM filters only.

  • --serialnumber <string>|"": Specifies a serial number filter, as a string.

  • --maskedinterfaces <XXXXXXXX>: Specifies a masked interface filter, for hiding one or more USB interfaces from the guest. The value is a bit mask where the set bits correspond to the USB interfaces that should be hidden, or masked off. This feature only works on Linux hosts.