Product SiteDocumentation Site

A.4. USB Filter Editor

The USB Filter Editor is a Windows tool used to configure a policy file named usbfilter.txt. The policy rules defined in this file allow, or deny, the passthrough of specific USB devices from client machines to virtual machines managed using Red Hat Enterprise Virtualization Manager. Once configured the policy file resides on the Red Hat Enterprise Virtualization Manager in the following location:
/usr/share/rhevm/rhevm.ear/userportal.war/org.ovirt.engine.ui.userportal.UserPortal/consoles/spice/usbfilter.txt
Changes to the USB filter policies take effect the next time the jbossas service on the Red Hat Enterprise Virtualization Manager server is restarted. To obtain the USB Filter Editor, download the USBFilterEditor.msi file from Red Hat Network, under the Red Hat Enterprise Virtualization Manager (v.3 x86_64) channel.
To install the USB Filter Editor
  1. On a Windows machine, launch the USBFilterEditor.msi installer that was obtained from Red Hat Network.
  2. You will be guided through a series of steps to install the USB Filter Editor on your machine. If you do not specify an alternative location, the USB Filter Editor will be installed by default in either C:\Program Files\RedHat\USB Filter Editor, or C:\Program Files(x86)\RedHat\USB Filter Editor depending on the version of Windows in use.
  3. When the installation completes, a shortcut icon is created on your desktop. This is how you launch the USB Filter Editor.

Important — Secure Copy Utility

To import and export filter policies from the Red Hat Enterprise Virtualization Manager it is necessary to use a Secure Copy (SCP) client. A Secure Copy tool for Windows machines is WinSCP (http://winscp.net).

A.4.1. Updating the USB Device Policy

The default USB device policy only allows virtual machines access to a limited range of USB devices. To allow the use of additional USB devices you must update the policy.
  1. Click the USB Filter Editor icon on your desktop. The Red Hat USB Filter Editor displays the current USB policies.
    Red Hat USB Filter Editor
    Figure A.1. Red Hat USB Filter Editor

  2. For each USB device, the Class, Vendor, Product, Revision and Action displays. The permitted devices display with an Allow action, the blocked devices display with a Block action.
  3. You can Add to, and Remove from, the list of devices that the policy allows virtual machines access to. The USB device policy rules are processed in the order in which they are listed. The Up and Down buttons enable you to move devices higher or lower in the list. The last rule in the list must always be the rule with action Block for any devices. This ensures that all devices that are not explicitly allowed in the policy are blocked.
    The Search button allows you to create policy rules based on the devices attached to the system the USB Filter Editor is being run on. Additionally the Import, and Export buttons allow you to move USB device policy files to and from the Red Hat Enterprise Virtualization Manager.
Table A.1. USB Editor Fields
Name Description
Class Type of USB device; for example, printers, mass storage controllers.
Vendor The manufacturer of the selected type of device.
Product The specific USB device model.
Revision The revision of the product.
Action Allow or block the specified device.

A.4.1.1. Adding a USB Policy

Double click the USB Filter Editor icon on your desktop. The Red Hat USB Filter Editor displays the current USB policies. You can specify the USB device and whether virtual machines can use them by adding a new policy.
To add a new policy, on the Red Hat USB Editor:
  1. Click the Add button. The Edit USB Criteria dialog displays:
    Edit USB Criteria
    Figure A.2. Edit USB Criteria

  2. Add any combination of USB devices, products, and vendors using the USB Class, Vendor ID, Product ID, and Revision check boxes and lists.
    To allow virtual machines to use the specified USB device, click the Allow button. Or, to block virtual machines from using the specified USB device, click the Block button. Click OK to exit the dialog box. This action adds the selected filter rule to the list.
    Example A.9. Adding a Device
    The following is an example of how to add USB Class Smartcard, device EP-1427X-2 Ethernet Adaptor, from manufacturer Acer Communications & Multimedia to the list of allowed devices.

  3. Click the Save entry in the File menu to save the changes.
  4. For USB filter policy changes to take effect they must also be exported to the Red Hat Enterprise Virtualization Manager, see Section A.4.2, “Export a USB Policy”.

A.4.1.2. Removing a USB Policy

Double click the USB Filter Editor icon on your desktop. The Red Hat USB Filter Editor displays the current USB policies.
To remove a policy, on the Red Hat USB Editor:
  1. Select the policy to be removed.
    Select USB Policy
    Figure A.3. Select USB Policy

  2. Click the Remove button. A message displays prompting you to confirm that you want to remove the policy.
    Edit USB Criteria
    Figure A.4. Edit USB Criteria

  3. Click the Yes button to confirm that you want to remove the policy.
  4. Click the Save entry in the File menu to save the changes.
  5. For USB filter policy changes to take effect they must also be exported to the Red Hat Enterprise Virtualization Manager, see Section A.4.2, “Export a USB Policy”.

A.4.1.3. Searching for USB Device Policies

You can search for policies using the Search feature of the Red Hat USB Filter Editor.
  1. Double click the USB Filter Editor icon on your desktop. The Red Hat USB Filter Editor displays the current USB policies.
  2. Click the Search button. The Attached USB Devices dialog box displays a list of all the attached devices.
  3. Select the device and click the Allow or Block button as appropriate. Double click the selected device to close the dialog box. A policy rule for the device is added to the list.
  4. Use the Up and Down buttons to change the position the new policy rule in the list.
  5. Click the Save entry in the File menu to save the changes.
  6. For USB filter policy changes to take effect they must also be exported to the Red Hat Enterprise Virtualization Manager, see Section A.4.2, “Export a USB Policy”.