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. Forusbfilter 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.