18.3. The USB Filter Editor

18.3.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 USB Filter Editor installer from "Installers and Images for Red Hat Virtualization Manager".

Installing the USB Filter Editor

  1. On a Windows machine, run the .msi file you downloaded for the USB Filter Editor.
  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.

18.3.2. The USB Filter Editor Interface

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

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 18.1. USB Editor Fields

NameDescription

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.

18.3.3. Adding a USB Policy

Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.

Adding a USB Policy

  1. Click Add.
  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 18.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.

    306
  3. Click FileSave to save the changes.

You have added a USB policy to the USB Filter Editor. USB filter policies must be exported to the Red Hat Virtualization Manager to take effect.

18.3.4. Removing a USB Policy

Double-click the USB Filter Editor shortcut icon on your desktop to open the editor.

Removing a USB Policy

  1. Select the policy to be removed.
  2. Click Remove. A message displays prompting you to confirm that you want to remove the policy.
  3. Click Yes to confirm that you want to remove the policy.
  4. Click FileSave to save the changes.

You have removed a USB policy from the USB Filter Editor. USB filter policies must be exported to the Red Hat Virtualization Manager to take effect.

18.3.5. Searching for USB Device Policies

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.

Searching for USB Device Policies

  1. Click Search. The Attached USB Devices window displays a list of all the attached 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.

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

18.3.6. Exporting a USB Policy

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.

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

18.3.7. Importing a USB Policy

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

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.