Product Documentation

Configure USB support

Mar 19, 2015
HDX USB device redirection enables redirection of USB devices to and from the user's client device. For example, a user can connect a flash drive to a local computer, and access it remotely from within a virtual desktop or a Virtual Machine (VM) hosted application, A "plug and play" capability allows Picture Transfer Protocol (PTP) devices such as digital cameras, Media Transfer Protocol (MTP) devices such as digital audio players or portable media players, and point-of-sale (POS) devices to be used in a XenApp session.
Note: Double-hop USB is not supported. That is, if a user connects to a VM hosted application session for a hosted desktop, the VM hosted application session does not have USB support.
USB redirection is available on the following clients:
  • Receiver for Windows
  • Receiver for Linux

By default, USB redirection is allowed for certain classes of USB devices, and denied for others. See the Receiver documentation for a list. You can restrict the types of USB devices made available to the virtual desktop by updating the list of USB devices supported for redirection, as described later in this document.

Important: In environments where security separation between client and server is needed, users should connect only appropriate USB devices.
Optimized virtual channels are available to redirect most popular USB devices, and provide superior performance and bandwidth efficiency over a WAN. The level of support provided depends on the client installed on the user device; see the Receiver documentation for support information. Optimized virtual channels are usually the best option, especially in high latency environments.
Note: For USB redirection purposes, XenApp treats a SMART board like a mouse.

In XenDesktop, specialty devices for which there is no optimized virtual channel are supported by falling back to a Generic USB virtual channel that provides raw USB redirection. For information on USB devices tested with XenDesktop, see http://support.citrix.com/article/ctx123569. Some advanced device-specific features, such as Human Interface Device (HID) buttons on a webcam, may not work as expected with the optimized virtual channel; if this is an issue, use the Generic USB virtual channel.

Certain devices are not redirected by default, and are only available to the local session. For example, it would not be appropriate to redirect a network interface card that is attached to the user device's system board by internal USB.

To enable USB support

The following Citrix policy settings control USB support:
  • Client USB device redirection - The default is Prohibited.
  • Client USB device redirection rules - Rules only apply to devices using Generic USB redirection. Therefore, rules do not apply to devices using specialized or optimized redirection, such as CDM.
  • Client USB Plug and Play device redirection - The default is Allowed, to permit plug-and-play of PTP, MTP, and POS devices in a XenApp session.
  • Client USB device redirection bandwidth limit - The default is 0 (zero, which means no maximum).
  • Client USB device redirection bandwidth limit percent - The default is 0 (zero, which means no maximum).
For detailed instructions on configuring policies, see Manage Citrix policies in Citrix eDocs.
To enable USB support:
  1. Add the Client USB device redirection setting to a policy and set its value to Allowed.
  2. (Optional) To update the list of USB devices available for remoting, add the Client USB device redirection rules setting to a policy and specify the USB policy rules, as explained later in this document.
  3. Enable USB support when you install the client on user devices; see the Receiver documentation for specific configuration information. If you specified USB policy rules for the Virtual Delivery Agent in the previous step, specify those same policy rules on the client.
    Note:

    If you are using a thin client, consult the manufacturer for details of USB support and any configuration you may need to carry out.

Update the list of USB devices available for remoting (Receiver for Windows 4.2)

USB devices are automatically redirected when USB support is enabled and the USB user preference settings are set to automatically connect USB devices. USB devices are also automatically redirected when operating in Desktop Appliance mode and the connection bar is not present. In some instances, however, you might not want to automatically redirect all USB devices. For more information, see CTX123015.

Users can explicitly redirect devices that are not automatically redirected by selecting them from the USB device list. To prevent USB devices from ever being listed or redirected, you can specify device rules on the client and the VDA, as explained below.

You can update the range of USB devices available for remoting by specifying USB device redirection rules for both Receiver and the VDA to override the default USB policy rules.
  • Edit the user device registry. An Administrative template (ADM file) is included on the installation media so you can change the user device through Active Directory Group Policy: dvd root \os\lang\Support\Configuration\icaclient_usb.adm.
  • Edit the administrator override rules in the VDA registry on the Server OS machines. An ADM file is included on the installation media so you can change the VDA through Active Directory Group Policy: dvd root \os\lang\Support\Configuration\vda_usb.adm.
Caution: Editing the registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

The product default rules are stored in HKLM\SOFTWARE\Citrix\PortICA\GenericUSB\DeviceRules. Do not edit these product default rules. Instead, use them as a guide for creating administrator override rules as explained below. The GPO overrides are evaluated before the product default rules.

The administrator override rules are stored in HKLM\SOFTWARE\Policies\Citrix\PortICA\GenericUSB\DeviceRules. GPO policy rules take the format {Allow:|Deny:} followed by a set of tag=value expressions separated by white space. The following tags are supported:

Tag Description
VID Vendor ID from the device descriptor
PID Product ID from the device descriptor
REL Release ID from the device descriptor
Class Class from either the device descriptor or an interface descriptor; see the USB Web site at http://www.usb.org/ for available USB Class Codes
SubClass Subclass from either the device descriptor or an interface descriptor
Prot Protocol from either the device descriptor or an interface descriptor
When creating new policy rules, note the following:
  • Rules are case-insensitive.
  • Rules may have an optional comment at the end, introduced by #. A delimiter is not required, and the comment is ignored for matching purposes.
  • Blank and pure comment lines are ignored.
  • White space is used as a separator, but cannot appear in the middle of a number or identifier. For example, Deny: Class = 08 SubClass=05 is a valid rule, but Deny: Class=0 Sub Class=05 is not.
  • Tags must use the matching operator =. For example, VID=1230.
  • Each rule must start on a new line or form part of a semicolon-separated list.
    Important: If you are using the ADM template file, you must create rules on a single line, as a semicolon-separated list.
When working with optimized devices such as mass storage, you usually redirect the device using the specialized CDM channel rather than with policy rules. However, if either of the following conditions exist, the optimized device is available in the device list in the desktop viewer for Generic USB redirection:
  • Auto redirection for storage device is set (for example, AutoRedirectStorage = 1); for more information, see CTX123015.
  • Simplify device connections for me is not selected; for more information, see CTX136716.
Examples:
  • The following example shows an administrator-defined USB policy rule for vendor and product identifiers:
    Allow: VID=046D PID=C626 # Allow Logitech SpaceNavigator 3D Mouse 
                   Deny: VID=046D # Deny all Logitech products 
    
  • The following example shows an administrator-defined USB policy rule for a defined class, sub-class, and protocol:
     Deny: Class=EF SubClass=01 Prot=01 # Deny MS Active Sync devices 
             Allow: Class=EF SubClass=01 # Allow Sync devices 
             Allow: Class=EF # Allow all USB-Miscellaneous devices 
           
    

To update the list of USB devices available for remoting

By default, USB devices are automatically redirected when USB support is enabled, and the USB user preference settings are set to automatically connect USB devices. USB devices are also automatically redirected when operating in a desktop appliance mode or with VM hosted applications. In some instances, however, you may not want to automatically redirect all USB devices. For more information, see http://support.citrix.com/article/CTX123015.
Note: Desktop Viewer users can explicitly redirect devices that are not automatically redirected by selecting them from the USB device list. To prevent USB devices from ever being listed or redirected, you can specify device rules on the client and the VDA, as explained below.
You can update the range of USB devices available for remoting by specifying USB device redirection rules on both the client and the VDA to override the default USB policy rules.
Note: Device rules are enforced on both sides; if you don't change both, devices may not be allowed through.
  • Edit the client registry (or the .ini files in the case of the Receiver for Linux). For information about how to do this, see the relevant client documentation. An Administrative template (ADM file) is included on the installation media to allow you to make changes to the client through Active Directory Group Policy: dvd root \os\lang\Support\Configuration\icaclient_usb.adm.
  • Edit the administrator override rules in the VDA registry on the computer(s) hosting the desktops and applications. Information about how to do this is included in the rest of this section. An ADM file is included on the installation media to allow you to make changes to the VDA through Active Directory Group Policy: dvd root \os\lang\Support\Configuration\vda_usb.adm.
Caution: Editing the registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

The product default rules are stored in HKLM\SOFTWARE\Citrix\PortICA\GenericUSB Type=String Name="DeviceRules".

Note: You can examine these product default rules, but do not edit them. Instead, use administrator override rules as explained below; the GPO overrides are evaluated before the product default rules.

The administrator override rules are stored in HKLM\SOFTWARE\Policies\Citrix\PortICA\GenericUSB Type=String Name="DeviceRules".

GPO policy rules take the format {Allow:|Deny:} followed by a set of tag=value expressions separated by white space. The following tags are supported:

Tag Description
VID Vendor ID from the device descriptor
PID Product ID from the device descriptor
REL Release ID from the device descriptor
Class Class from either the device descriptor or an interface descriptor; see the USB Web site at http://www.usb.org/ for available USB Class Codes
SubClass Subclass from either the device descriptor or an interface descriptor
Prot Protocol from either the device descriptor or an interface descriptor
When creating new policy rules, note the following:
  • Rules are case-insensitive.
  • Rules may have an optional comment at the end, introduced by #. A delimiter is not required, and the comment is ignored for matching purposes.
  • Blank and pure comment lines are ignored.
  • White space is used as a separator, but cannot appear in the middle of a number or identifier. For example, Deny: Class = 08 SubClass=05 is a valid rule, but Deny: Class=0 Sub Class=05 is not.
  • Tags must use the matching operator =. For example, VID=1230.
  • Each rule must start on a new line or form part of a semicolon-separated list.
    Important: If you are using the ADM template file, you must create rules on a single line, as a semicolon-separated list.

Use rules with optimized devices

When working with optimized devices, for example, mass storage, you usually redirect the device using the specialized CDM channel, rather than with policy rules. However, if either of the following conditions exist, the optimized device is available in the device list in the desktop viewer for Generic USB redirection:

Examples

This example shows an administrator-defined USB policy rule using vendor and product identifiers:

Allow: VID=046D PID=C626 # Allow Logitech SpaceNavigator 3D Mouse 
        Deny: VID=046D # Deny all Logitech products 

This example shows administrator-defined USB policy rules using USB defined class, sub-class and protocol:

Deny: Class=EF SubClass=01 Prot=01 # Deny MS Active Sync devices 
                Allow: Class=EF SubClass=01 # Allow Sync devices 
                Allow: Class=EF # Allow all USB-Miscellaneous devices 

Using and removing USB devices

Users can connect a USB device before or after starting a virtual session.

When using Receiver for Windows, the following apply:
  • Devices connected after a session starts appear in the USB menu of the Desktop Viewer immediately.
  • If a USB device is not redirecting properly, sometimes you can resolve the problem by waiting to connect the device until after the virtual session has started ("hot plugging").
  • To avoid data loss, use the Windows Safe removal menu before removing the USB device.