A.4. USB Filter Editor

A virtual machine that is connected with the SPICE protocol can be configured to connect USB devices. To do so, the USB device has to be plugged into the client machine, then redirected to appear on the guest machine. Red Hat Enterprise Virtualization presently supports USB usage on the following clients and guests:
  • Client
    • Red Hat Enterprise Linux 6.0 and higher
    • Red Hat Enterprise Linux 5.5 and higher
    • Windows XP
    • Windows 7
    • Windows 2008
  • Guest
    • Windows XP
    • Windows 7
Further information on configuring clients and guests is available in the Red Hat Enterprise Virtualization User Portal Guide. This section concentrates on the use of the USB Filter Editor to define policies allowing, or restricting, the use of USB devices in the virtualized environment.
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.
    Attached USB Devices

    Figure A.5. Attached USB 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”.