Product Documentation

Configure USB redirection

Sep 27, 2016

Version 1.4 of the Linux VDA provides support for USB redirection. With this functionaliy, USB devices are shared among Citrix Receiver and the Linux VDA desktop. Once a USB device is redirected to the desktop, the user can use the USB device as if it were locally connected.  

USB redirection includes three main areas of functionality:

  • open soure project implementation (VHCI)
  • VHCI service
  • USB service

Open source VHCI

This portion of the USB redirection feature develops a general USB device sharing system over an IP network. It consists of a Linux kernel driver and some user mode libraries, which allows you to communicate with the kernel driver to get all the USB data. In the Linux VDA implementation, Citrix reuses the kernel driver of VHCI, however all the USB data transfers between Linux VDA and Citrix Receiver are encapsulated in the Citrix ICA protocol package.

VHCI service

The VHCI service is an open source service provided by Citrix to communicate with VHCI kernel module. This service works as a gateway between VHCI and the Citrix USB service.

USB service

The USB service represents a Citrix module that manages all the virtualization and data transfers on the USB device.

This article contains the following sections:

How USB redirection works

Typically, if a USB device is redirected successfully to the Linux VDA client, one or more device nodes are created in the system /dev path. However, in some cases the redirected device cannot be used by an active Linux VDA session. USB devices rely on drivers to function properly (and some devices require special drivers), and in some cases drivers are not provided, which results in some redirected USB devices being inaccessible to an active Linux VDA session. When situations like these occur, the drivers must be installed and the system must be configured properly to ensure USB device connectivity.

With version 1.4, the Linux VDA supports a list of USB devices that are sucessfully redirected to the client. In addition, the device is properly mounted, especially the USB disk, allowing the user to access the disk without any additional configuration.

Configuring USB redirection

A Citrix policy controls whether USB device redirection is enabled or disabled. In addition, the type of device can also be specified using s DDC policy. When configuring USB redirection for the Linux VDA, the following must be configured:

  • client USB device redirection policy
  • client USB device redirection rules

Enable USB redirection policy

In Citrix Studio, enable (or disable) USB device redirection to and from the client (for workstation hosts only).

In the Edit Setting dialog:

  1. Select Allowed.
  2. Click OK.
localized image

Setting USB redirection rules

After enabling the USB redirection policy, set redirection rules using Citrix Studio by specifying which devices are allowed (or denied) on the Linux VDA client. 

In the Client USB device redirection rules dialog:

  1. Click New to add a redirection rule, or click Edit to review an existing rule. 
  2. After creating (or modifying) a rule, click OK.
localized image

注意

To learn more about configuring generic USB redirection, refer to the Citrix Generic USB Redirection Configuration Guide.

Troubleshoot USB redirection issues

Use the information in this section to troubleshoot various issues that you might encounter when using the Linux VDA.

No devices on the Receiver toolbar

In some cases, you might not be able to see devices listed on the Citrix Receiver toolbar, which indicates that no USB redirection is taking place. If this occurs, verify the following:

  • the policy is configured to allow USB redirection
  • the Kernel module is compatible with your kernel
localized image

USB devices can be seen in the Receiver toolbar, but are labeled policy restricted, which results in failed redirection

This issue occurs because of the device's policy configuration. In such cases:

  • configure the Linux VDA policy to enable redirection
  • Verify if any additional policy restrictions are configured in the Receiver registry; a device might be blocked by the Receiver registry setting. Check DeviceRules in the registry path to ensure that the device is not denied access by this setting:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\GenericUSB

注意

For more information, see How to Configure Automatic Redirection of USB Devices on the Citrix Support site.

A USB device is redirected successfully, but I cannot use it in my session 

In most cases, only USB devices in the supported devices list can be redirected, however, in some cases other kinds of devices may be redirected into an active Linux VDA session. In these situations, for every redirected device, a node owned by the user is created in the system /dev path. However, it is the drivers and the configuration that determine whether the user can use the device successfully. If you find a device owned (plugged in) but inaccessible, add the device to an unrestricted policy.

注意

In the case of USB drives, the Linux VDA configures and mounts the disk. The user (and only the owner who installed it) can access the disk without any additional configuration. This might not be the case for device that are not in the supoorted device list.

Building the VHCI kernel module

USB redirection depends on the VHCI kernel modules (usb-vhci-hcd.ko and usb-vhci-iocif.ko). These modules are part of the Linux VDA distribution (as part of the RPM package). They are compiled based on the official Linux distribution kernels and are noted in the table below:

Supported Linux distribution Kernel version
RHEL 6.8 2.6.32-573.8.1.el6.x86_64
RHEL 7.2 3.10.0-327.4.4.el7.x86_64
SUSE 11.4 3.0.101-0.47.55-default
SUSE 12.1 3.12.43-52.6-default

Important

If the kernel of your machine is not compatible with the driver built by Citrix for the Linux VDA, the USB service may fail to start. In this case you cannot use the USB redirection feature unless you build your own VHCI kernel modules.

Verify if your kernel is consistent with the modules built by Citrix

On the command line, execute the following command to verify if the kernel is consistent:

command 複製

insmod /opt/Citrix/VDA/lib64/usb-vhci-hcd.ko

If the command executes successfully, it means that the kernel module has loaded successfully and that the version is consistent with the one installed by Citrix. 

If the command executes with errors, it means that the kernel is inconsistent with the Citrix module and must be rebuilt.

Rebuilding the VHCI kernel module

If the kernel module is inconsistent with the Citrix version, perform the following:

1. Build the VHCI kernel module. Download the VHCI source code from the project page.

2. Build the kernel module based on the header files and the Module.symvers file. Use the following steps to install the kernel header files and create Module.symvers based on the appropriate Linux distribution:

RHEL 7.2

command 複製

yum install kernel-devel

RHEL 6.8

command 複製

yum install kernel-headers

SUSE 12.1

command 複製

zypper install kernel-devel

zypper install kernel-source

SUSE 11.4

command 複製

zypper install kernel-source

提示

If the installation is successful, there will be a kernel folder resembling:

/usr/src/kernels/3.10.0-327.10.1.el7.x86_64

3.  In the folder (/usr/src/kernels/3.10.0-327.10.1.el7.x86_64) verify that the file Module.symvers is present. If this file is not in the directory, you must build the kernel to get this file (e.g., make oldconfig; make prepare;make modules;make) or copy it from /usr/src/kernels/3.10.0-327.10.1.el7.x86_64-obj/x86_64/defaults/module.*  

4.  vhci-hcd-1.15/Makefile, change the Makefile of VCHI, set KDIR to the kernel directory: 

command 複製

#KDIR = $(BUILD_PREFIX)/lib/modules/$(KVERSION)/build

KDIR = usr/src/kernels/3.10.0-327.10.1.el7.x86_64

5.  cd vhci-hcd-1.15/ and make; build the VHCI kernel.

注意

If the build was successful, usb-vhci-hcd.ko and usb-vhci-iocifc.ko are created in the vhci-hcd-1.15/directory.

6. Replace the kernel module with the newly built one: cp -f usb-vhci-*.ko /opt/Citrix/VDA/lib64/

7. Restart the USB service:  service ctxusbsd restart

8. Log off and log on to the the session again. Check to see if USB redirection is functioning.

Known issues

  • Unable to unmount the redirected USB disk. For the access control of all USB disks redirected from Citrix Receiver, the Linux VDA manages all of these devices under administrative privilege to ensure that only the owner can access the redirected device. As a result, the user is not permitted to unmount the device without the administrative privilege.
localized image
  • File lost when you stop redirecting a USB disk.  If you redirect a USB disk into a session and try to modify it (for example, create some files on the disk), then stop redirecting it immediately using the Receiver toolbar, the file you modified (or created) can be lost. 

This issue occurs because when you write data to a file system, the system mounts the memory cache in the file system, the data is not actually written to the disk itself. If you stop redirecting using the Receiver toolbar, there is no time remaining for the data being flushed into the disk, which results in lost data. 

To resolve this issue, whenever you write data into the disk, use the sync command in a terminal to flush data into the disk, then stop USB redirection.

localized image

Supported USB devices

The following devices have been verified to work with this version of the Linux VDA. Other devices may be freely used, with unexpected results:

USB mass storage device VID:PID File system
Netac Technology Co., Ltd 0dd8:173c FAT32
Kingston Datatraveler 101 II 0951:1625 FAT32
Kingston Datatraveler GT101 G2 1567:8902 FAT32
SanDisk SDCZ80 flash drive 0781:5580 FAT32
SanDisk Cruzer 16GB 1058:10B8 FAT32
WD HDD  0781:5567 FAT32

 

USB 3D mouse VID:PID
3DConnexion SpaceMouse Pro   046d: c62b

 

USB scanner VID:PID
Epson Perfection V330 photo        04B8: 0142