Product documentation
Linux Virtual Delivery Agent
Current Release 2407 2402 LTSR 2311 2308 2305 2303 2301 2212 2210 2209 2207 2206 2204 2203 LTSR 2201 2112 2110 2109 2107 2106 2104 2103 1912 LTSR 7.15
View PDF

USB device redirection

December 12, 2024
Contributed by: 
C 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, 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 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 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 policies:

  • Client USB device redirection
  • 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:

  1. Select Allowed.
  2. 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:

  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.

The client USB device redirection rule setting

Note:

When configuring USB device redirection, ensure that you set the Client USB device redirection option to Allowed and configure Client USB device redirection rules as Allow:#all ok. Failure to configure both settings can result in the external mouse disappearing upon clicking in a session.

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.

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.

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:

  1. Check whether a USB/IP kernel module is available on your Linux distribution using the following command:

    modinfo usbip-core
<!--NeedCopy-->

  2. 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.
<!--NeedCopy-->
    • For 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
<!--NeedCopy-->

      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
<!--NeedCopy-->

      4. Compile the source code:

        apt-get install linux-headers-`uname -r`

make -C /lib/modules/`uname -r`/build M=$PWD
<!--NeedCopy-->

      5. Install the USB/IP kernel module:

        cp usbip-core.ko vhci-hcd.ko /opt/Citrix/VDA/lib64/
<!--NeedCopy-->

      6. Restart the ctxusbsd service to load the USB/IP kernel module:

        systemctl restart ctxusbsd
<!--NeedCopy-->

Redirection failure when USB devices are visible 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 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.

USB device redirection
December 12, 2024
Contributed by: 
C B C
December 12, 2024
Contributed by: 
C B C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.