$Date: 2025-08-11 19:18:47 +0200 (Mon, 11 Aug 2025) $

VBoxManage usbfilter

VBoxManage-usbfilter 1
VBoxManage-usbfilter управление USB фильтрами &product-name;
`VBoxManage usbfilter add` индекс,0-N --target= uuid имя-ВМ global --name=строка --action=ignore | hold --active=yes | no --vendorid=XXXX --productid=XXXX --revision=IIFF --manufacturer=строка --product=строка --port=hex --remote=yes | no --serialnumber=строка --maskedinterfaces=XXXXXXXX `VBoxManage usbfilter modify` индекс,0-N --target= uuid имя-ВМ global --name=строка --action=ignore | hold --active=yes | no --vendorid=XXXX | "" --productid=XXXX | "" --revision=IIFF | "" --manufacturer=строка | "" --product=строка | "" --port=hex --remote=yes | no --serialnumber=строка | "" --maskedinterfaces=XXXXXXXX `VBoxManage usbfilter remove` индекс,0-N --target= uuid имя-ВМ global

## Описание

Команда `VBoxManage usbfilter` позволяет управлять USB фильтрами для указанной виртуальной машиной (ВМ) или глобальными USB фильтрами, влияющими на всю конфигурацию &product-name;.

Глобальные фильтры применяются перед фильтрами определенной ВМ. Это означает, что можно использовать глобальный фильтр для предотвращения захвата устройств какой-либо ВМ.

Глобальные фильтры применяются в определенном порядке. Применяется только первый походящий данному устройству фильтр. Например, первый глобальный фильтр делает доступным определенный флеш-накопитель Kingston, тогда как второй фильтр игнорирует все устройства Kingston. В результате применения этих фильтров, определенный флеш-накопитель Kingston будет доступен любой машине, имеющей соответствующий фильтр, но остальные устройства Kingston доступны не будут.

### Общие операнды и опции

index,0-N

  Задает единственное число, указывающее позицию фильтра в списке. Ноль (`0`) представляет первую позицию в списке. Если в данной позиции уже существует фильтр, то этот фильтр, а также следующие за ним передвигаются ниже по списку. В противном случае, новый фильтр добавляется в список.

`--action=ignore | hold`

  Указывает, разрешать ли доступ ВМ к устройствам, подходящим к описанию фильтра (`hold`) или запрещать (`ignore`). Эта опция применяется только к глобальным фильтрам.

`--active=yes | no`

  Указывает, активен ли USB фильтр или временно отключен. Допустимые значения `yes`, активирующая фильтр и `no`, отключающая его. Значение по умолчанию `yes`.

`--manufacturer=строка`

  Задает фильтр по ID производителя как строку. Значение по умолчанию пустое (`""`).

`--maskedinterfaces=XXXXXXXX`

  Указывает фильтр маскированного интерфейса, который используется для скрытия одного или нескольких USB интерфейсов от гостевой системы. Значение - это битовая маска, где набор битов соответствует скрываемому USB интерфейсу или снятие маски. Эта функция поддерживается только только в хост-системах Linux.

`--name=имя-фильтра`

  Задает имя фильтра.

`--port=hex`

  Задает фильтр по номеру USB порта (hub port number). Значение по умолчанию - пустая строка (`""`).

`--product=строка`

  Задает фильтр по ID продукта как строку. Значение по умолчанию пустое (`""`).

`--productid=XXXX`

  Задает фильтр по ID продукта. Строковое представление для точного соответствия имеет вид XXXX, где X - это шестнадцатеричная цифра включающая лидирующие нули. Значение по умолчанию пустое (`""`).

`--remote=yes | no`

  Задает удаленный фильтр, показывающий подключено ли физически устройство к удаленному клиенту VRDE или или к локальной системе. Эта опцию применяется только к фильтрам ВМ. Значение по умолчанию пустое (`""`).

  Почему значение по умолчанию пустое когда допустимые значения `yes` или `no`?
`--revision=IIFF`

  Задает фильтр по ID ревизии. Строковое представление для точного соответствия имеет вид IIFF. I - это десятичная цифра целой части ревизии. F - это десятичная цифра ее дробной части включающая лидирующие и замыкающие нули. Значение по умолчанию пустое (`""`).

  Для того, чтобы указать диапазон ревизий ID, убедитесь что используется шестнадцатеричная форма, то есть в виде 16 битного упакованного двоично-десятичного значения. Например, выражение `int:0x0100-0x0199` соответствует любой ревизии с 1.0 по 1.99 включительно.

`--serialnumber=строка`

  Задает фильтр серийного номера как строку. Значение по умолчанию пустое(`""`).

`--target=uuid | имя-ВМ | global`

  Указывает ВМ, к которой подключается фильтр. Можно указать Универсальный Уникальный Идентификатор (UUID) или имя ВМ. Для применения описания фильтра ко всем ВМ, укажите `global`.

`--vendorid=XXXX`

  Задает фильтр по ID поставщика, который представляется строкой шестнадцатеричного номера, состоящего из четырех цифр включая лидирующие нули. Значение по умолчанию пустое (`""`).

### Добавить USB фильтр или глобальный фильтр

Используйте команду `VBoxManage usbfilter add` для создания нового USB фильтра.

Дополнительно укажите параметры для фильтрации. Можно использовать команду `VBoxManage list usbhost` для просмотра параметров устройств, подключенных к вашей системе.

### Изменить USB фильтр или глобальный фильтр

Используйте команду `VBoxManage usbfilter modify` для изменения USB фильтра. Можно использовать команду `VBoxManage list usbfilters` для отображения индексов глобальных фильтров и команду `VBoxManage showvminfo` для отображения индексов по определенной машине.

### Удалить USB фильтр или глобальный фильтр

Используйте команду `VBoxManage usbfilter remove` для удаления USB фильтра.

## Примеры

Следующая команда отображает доступные USB устройства в хост-системе.

    $ VBoxManage list usbhost

Следующая команда добавляет USB фильтр, называемый `filter01` к ВМ `ol7`. Фильтр определяет флеш-накопитель Kingston DataTraveler и помещается первым в списке USB фильтров ВМ.

    $ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545

Следующая команда удаляет USB фильтр, который второй в списке ВМ `ol7` VM.

    $ VBoxManage usbfilter remove 1 --target ol7