USB Redirection
Overview
USB devices are shared between the Citrix Workspace app and the Citrix VDA for macOS desktop. When a USB device is redirected to the desktop, you can use the USB device as if it were locally connected.
Note:
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 two main areas of functionality:
- Citrix USB session module (CtxHDX)
- Citrix USB service module (CtxUSB)
Citrix USB session module
The Citrix USB session module acts as a communication bridge between the USB service module and Citrix Workspace app. All USB data transfers between the Citrix VDA for macOS and Citrix Workspace app are encapsulated by the Citrix ICA USB protocol.
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 Citrix VDA for macOS, one or more device nodes are created in the system and attached in macOS USB host controller. Sometimes, however, the redirected device isn’t usable for an active Citrix VDA for macOS 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 Citrix VDA for macOS session. To make sure of USB device connectivity, install the drivers and configure the system properly.
The Citrix VDA for macOS supports a list of USB devices that are successfully redirected from the client.
Supported USB devices
Note:
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 class has been verified to support this version of the Citrix VDA for macOS. Other devices might be freely used, with unexpected results:
- USB mass storage device
- Supported File System format: Mac OS Extended, ExFAT, MS-DOS(FAT) and NTFS, whereas NTFS is read-only on a Mac.
- HID Device
- The following device has tested with Citrix VDA for macOS：Wacom Pen Tablet CTL-472
-
Audio / Video Device
- Webcam Device and Audio Device currently is not supported in Citrix VDA for macOS USB redirection. We suggest using the optimized Webcam Redirection and Audio Redirection Features for these devices.
Configuration
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 Citrix VDA for macOS, 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.
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 Citrix VDA for macOS.
In the Client USB device redirection rules dialog:
-
Click New to add a redirection rule, or click 1. Edit to review an existing rule.
After creating (or editing) a rule, click OK.
For more information on configuring USB 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 Citrix VDA for macOS.
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 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, refer the Set USB device redirection policies to set it correctly.
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 Citrix VDA for macOS 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 Mass Storage device is redirected successfully, but I can’t write data to it in my session
Check if the file system is NTFS. NTFS is read-only in macOS.
I can’t redirect iPhone and iPad devices into the Citrix VDA for macOS session
Currently, we only support redirecting mass storage Devices and HID Devices by Citrix VDA for macOS USB feature.
USB Device Session Isolation
Citrix VDA for macOS only supports a single ICA session that is used at the same time. However, with Apple’s built-in VNC client, we can launch two or more sessions with different user accounts.
For instance, one ICA session for user A and two VNC sessions for user B and user C. USB redirection doesn’t support USB device session isolation currently.