19.4. The USB Filter Editor

19.4.1. Installing the USB Filter Editor

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 automatic pass-through of specific USB devices from client machines to virtual machines managed using the Red Hat Virtualization Manager. The policy file resides on the Red Hat 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 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.

Procedure 19.3. 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 Virtualization Manager. A Secure Copy tool for Windows machines is WinSCP (http://winscp.net).
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.

19.4.2. The USB Filter Editor Interface

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

    Figure 19.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 19.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 rules 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.

19.4.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 19.4. Adding a USB Policy

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

    Figure 19.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 19.1. 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 FileSave 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 Virtualization Manager to take effect.

19.4.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 19.5. Removing a USB Policy

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

    Figure 19.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 19.4. Edit USB Criteria

  3. Click Yes to confirm that you want to remove the policy.
  4. Click FileSave 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 Virtualization Manager to take effect.

19.4.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 19.6. 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 19.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 FileSave to save the changes.
Result

You have searched the attached USB devices. USB filter policies need to be exported to the Red Hat Virtualization Manager to take effect.

19.4.6. Exporting a USB Policy

Summary

USB device policy changes need to be exported and uploaded to the Red Hat 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 19.7. 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 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 Virtualization Manager, restart the ovirt-engine service.
    # systemctl restart ovirt-engine.service
Result

The USB device policy will now be implemented on virtual machines running in the Red Hat Virtualization environment.

19.4.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 19.8. Importing a USB Policy

  1. Using a Secure Copy client, such as WinSCP, download the usbfilter.txt file from the server running Red Hat Virtualization Manager. The file can be found 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.