USB

USB support enables users to interact with a wide range of USB devices when connected to a virtual desktop. Users can plug USB devices into their computers and the devices are redirected to their virtual desktop after enabling auto-redirection. You can enable auto-redirection manually through configuration file settings. Auto-redirection of USB devices is disabled by default. USB devices available for remoting include the following:

• Flash drives
• Smartphones
• PDAs
• Printers
• Scanners
• MP3 players
• Security devices
• Tablets

USB redirection requires either Citrix Virtual Apps and Desktops 7.6 or later.

The following isochronous features in USB devices are supported in typical low latency or high speed LAN environments:

• Webcams
• Microphones
• Speakers
• Headsets

But usually the standard audio or webcam redirection are more suitable.

The following types of devices are supported directly in a virtual apps and desktops session, and so do not use USB support:

• Keyboards
• Mice
• Smart cards
• Headsets
• Webcams

Note:

Specialist USB devices (for example, Bloomberg keyboards and 3D mice) can be configured to use USB support. For information on configuring policy rules for other specialist USB devices, see CTX119722.

By default, certain types of USB devices aren’t supported for remoting through Citrix Virtual Apps and Desktops or Citrix DaaS. For example, a user might have a NIC attached to the system board by internal USB. Remoting this NIC isn’t appropriate. By default, the following types of USB device aren’t supported for use in the virtual apps and desktops:

• Bluetooth dongles
• Integrated NICs
• USB hubs

To update the default list of USB devices available for remoting, edit the usb.conf file in the $ICAROOT/ folder. For more information, see the Update the list of USB devices available for remoting section.

To allow the remoting of USB devices to virtual desktops, enable the USB policy rule. For more information, see the Citrix Virtual Apps and Desktops documentation.

How USB support works

When a user plugs a USB device, it’s checked against the USB policy. And, if allowed, redirected to the virtual desktop. If the default policy denies the device, it’s available only to the local desktop.

Consider a user plugging in a USB device in desktops accessed through desktop appliance mode. In this case, that device is auto-redirected to the virtual desktop after enabling auto-redirection manually through configuration file settings. Auto-redirection of USB devices is disabled by default. To configure the auto-redirection of USB devices, do the following:

1. Navigate to the $Home/.ICAClient/wfclient.ini configuration file.

2. Add the following entry:

   DesktopApplianceMode=True

3. Navigate to /opt/Citrix/ICAClient/usb.conf configuration file.

4. Set any of the following device rules:

   • CONNECT – Set the “CONNECT” keyword to enable auto redirect of a device when a session starts.
   • ALLOW – Set the “ALLOW” keyword to allow auto-redirect of a device only after a session starts. However, if you set the CONNECT or ALLOW keyword, it auto-redirects the device when unplugged and plugged in during a session.

   Sample device rule: CONNECT: vid=046D pid=0002 # Allow a specific device by vid/pid ALLOW: vid=046D pid=0102 # Allow a specific device by vid/pid

The session window must have focus when the user plugs in the USB device for redirection to occur, unless desktop appliance mode is in use.

Note:

If you configure the USB policy to a device with the “CONNECT” keyword and set the DesktopApplianceMode to True, the USB device redirects to the VDA session automatically. When the DesktopApplianceMode mode is set to false, the USB device doesn’t redirects to the VDA session automatically.

Known limitation:

• For USB redirection, the policies defined in the usb.conf file might not work and the USB devices might not be redirected into session. This issue occurs if you have more than 2000 characters present in the usb.conf file. As a workaround, you can remove the existing comments to the policies to reduce the number of characters in the usb.conf file.
• Generic USB redirection is supported only when the virtual desktop window is focused.

Mass storage devices

Consider that a user disconnects from a virtual desktop when a USB mass storage device (MSD) is still plugged in to the local desktop. In this case, that device isn’t redirected to the virtual desktop when the user reconnects. To verify that the MSD is redirected to the virtual desktop, the user must remove and reinsert the device after reconnecting.

Note:

If you insert an MSD into a Linux workstation configured to deny remote support for USB MSDs, Citrix Workspace app doesn’t accept the device. And a separate Linux file browser might open. So, Citrix recommends that you pre-configure user devices with the Browse removable media when inserted setting cleared by default. On Debian-based devices, do this using the Debian menu bar by selecting Desktop > Preferences > Removable Drives and Media. And on the Storage tab, under Removable Storage, clear the Browse removable media when inserted check box.

For the Client USB device redirection, note the following points.

Notes:

Consider that the Client USB device redirection server policy is turned on. In this case, the MSDs are directed as USB devices even if client drive mapping is turned on.

USB classes

The default USB policy rules allow the following classes of USB device:

• Audio (Class 01)

  Includes microphones, speakers, headsets, and MIDI controllers.

• Physical Interface (Class 05)

  These devices are similar to HIDs, but generally provide real-time input or feedback. Also, include force feedback joysticks, motion platforms, and force feedback exoskeletons.

• Still Imaging (Class 06)

  Includes digital cameras and scanners. Digital cameras support the still imaging class that uses the following to transfer images to a computer or other peripheral:

  • Picture Transfer Protocol (PTP) or,
  • Media Transfer Protocol (MTP)

  Cameras might also appear as mass storage devices. And it might be possible to configure a camera to use either class, through the setup menus provided by the camera itself.

  If a camera appears as an MSD, client drive mapping is used, and USB support isn’t required.

• Printers (Class 07)

  In general most printers are included in this class, although some use vendor-specific protocols (class ff). Multi-function printers might have an internal hub or be composite devices. In both cases, the printing element generally uses the Printers class and the scanning or fax element uses another class; for example, Still Imaging.

  Printers normally work appropriately without USB support.

• Mass Storage (Class 08)

  The most common MSDs are USB flash drives. Others include USB-attached hard drives, CD/DVD drives, and SD/MMC card readers. There’s a wide variety of devices having internal storage which also presents a mass storage interface. These devices include media players, digital cameras, and mobile phones. Known subclasses include:

• 01 Limited flash devices
• 02 Typically CD/DVD devices (ATAPI/MMC-2)
• 03 Typically tape devices (QIC-157)
• 04 Typically floppy disk drives (UFI)
• 05 Typically floppy disk drives (SFF-8070i)

• 06 Most MSDs use this variant of SCSI

  MSDs can often be accessed through client drive mapping, and so USB support isn’t required.

  Important: Some viruses are known to propagate actively using all types of MSDs. Consider carefully whether there’s a business requirement to allow the use of MSDs, either through client drive mapping, or USB support. To reduce this risk, the server might be configured to prevent files being run-through client drive mapping.

  Note:

  If a user requires to redirect a USB 3.0 driver to the Linux VDA using generic USB redirection, plug-in the USB flash drive into a USB 3.0 slot.

• Content Security (Class 0d)

  Content security devices enforce content protection, typically for licensing or digital rights management. This class includes dongles.

• Personal Healthcare (Class 0f)

  These devices include personal healthcare devices such as the following:

  • Blood pressure sensors
  • Heart rate monitors
  • Pedometers
  • Pill monitors
  • Spirometers

• Application and Vendor Specific (Classes fe and ff)

  Many devices use vendor-specific protocols or protocols not standardized by the USB consortium, and these devices usually appear as vendor-specific (class ff).

USB device classes

The default USB policy rules deny the following classes of USB devices:

• Communications and CDC Control (Classes 02 and 0a)

  Includes modems, ISDN adapters, network adapters, and some telephones and fax machines.

  The default USB policy does not allow these devices, because one of them might be providing the connection to the virtual desktop itself.

• Human Interface Devices (Class 03)

  Includes a wide variety of both input and output devices. Typical Human Interface Devices (HIDs) are the following:

  • Keyboards
  • Mice
  • Pointing devices
  • graphic tablets
  • Sensors
  • Game controllers
  • Buttons
  • Control functions

  Subclass 01 is known as the boot interface class and is used for keyboards and mice.

  The default USB policy does not allow USB keyboards (class 03, subclass 01, protocol 1), or USB mice (class 03, subclass 01, protocol 2). This setting is because most keyboards and mice are handled appropriately without USB support. And it’s normally necessary to use these devices locally as well remotely when connecting to a virtual desktop.

• USB Hubs (Class 09)

  USB Hubs allow extra devices to be connected to the local computer. It isn’t necessary to access these devices remotely.

• Smart card (Class 0b)

  Smart card readers include contactless and contact smart card readers, and also USB tokens with an embedded smart card equivalent chip.

  Smart card readers are accessed using smart card remoting and do not require USB support.

• Video (Class 0e)

  The video class covers devices that are used to manipulate video or video-related material, such as:

  • Webcams
  • Digital camcorders
  • Analog video converters
  • Some television tuners
  • Some digital cameras that support video streaming

  By default, optimum webcam performance is provided by HDX RealTime Webcam Video Compression.

• Wireless Controllers (Class e0)

  Includes a wide variety of wireless controllers, such as ultrawide band controllers and Bluetooth.

  Some of these devices might provide critical network access, or connect critical peripherals such as Bluetooth keyboards or mice.

  The default USB policy does not allow these devices. However, there might be particular devices it’s appropriate to provide access to using USB support.

List of USB devices

You can update the range of USB devices available for remoting to desktops by editing the list of default rules in the usb.conf file on the user device in $ICAROOT/.

You can update the list by adding new policy rules to allow or deny USB devices not included in the default range. Rules created by an administrator in this way control which devices are offered to the server. The rules on the server control which of these devices are to be accepted.

The default policy configuration for disallowed devices is:

DENY: class=09 # Hub devices

DENY: class=03 subclass=01 # HID Boot device (keyboards and mice)

DENY: class=0b # Smartcard

DENY: class=e0 # Wireless Controllers

DENY: class=02 # Communications and CDC Control

DENY: class=03 # UVC (webcam)

DENY: class=0a # CDC Data

ALLOW: # Ultimate fallback: allow everything else

USB policy rules

When creating policy rules, be aware of the following:

• The rules are case-insensitive.
• The rules might have an optional comment at the end, introduced by “#.” A delimiter isn’t required and the comment is ignored for matching purposes.
• Blank and pure comment lines are ignored.
• Whitespace used as a separator is ignored, but can’t appear in the middle of a number or identifier. For example, Deny: Class=08 SubClass=05 is a valid rule; Deny: Class=0 8 Sub Class=05 isn’t.
• Tags must use the matching operator “=.” For example, VID=1230.

Example

The following example shows a section of the usb.conf file on the user device. For these rules to be implemented, the same set of rules must exist on the server.

ALLOW: VID=1230 PID=0007 \# ANOther Industries, ANOther Flash Drive

DENY: Class=08 SubClass=05 \# Mass Storage Devices

DENY: Class=0D \# All Security Devices

Start-up modes

Using desktop appliance mode, you can change how a virtual desktop handles previously attached USB devices. In the WfClient section of the $ICAROOT/config/module.ini file on each user device, set DesktopApplianceMode=Boolean as follows.

Note:

Set the “CONNECT” keyword to enable the auto redirect of a device when a session starts. Also, set the “ALLOW” keyword to allow auto-redirect of a device only after a session starts. However, if you set the CONNECT or ALLOW keyword, it auto-redirects the device when unplugged and plugged in during a session.

Configure auto-redirection of USB devices

Earlier, during a session, when a device was unplugged and plugged it automatically redirected. As a result, the device was auto-connected to the VDA. With the Citrix Workspace app 2207 release, you are required to enable auto-redirection manually through configuration file settings. Auto-redirection of USB devices is disabled by default.

To configure the auto-redirection of USB devices (regular and composite devices), do the following:

1. Navigate to the $Home/.ICAClient/wfclient.ini configuration file.

2. Add the following entry:

   DesktopApplianceMode=True

3. Navigate to /opt/Citrix/ICAClient/usb.conf configuration file.

4. Set any of the following device rules:

   • CONNECT – Set the “CONNECT” keyword to enable auto redirect of a device when a session starts.
   • ALLOW – Set the “ALLOW” keyword to allow auto-redirect of a device only after a session starts.

   However, if the CONNECT or ALLOW keyword is set, the device is auto-redirected when it unplugged and plugged in during a session.

Sample device rule:

CONNECT: vid=046D pid=0002 # Allow a specific device by vid/pid`

ALLOW: vid=046D pid=0102 # Allow a specific device by vid/pid`

Composite USB device redirection

Starting with the 2207 version, Citrix Workspace app allows splitting of composite USB devices. A composite USB device can perform more than one function. These functions are accomplished by exposing each of those functions using different interfaces. Examples of composite USB devices include HID devices that consist of audio and video input and output.

Currently composite USB device redirection is available in desktop session only. The split devices appear in the Desktop Viewer.

Earlier when a device was unplugged and plugged in during a session, the device was auto-redirected. As a result, the device was auto connected to the VDA. With this release, you are required to enable auto-redirection manually through configuration file settings. Auto-redirection of composite USB devices is disabled by default.

USB 2.1 and later supports the notion of USB composite devices where multiple child devices share a single connection with the same USB bus. Such devices employ a single configuration space and shared bus connection where a unique interface number 00-ff is used to identify each child device. This setting is not the same as a USB hub which provides a new USB bus origin for other independently addressed USB devices for connection.

Composite devices found on the client endpoint can be forwarded to the virtual host as either:

• a single composite USB device, or
• a set of independent child devices (split devices)

When a composite USB device is forwarded, the entire device becomes unavailable to the endpoint. This action blocks the local usage of the device for all applications on the endpoint, including the Citrix Workspace client needed for an optimized HDX remote experience.

Consider a USB headset device with both audio device and HID button for mute and volume control. If the entire device is forwarded using a generic USB channel, the device becomes unavailable for redirection over the optimized HDX audio channel. However, you can achieve the best experience when sending the audio through the optimized HDX audio channel unlike the audio sent using host-side audio drivers through generic USB remoting. It happens because of the noisy nature of the USB audio protocols.

You also notice issues when the system keyboard or pointing device are part of a composite device with other integrated features that are required for the remote session support. When a complete composite device is forwarded, the system keyboard or mouse becomes inoperable at the endpoint, except within the remote desktop session or application.

To resolve these issues, Citrix recommends that you split the composite device and forward only the child interfaces that use a generic USB channel. This setting ensures that the other child devices are available for use by apps on the client endpoint. This client endpoint includes the Citrix Workspace app that provides optimized HDX experiences, while forwarding only the required devices and making them available to the remote session.

Device Rules:

As with regular USB devices, the composite devices for forwarding are selected based on the device rules set in the Citrix Workspace app configuration. Citrix Workspace app uses these rules to decide which USB devices to allow or prevent from forwarding to the remote session.

Each rule consists of the following that match the actual devices at the endpoints USB subsystem:

• an action keyword such as Allow, Connect, or Deny
• a colon (:)
• and zero or more filter parameters

The preceding filter parameters correspond to the USB device descriptor metadata used by every USB device to identify itself.

Device rules are clear text with each rule on a single line and an optional comment after a # character. Rules are matched top down (descending priority order). The first rule that matches the device or child interface is applied. Subsequent rules that select the same device or interface are ignored.

To modify the device rules, do the following:

1. Navigate to the /opt/Citrix/ICAClient/usb.conf file.
2. Update the device rules as required.

Sample device rules:

ALLOW: vid=046D pid=0102 # Allow a specific device by vid/pid

ALLOW: vid=0505 class=03 subclass=01 # Allow any pid for vendor 0505 w/subclass=01

DENY: vid=0850 pid=040C # deny a specific device (including all child devices)

DENY: class=03 subclass=01 prot=01 # deny any device that matches all filters

CONNECT: vid=0911 pid=0C1C # Allow and auto-connect a specific device

ALLOW: vid=0286 pid=0101 split=01 # Split this device and allow all interfaces

ALLOW: vid=1050 pid=0407 split=01 intf=00,01 # Split and allow only 2 interfaces

CONNECT: vid=1050 pid=0407 split=01 intf=02 # Split and auto-connect interface 2

DENY: vid=1050 pid=0407 split=1 intf=03 # Prevent interface 03 from being remoted

You can use any of the following filter parameters to apply rules to the encountered devices:

The first six parameters select the USB devices for which the rule must be applied. If any parameter is not specified, the rule matches a device with ANY value for that parameter.

The USB Implementors Forum maintains a list of defined class, subclass, and protocol values in Defined Class Codes. USB-IF also maintains a list of registered vendor IDs. You can check the vendor, product, release, and interface IDs of a specific device using a free tool like lsusb:

 <username@username>-ThinkPad-T470:/var/log$ lsusb

Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Bus 002 Device 002: ID 0bda:0316 Realtek Semiconductor Corp. USB3.0-CRW

Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

Bus 001 Device 005: ID 138a:0097 Validity Sensors, Inc.

Bus 001 Device 004: ID 5986:111c Acer, Inc Integrated Camera

Bus 001 Device 003: ID 8087:0a2b Intel Corp.

Bus 001 Device 006: ID 17ef:609b Lenovo Lenovo USB Receiver

Bus 001 Device 045: ID 1188:a001 Bloomberg L.P. Lenovo USB Receiver

Bus 001 Device 044: ID 1188:a301 Bloomberg L.P.

Bus 001 Device 043: ID 1188:a901 Bloomberg L.P. Keyboard Hub

Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

<!--NeedCopy-->

    | <username@username>-ThinkPad-T470:/var/log$ lsusb -t

    /:  Bus 04.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 10000M

    /:  Bus 03.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M

    /:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/6p, 5000M

    |__ Port 3: Dev 2, If 0, Class=Mass Storage, Driver=usb-storage, 5000M

    /:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/12p, 480M

    |__ Port 1: Dev 43, If 0, Class=Hub, Driver=hub/4p, 480M

        |__ Port 1: Dev 46, If 0, Class=Human Interface Device, Driver=usbhid, 12M

        |__ Port 4: Dev 45, If 0, Class=Human Interface Device, Driver=usbhid, 12M

        |__ Port 4: Dev 45, If 1, Class=Human Interface Device, Driver=usbhid, 12M

        |__ Port 2: Dev 44, If 3, Class=Audio, Driver=snd-usb-audio, 12M

        |__ Port 2: Dev 44, If 1, Class=Vendor Specific Class, Driver=, 12M

        |__ Port 2: Dev 44, If 4, Class=Audio, Driver=snd-usb-audio, 12M

        |__ Port 2: Dev 44, If 2, Class=Audio, Driver=snd-usb-audio, 12M

        |__ Port 2: Dev 44, If 0, Class=Human Interface Device, Driver=usbhid, 12M

    |__ Port 4: Dev 6, If 1, Class=Human Interface Device, Driver=usbhid, 12M

    |__ Port 4: Dev 6, If 2, Class=Human Interface Device, Driver=usbhid, 12M

    |__ Port 4: Dev 6, If 0, Class=Human Interface Device, Driver=usbhid, 12M

    |__ Port 7: Dev 3, If 0, Class=Wireless, Driver=btusb, 12M

    |__ Port 7: Dev 3, If 1, Class=Wireless, Driver=btusb, 12M

    |__ Port 8: Dev 4, If 1, Class=Video, Driver=uvcvideo, 480M

    |__ Port 8: Dev 4, If 0, Class=Video, Driver=uvcvideo, 480M

    |__ Port 9: Dev 5, If 0, Class=Vendor Specific Class, Driver=, 12M |

<!--NeedCopy-->

When present, the last two parameters apply only to USB composite devices. The split parameter determines if a composite device must be forwarded as a split device or as a single composite device.

Split=1 indicates that the selected child interfaces of a composite device must be forwarded as split devices. Split=0 indicates that the composite device must not be split.

Note:

If the split parameter is omitted, Split=0 is assumed.

The intf parameter selects the specific child interfaces of the composite device to which the action must be applied. If omitted, the action applies to all interfaces of the composite device.

Consider a composite USB device (For example, the Bloomberg 4 keyboard) with six interfaces:

• Interface 0 - Bloomberg 4 Keyboard HID
• Interface 1 - Bloomberg 4 Keyboard HID
• Interface 2 - Bloomberg 4 HID
• Interface 3 - Bloomberg 4 Keyboard Audio Channel
• Interface 4 - Bloomberg 4 Keyboard Audio Channel
• Interface 5 - Bloomberg 4 Keyboard Audio Channel
• The suggested rules for this type of device are:

CONNECT: vid=1188 pid=9545 split=01 intf=00 # Bloomberg 4 Keyboard HID

CONNECT: vid=1188 pid=9545 split=01 intf=01 # Bloomberg 4 Keyboard HID

CONNECT: vid=1188 pid=9545 split=01 intf=02 # Bloomberg 4 HID

DENY: vid=1188 pid=9545 split=01 intf=03 # Bloomberg 4 Keyboard Audio Channel

DENY: vid=1188 pid=9545 split=01 intf=04 # Bloomberg 4 Keyboard Audio Channel

DENY: vid=1188 pid=9545 split=01 intf=05 # Bloomberg 4 Keyboard Audio Channel

Composite USB device redirection with Citrix Viewer

To connect the USB devices from the Devices section, do the following:

1. In a desktop session, navigate to the Desktop Viewer under Devices. The split USB devices appear.

   

2. To connect a device, select the required menu item.

To connect the USB devices from the Preferences section, do the following:

1. Navigate to the Preferences > Devices section. The split USB devices appear.

   

2. Select the check boxes next to the devices, as required.

3. Click OK.

The selected configuration is applied to the device connection.

Note:

Clear the required menu item or check boxes next to the device to disconnect a device.

Enhancement for composite USB auto-redirection

Previously, you had to set DesktopApplianceMode to True in the configuration file to auto-redirect USB devices when a session starts.

With the 2402 release, you are able to manage device connection settings from a UI on the Citrix Workspace app for Linux, without having to depend on configuration files.

The following two options are added on the Devices section in the Preferences screen:

• When a session starts, connect devices automatically. By default, this checkbox isn’t selected.
• When a new device is connected while a session is running, connect devices automatically. By default, this checkbox is selected.

This feature is enabled by default.

To configure the composite USB redirection by using the GUI, do the following:

1. From the Desktop Viewer toolbar of an HDX session, select Preferences. The Citrix Workspace – Preferences dialog box appears.

2. Click Devices. You can see the Devices section.

   

3. Select one or both of the following options as per your requirement:

   • When a session starts, connect devices automatically - When this option is selected, the USB devices are automatically connected to the virtual desktop when a session starts.
   • When a new device is connected while a session is running, connect devices automatically - When this option is selected, the USB devices are automatically connected to the virtual desktop while a session is in-progress.
4. Click OK.

When one or more HDX sessions are configured for auto-redirection, the behaviors are as follows:

• If there’s an HDX session on focus, all USB devices are auto-redirected.
• If there’s no HDX session on focus, USB devices are auto-redirected to the last started HDX session.
• After a USB device is redirected, an end user can stop it using the HDX session’s toolbar or directly close the HDX session. In this case, the USB device is disconnected and connected back to the client machine. The end user can redirect it again anytime.

Composite USB device redirection using DDC policies

Previously, the composite USB device redirection was managed on the client side. There was no option to manage it on VDA.

Starting with the 2405 release, you can manage the composite USB device redirection on VDA using the DDC policies. The rules set on the VDA take preferences over the rules set on the client. Client can interpret the value set on VDA.

With this release, Citrix Workspace app for Linux supports the following policies which helps you to manage the usage of the composite USB device redirection:

• Client USB device redirection
• Client USB device redirection rules
• Client USB device redirection rules (Version 2)
• Allow existing USB devices to be automatically connected
• Allow newly arrived USB devices to be automatically connected

Note:

To configure the preceding polices, users can refer to the documents see Client USB device redirection document.

Desktop Viewer’s updates according to the polices

• If the Client USB device redirection policy is set to Prohibited on DDC, the Devices on the toolbar will be set to insensible and the Devices option on the Citrix Workspace app - Preferences screen won’t be visible.

• Based on the values set for Allow existing USB devices to be automatically connected and Allow newly arrived USB devices to be automatically connected policies, the following checkboxes might be enabled or disabled on the Devices option on the Citrix Workspace app - Preferences screen:

  • When a session starts, connect devices automatically
  • When a new device is connected while a session is running, connect devices automatically