Linux Virtual Delivery Agent

USB device redirection

August 9, 2024

Contributed by:

B C

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

Tip:

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

USB device redirection includes three main areas of functionality:

Open-source USB/IP project
Citrix USB session module
Citrix USB service module

Open-source USB/IP project:

The USB/IP project consists of a Linux kernel driver and some user mode libraries that let you communicate with the kernel driver to get all USB data.

The Linux VDA implements USB device redirection based on the open-source USB/IP project and reuses the kernel driver and user mode libraries of USB/IP. However, all USB data transfers between the Linux VDA and Citrix Workspace app are encapsulated by the Citrix ICA USB protocol.

Citrix USB session module:

The Citrix USB session module acts as a communication bridge between the USB/IP kernel module and Citrix Workspace app.

Citrix USB service module:

The Citrix USB service module manages all operations on USB devices, for example, attach or detach USB devices.

How USB device 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 isn’t usable for an active Linux VDA session. USB devices rely on drivers to function properly and some devices require special drivers. If drivers aren’t provided, the redirected USB devices are inaccessible to the active Linux VDA session. To make sure of USB device connectivity, install the drivers and configure the system properly.

The Linux VDA supports a list of USB devices that are successfully redirected from the client.

Supported USB devices

Tip:

We have added support for USB 3.0 ports. You can insert USB 3.0 devices into USB 3.0 ports on a client device.

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

USB mass storage device	VID:PID	File system
`Netac Technology Co., Ltd`	0dd8:173c	FAT32, NTFS
`Kingston Datatraveler 101 II`	0951:1625	FAT32, NTFS
`Kingston Datatraveler GT101 G2`	1567:8902	FAT32, NTFS
`SanDisk SDCZ80 flash drive`	0781:5580	FAT32, NTFS
`WD HDD`	1058:10B8	FAT32, NTFS
`Toshiba Kingston DataTraveler 3.0 USB device`	0930:6545	FAT32, NTFS
`Taiwan OEM – OBSOLETE VendorCo ProductCode Disk 2.0`	FFFF:5678	FAT32, NTFS
`TD-RDF5A Transcend USB device`	8564:4000	FAT32, NTFS

Note:

To use NTFS on Amazon Linux 2, CentOS, RHEL, Rocky Linux, and SUSE, enable NTFS support on these distributions first.

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

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

Yubico USB	VID:PID
`Yubico YubiKey OTP+FIDO+CCID -Keyboard, HID`	1050:0407

Webcam USB	VID:PID
`Logitech composite USB device – WebCam, Audio`	0460:0825

Configure USB device redirection

(For CentOS, RHEL, and Rocky Linux only) Install or compile the USB/IP kernel module

The Linux VDA uses USB/IP as the virtual host controller for USB device redirection. Because in most cases the USB/IP kernel module is released with the Linux kernel version 3.17 and later, you don’t have to build the kernel module by default. However, the USB/IP kernel module is not available for CentOS, RHEL, and Rocky Linux. To use USB device redirection with these Linux distributions, you must install or compile the USB/IP kernel module. Download and install USB/IP from https://pkgs.org/download/kmod-usbip based on your Linux distribution.

Set USB device redirection policies

A Citrix policy controls whether USB device redirection is enabled or disabled. The type of device can also be specified using a Delivery Controller policy. When configuring USB device redirection for the Linux VDA, configure the following policy and rules:

Client USB device redirection policy
Client USB device redirection rules

Enable USB device redirection

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

In the Edit Setting dialog:

Select Allowed.
Click OK.

Enable USB device redirection

Set USB device 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:

Click New to add a redirection rule, or click Edit to review an existing rule.
After creating (or editing) a rule, click OK.

The client USB device redirection rule setting

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

Troubleshoot USB device redirection issues

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

Unable to unmount the redirected USB disk

The Linux VDA manages all USB disks redirected from Citrix Workspace app under the administrative privilege to make sure that only the owner can access the redirected device. As a result, you can unmount the device only with the administrative privilege.

Unable to unmount a device

File lost when you stop redirecting a USB disk

If you stop redirecting a USB disk immediately using the toolbar of Citrix Workspace app, the files you modified or created on the disk 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 isn’t written to the disk itself. If you stop redirecting using the toolbar of Citrix Workspace app, there’s no time remaining for 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.

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.

The devices tab in the workspace app toolbar

If you come across the issue, verify the following:

The policy is configured to allow USB device redirection.
The Citrix USB service module is running.

If the policy is not set correctly, correct it by referencing the Set USB device redirection policies section in this article.

If the Citrix USB service module is not running, complete the following steps:

Check whether a USB/IP kernel module is available on your Linux distribution using the following command:
```
modinfo usbip-core

```
If the output is shown as follows, install or compile the USB/IP kernel module based on your Linux distribution:
```
modinfo: ERROR: Module usbip-core not found.

```
- For Amazon Linux 2, CentOS, RHEL, and Rocky Linux, see the Install or compile the USB/IP kernel module section in this article.
- For SUSE, download and install the USB/IP package from https://software.opensuse.org/package/usbip.
- For Ubuntu/Debian, complete the following steps to compile and install the USB/IP kernel module:
  1. Download the USB/IP kernel module source code.
    
    Go to the Linux kernel repository at https://github.com/torvalds/linux/tree/master/drivers/usb/usbip, select the target Linux kernel version (v4.15 or later) tag, and get the link such as https://github.com/torvalds/linux/tree/v4.15/drivers/usb/usbip.
    
    Go to DownGit and enter the preceding link to create a download link for downloading the USB/IP source code.
  2. Unzip the source file using the following commands:
    unzip ${USBIP_SRC}.zip cd usbip 
  3. Modify the Makefile file as follows:
    # SPDX-License-Identifier: GPL-2.0 ccflags-$(CONFIG_USBIP_DEBUG) := -DDEBUG obj-$(CONFIG_USBIP_CORE) += usbip-core.o usbip-core-y := usbip_common.o usbip_event.o obj-$(CONFIG_USBIP_VHCI_HCD) += vhci-hcd.o vhci-hcd-y := vhci_sysfs.o vhci_tx.o vhci_rx.o vhci_hcd.o #obj-$(CONFIG_USBIP_HOST) += usbip-host.o #usbip-host-y := stub_dev.o stub_main.o stub_rx.o stub_tx.o #obj-$(CONFIG_USBIP_VUDC) += usbip-vudc.o #usbip-vudc-y := vudc_dev.o vudc_sysfs.o vudc_tx.o vudc_rx.o vudc_transfer.o vudc_main.o 
  4. Compile the source code:
    apt-get install linux-headers-`uname -r` make -C /lib/modules/`uname -r`/build M=$PWD 
  5. Install the USB/IP kernel module:
    cp usbip-core.ko vhci-hcd.ko /opt/Citrix/VDA/lib64/ 
  6. Restart the ctxusbsd service to load the USB/IP kernel module:
    systemctl restart ctxusbsd

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 make sure that the device isn’t denied access by this setting:

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

A USB device is redirected successfully, but I can’t 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’s 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:

For 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. It might not be the case for devices that aren’t in the supported device list.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

USB device redirection

August 9, 2024

Contributed by:

B C

August 9, 2024

Contributed by:

B C

USB device redirection

How USB device redirection works

Supported USB devices

Configure USB device redirection

(For CentOS, RHEL, and Rocky Linux only) Install or compile the USB/IP kernel module

Set USB device redirection policies

Enable USB device redirection

Set USB device redirection rules

Troubleshoot USB device redirection issues

Unable to unmount the redirected USB disk

File lost when you stop redirecting a USB disk

No devices in the toolbar of Citrix Workspace app

Redirection failure when USB devices are visible in the toolbar of Citrix Workspace app, but are labeled “policy restricted”

A USB device is redirected successfully, but I can’t use it in my session

In this article