⁠20.5. The USB Filter Editor

20.5.1. Installing the USB Filter Editor
20.5.2. The USB Filter Editor Interface
20.5.3. Adding a USB Policy
20.5.4. Removing a USB Policy
20.5.5. Searching for USB Device Policies
20.5.6. Exporting a USB Policy
20.5.7. Importing a USB Policy

⁠20.5.1. Installing the USB Filter Editor

Summary
The USB Filter Editor is a Windows tool used to configure the usbfilter.txt policy file. The policy rules defined in this file allow or deny the pass-through of specific USB devices from client machines to virtual machines managed using the Red Hat Enterprise Virtualization Manager. The policy file resides on the Red Hat Enterprise Virtualization Manager in the following location:

/etc/ovirt-engine/usbfilter.txt
Changes to USB filter policies do not take effect unless the ovirt-engine service on the Red Hat Enterprise Virtualization Manager server is restarted.
Download the USBFilterEditor.msi file from the Content Delivery Network: https://rhn.redhat.com/rhn/software/channel/downloads/Download.do?cid=20703. The file works with Red Hat Enterprise Virtualization 3.0, 3.1, 3.2, 3.3, 3.4, and 3.5.
⁠

Procedure 20.4. Installing the USB Filter Editor

  1. On a Windows machine, launch the USBFilterEditor.msi installer obtained from the Content Delivery Network.
  2. Follow the steps of the installation wizard. Unless otherwise specified, 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 your version of Windows.
  3. A USB Filter Editor shortcut icon is created on your desktop.

Important

Use a Secure Copy (SCP) client to import and export filter policies from the Red Hat Enterprise Virtualization Manager. A Secure Copy tool for Windows machines is WinSCP (http://winscp.net).
Result
The default USB device policy provides virtual machines with basic access to USB devices; update the policy to allow the use of additional USB devices.

⁠20.5.2. The USB Filter Editor Interface

  • Double-click the USB Filter Editor shortcut icon on your desktop.
    ⁠
    Red Hat USB Filter Editor

    Figure 20.1. Red Hat USB Filter Editor

The Red Hat USB Filter Editor interface displays the Class, Vendor, Product, Revision, and Action for each USB device. Permitted USB devices are set to Allow in the Action column; prohibited devices are set to Block.
⁠

Table 20.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.
The USB device policy rules are processed in their listed order. Use the Up and Down buttons to move devices higher or lower in the list. The universal Block rule needs to remain as the lowest entry to ensure all USB devices are denied unless explicitly allowed in the USB Filter Editor.

⁠20.5.3. Adding a USB Policy

Summary
Add a USB policy to the USB Filter Editor.
Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.
⁠

Procedure 20.5. Adding a USB Policy

  1. Click the Add button. The Edit USB Criteria window opens:
    ⁠
    Edit USB Criteria

    Figure 20.2. Edit USB Criteria

  2. Use the USB Class, Vendor ID, Product ID, and Revision check boxes and lists to specify the device.
    Click the Allow button to permit virtual machines use of the USB device; click the Block button to prohibit the USB device from virtual machines.
    Click OK to add the selected filter rule to the list and close the window.
    ⁠

    Example 20.8. Adding a Device

    The following is an example of how to add USB Class Smartcard, device EP-1427X-2 Ethernet Adapter, from manufacturer Acer Communications & Multimedia to the list of allowed devices.
  3. Click File → Save to save the changes.
Result
You have added a USB policy to the USB Filter Editor. USB filter policies need to be exported to the Red Hat Enterprise Virtualization Manager to take effect.

⁠20.5.4. Removing a USB Policy

Summary
Remove a USB policy from the USB Filter Editor.
Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.
⁠

Procedure 20.6. Removing a USB Policy

  1. Select the policy to be removed.
    ⁠
    Select USB Policy

    Figure 20.3. Select USB Policy

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

    Figure 20.4. Edit USB Criteria

  3. Click Yes to confirm that you want to remove the policy.
  4. Click File → Save to save the changes.
Result
You have removed a USB policy from the USB Filter Editor. USB filter policies need to be exported to the Red Hat Enterprise Virtualization Manager to take effect.

⁠20.5.5. Searching for USB Device Policies

Summary
Search for attached USB devices to either allow or block them in the USB Filter Editor.
Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.
⁠

Procedure 20.7. Searching for USB Device Policies

  1. Click Search. The Attached USB Devices window displays a list of all the attached devices.
    ⁠
    Attached USB Devices

    Figure 20.5. Attached USB Devices

  2. Select the device and click Allow or Block as appropriate. Double-click the selected device to close the window. A policy rule for the device is added to the list.
  3. Use the Up and Down buttons to change the position of the new policy rule in the list.
  4. Click File → Save to save the changes.
Result
You have searched the attached USB devices. USB filter policies need to be exported to the Red Hat Enterprise Virtualization Manager to take effect.

⁠20.5.6. Exporting a USB Policy

Summary
USB device policy changes need to be exported and uploaded to the Red Hat Enterprise Virtualization Manager for the updated policy to take effect. Upload the policy and restart the ovirt-engine service.
Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.
⁠

Procedure 20.8. Exporting a USB Policy

  1. Click Export; the Save As window opens.
  2. Save the file with a file name of usbfilter.txt.
  3. Using a Secure Copy client, such as WinSCP, upload the usbfilter.txt file to the server running Red Hat Enterprise Virtualization Manager. The file must be placed in the following directory on the server:

    /etc/ovirt-engine/
  4. As the root user on the server running Red Hat Enterprise Virtualization Manager, restart the ovirt-engine service. 
    # service ovirt-engine restart
Result
The USB device policy will now be implemented on virtual machines running in the Red Hat Enterprise Virtualization environment.

⁠20.5.7. Importing a USB Policy

Summary
An existing USB device policy must be downloaded and imported into the USB Filter Editor before you can edit it.
⁠

Procedure 20.9. Importing a USB Policy

  1. Using a Secure Copy client, such as WinSCP, upload the usbfilter.txt file to the server running Red Hat Enterprise Virtualization Manager. The file must be placed in the following directory on the server:

    /etc/ovirt-engine/
  2. Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.
  3. Click Import to open the Open window.
  4. Open the usbfilter.txt file that was downloaded from the server.
Result
You are able to edit the USB device policy in the USB Filter Editor.