Configure USB redirection

USB devices are shared between Citrix Workspace app and the Linux VDA desktop. When a USB device is redirected to the desktop, the user can use the USB device as if it were locally connected.

Tip:

We recommend using USB redirection when the network latency is lower than 100 milliseconds. Do not use USB redirection when the network latency is higher than 200 milliseconds.

USB redirection includes three main areas of functionality:

• Open-source 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 that allow 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 the Linux VDA and Citrix Workspace app are encapsulated in the Citrix ICA protocol package.

VHCI service:

The VHCI service is an open-source service provided by Citrix to communicate with the 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.

How USB redirection works

Typically, if a USB device is redirected successfully to the Linux VDA, one or more device nodes are created in the system /dev path. Sometimes, however, the redirected device is not usable for an active Linux VDA session. USB devices rely on drivers to function properly and some devices require special drivers. If drivers are not provided, the redirected USB devices are inaccessible to the active Linux VDA session. To ensure USB device connectivity, install the drivers and configure the system properly.

The Linux VDA supports a list of USB devices that are successfully redirected to and from the client. In addition, the device is properly mounted, especially the USB disk, allowing the user to access the disk without any additional configuration.

Supported USB devices

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

Note:

The Linux VDA supports only USB 2.0 protocols.

Configure 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 a Delivery Controller policy. When configuring USB redirection for the Linux VDA, configure the following policy and rules:

• 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.

Set USB redirection rules

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

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 editing) a rule, click OK.

For more information about configuring generic USB redirection, see Citrix Generic USB Redirection Configuration Guide.

Build 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 following table:

Important:

If the kernel of your machine is not compatible with the driver built for the Linux VDA, the USB service might fail to start. In this case, you can use the USB redirection feature only if you build your own VHCI kernel modules.

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

On the command line, run the following command to verify whether the kernel is consistent:

insmod /opt/Citrix/VDA/lib64/usb-vhci-hcd.ko
<!--NeedCopy-->

If the command runs successfully, the kernel module has loaded successfully and the version is consistent with the one installed by Citrix.

If the command runs with errors, the kernel is inconsistent with the Citrix module and must be rebuilt.

Rebuild the VHCI kernel module

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

1. Download the LVDA source code from the Citrix download site. Select the file contained in the section “Linux Virtual Delivery Agent (sources).”

2. Unzip the citrix-linux-vda-sources.zip file. Navigate to linux-vda-souces/vhci-hcd-1.15.tar.bz2 and unzip the VHCI source files by using tar xvf vhci-hcd-1.15.tar.bz2.

3. 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/CentOS:

   yum install kernel-devel
   <!--NeedCopy-->
   

   SUSE 12:

   zypper install kernel-devel
   
   zypper install kernel-source
   <!--NeedCopy-->
   

   Ubuntu:

   apt-get install linux-headers
   <!--NeedCopy-->
   

   Tip:

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

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

4. In the /usr/src/kernels/3.10.0-327.10.1.el7.x86_64 folder, verify that the Module.symvers file is present. If this file is not in the folder, build the kernel (by running the following commands in sequence: make oldconfig; make prepare; make modules; make) to get this file or copy it from /usr/src/kernels/3.10.0-327.10.1.el7.x86_64-obj/x86_64/defaults/module.*

5. Run the following commands to install the development tools.

   RHEL 8, CentOS 8:

   yum groupinstall 'Development Tools'
   
   yum install elfutils-libelf-devel
   <!--NeedCopy-->
   

   RHEL 7, CentOS 7:

   yum groupinstall 'Development Tools'
   <!--NeedCopy-->
   

   Ubuntu 20.04, Ubuntu 18.04, Debian 10:

   apt install build-essential flex bison libelf-dev
   <!--NeedCopy-->
   

   Ubuntu 16.04:

   apt install build-essential flex bison
   
   <!--NeedCopy-->
   

6. In the vhci-hcd-1.15/Makefile file, change the Makefile of VCHI and set KDIR to the kernel directory:

   #KDIR = $(BUILD_PREFIX)/lib/modules/$(KVERSION)/build
   
   KDIR = /usr/src/kernels/3.10.0-327.10.1.el7.x86_64
   <!--NeedCopy-->
   

7. In the vhci-hcd-1.15/ folder, run make to build the VHCI kernel.

   Note:

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

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

9. Restart the USB service:

   service ctxusbsd restart
   <!--NeedCopy-->
   

10. Log off and back on to the session again. Check whether USB redirection is functioning.

Troubleshoot kernel building issues

The following errors might occur when you build the VHCI module with specific kernels:

• The implicit declaration of function 'copy\_to\_user' error might occur, see the following screen capture:

  

  The error occurs due to header file changes in the kernels. As a workaround, add the #include <linux/uaccess.h> line to the vhci-hcd-1.15/usb-vhci-iocifc.c file.

  

• The 'driver\_attr\_debug_output' undeclared error might occur, see the following screen capture:

  

  The error occurs when symbols are missing on the kernel. As a workaround, disable the macro definition for DEBUG in the vhci-hcd-1.15/usb-vhci-iocifc.c and vhci-hcd-1.15/usb-vhci-hcd.c files.

  

• The 'make[3]: *** No rule to make target 'arch/x86/tools/relocs_32.c', needed by 'arch/x86/tools/relocs_32.o'. Stop. error might occur, see the following screen capture:

  

  As a workaround, replace SUBDIRS=$(PWD) with M=$(shell pwd) by using the following commands under the vhci-hcd-1.15/ path:

   sed -i 's/SUBDIRS=$(PWD)/M=$(shell pwd)/g' Makefile
  
   sed -i 's/SUBDIRS=$(PWD)/M=$(shell pwd)/g' test/Makefile
   <!--NeedCopy-->
  

• The ./include/uapi/linux/stat.h:30:17: error: expected ')' before numeric constant
#define S_IRUSR 00400 error might occur, see the following screen capture:

  

  Run the following commands to work around the issue:

   sed -i 's/show_debug_output/debug_output_show/g' usb-vhci-iocifc.c usb-vhci-hcd.c  
  
   sed -i 's/store_debug_output/debug_output_store/g' usb-vhci-iocifc.c usb-vhci-hcd.c  
  
   sed -i 's/static DRIVER_ATTR(debug_output, S_IRUSR | S_IWUSR, debug_output_show, debug_output_store);/static DRIVER_ATTR_RW(debug_output);/g' usb-vhci-iocifc.c usb-vhci-hcd.c
   <!--NeedCopy-->
  

• The ./arch/x86/include/asm/uaccess.h:433:29: error: invalid initializer __typeof__(ptr) __pu_ptr = (ptr); \ error might occur, see the following screen capture:

  

  As a workaround, change the 219 line of the usb-vhci-iocifc.c file from __put_user('\0', arg->bus_id); to __put_user('\0', arg->bus_id + 0);.

• The error: 'access_ok' undeclared (first use in this function)
if(unlikely((_IOC_DIR(cmd) & _IOC_READ) && !access_ok(VERIFY_WRITE, arg, _IOC_SIZE(cmd)))) error might occur, see the following screen capture:

  

  Run the following commands to work around the issue:

   sed -i 's/VERIFY_READ, //g' usb-vhci-iocifc.c  
   sed -i 's/VERIFY_WRITE, //g' usb-vhci-iocifc.c
   <!--NeedCopy-->
  

Troubleshoot USB redirection issues

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

Unable to unmount the redirected USB disk

For the access control of all USB disks redirected from Citrix Workspace app, the Linux VDA manages all these devices under administrative privilege to ensure that only the owner can access the redirected device. As a result, the user cannot unmount the device without the administrative privilege.

File lost when you stop redirecting a USB disk

If you redirect a USB disk to a session and try to modify it (for example, create some files on the disk), then stop redirecting it immediately using the toolbar of Citrix Workspace app, 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 written to the disk itself. If you stop redirecting using the toolbar of Citrix Workspace app, there is no time remaining for the data being flushed to the disk, which results in lost data. To resolve this issue, use the sync command in a terminal to flush data to the disk before stopping USB redirection.

No devices in the toolbar of Citrix Workspace app

Sometimes, you might not be able to see devices listed in the toolbar of Citrix Workspace app, which indicates that no USB redirection is taking place. If you encounter the issue, verify the following:

• The policy is configured to allow USB redirection
• The Kernel module is compatible with your kernel

Note:

The Devices tab is not available in Citrix Workspace app for Linux.

Failed redirection when USB devices can be seen in the toolbar of Citrix Workspace app, but are labeled policy restricted

When the issue occurs, do the following:

• Configure the Linux VDA policy to enable redirection.

• Check whether any additional policy restrictions are configured in the registry of Citrix Workspace app. 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

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

Typically, only supported USB devices can be redirected. Other devices might be redirected to an active Linux VDA session too. 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.

Note:

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 devices that are not in the supported device list.