USB 设备重定向
USB 设备在 Citrix Workspace™ app 和 Linux VDA 桌面之间共享。当 USB 设备重定向到桌面时，您可以像使用本地连接的 USB 设备一样使用它。
提示：
我们建议在网络延迟低于 100 毫秒时使用 USB 设备重定向。当网络延迟高于 200 毫秒时，请勿使用 USB 设备重定向。
-
USB 设备重定向包括三个主要功能领域：
- 开源 USB/IP 项目
- Citrix USB 会话模块
- Citrix USB 服务模块
开源 USB/IP 项目：
USB/IP 项目由一个 Linux 内核驱动程序和一些用户模式库组成，这些库允许您与内核驱动程序通信以获取所有 USB 数据。
Linux VDA 基于开源 USB/IP 项目实现 USB 设备重定向，并重用 USB/IP 的内核驱动程序和用户模式库。但是，Linux VDA 和 Citrix Workspace app 之间的所有 USB 数据传输都由 Citrix ICA USB 协议封装。
Citrix USB 会话模块：
Citrix USB 会话模块充当 USB/IP 内核模块与 Citrix Workspace app 之间的通信桥梁。
Citrix USB 服务模块：
Citrix USB 服务模块管理 USB 设备上的所有操作，例如，连接或分离 USB 设备。
USB 设备重定向的工作原理
通常，如果 USB 设备成功重定向到 Linux VDA，则会在系统 /dev 路径中创建一个或多个设备节点。但是，有时重定向的设备无法用于活动的 Linux VDA 会话。USB 设备依赖驱动程序才能正常运行，并且某些设备需要特殊驱动程序。如果未提供驱动程序，则重定向的 USB 设备将无法访问活动的 Linux VDA 会话。为确保 USB 设备连接，请安装驱动程序并正确配置系统。
Linux VDA 支持从客户端成功重定向的 USB 设备列表。
支持的 USB 设备
提示：
我们已添加对 USB 3.0 端口的支持。您可以将 USB 3.0 设备插入客户端设备上的 USB 3.0 端口。
以下设备已验证支持此版本的 Linux VDA。其他设备可以自由使用，但可能会出现意外结果：
| USB 大容量存储设备 | VID:PID | 文件系统 |
|---|---|---|
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 |
注意：
要在 RHEL、Rocky Linux 和 SUSE 上使用 NTFS，请首先在这些分发版上启用 NTFS 支持。
| USB 3D 鼠标 | VID:PID |
|---|---|
3DConnexion SpaceMouse Pro |
046d: c62b |
| USB 扫描仪 | VID:PID |
Epson Perfection V330 photo |
04B8: 0142 |
| Yubico USB | VID:PID |
Yubico YubiKey OTP+FIDO+CCID -Keyboard, HID |
1050:0407 |
| 网络摄像头 USB | VID:PID |
Logitech composite USB device – WebCam, Audio |
0460:0825 |
配置 USB 设备重定向
（仅适用于 RHEL 和 Rocky Linux）安装或编译 USB/IP 内核模块
Linux VDA 使用 USB/IP 作为 USB 设备重定向的虚拟主机控制器。由于在大多数情况下，USB/IP 内核模块随 Linux 内核版本 3.17 及更高版本发布，因此默认情况下您无需构建内核模块。但是，USB/IP 内核模块不适用于 RHEL 和 Rocky Linux。要在这些 Linux 分发版上使用 USB 设备重定向，您必须安装或编译 USB/IP 内核模块。请根据您的 Linux 分发版从 https://pkgs.org/download/kmod-usbip 下载并安装 USB/IP。
设置 USB 设备重定向策略
Citrix 策略控制 USB 设备重定向是启用还是禁用。还可以使用 Delivery Controller™ 策略指定设备类型。为 Linux VDA 配置 USB 设备重定向时，请配置以下策略：
- 客户端 USB 设备重定向策略
- 客户端 USB 设备重定向规则
启用 USB 设备重定向
在 Citrix Studio 中，启用（或禁用）来自客户端的 USB 设备重定向（仅适用于工作站主机）。
在 Edit Setting（编辑设置）对话框中：
- 选择 Allowed（允许）。
- 单击 OK（确定）。
设置 USB 设备重定向规则
启用 USB 重定向策略后，使用 Citrix Studio 设置重定向规则，指定在 Linux VDA 上允许（或拒绝）哪些设备。
在 Client USB device redirection rules（客户端 USB 设备重定向规则）对话框中：
- 单击 New（新建）以添加重定向规则，或单击 Edit（编辑）以查看现有规则。
- 创建（或编辑）规则后，单击 OK（确定）。
注意：
配置 USB 设备重定向时，请确保将 Client USB device redirection（客户端 USB 设备重定向）选项设置为 Allowed（允许），并将 Client USB device redirection rules（客户端 USB 设备重定向规则）配置为 Allow:#all ok。未能同时配置这两个设置可能导致在会话中单击时外部鼠标消失。
支持 Ubuntu on Azure 上的 USB 重定向
默认情况下，Ubuntu on Azure 可能不包含某些 USB 内核驱动程序。您可以按照以下说明为通用设备和特定设备启用 USB 重定向。
为通用设备启用 USB 重定向
对于通用 USB 设备，例如标准 USB 存储设备、YubiKey USB HID 设备和 ASIX 网卡，您只需执行以下配置脚本：
sudo /opt/Citrix/VDA/sbin/usbazure/ctxusbcfg.sh
运行脚本后，重新启动 Citrix USB 服务以激活支持：
sudo service ctxusbsd restart
为特定设备构建 USB 内核驱动程序模块
对于开箱即用不支持的设备，您可以使用以下通用工作流程来构建和安装必要的内核驱动程序模块。以下示例使用 Kingston DataTraveler 2.0 Stick (VID=0930, PID=6544) 进行说明。
先决条件：
-
已安装 Linux VDA 软件包的 VDA 计算机。
-
运行通用 Linux 内核的 Linux 物理机。
在 Linux 物理机上识别所需的内核驱动程序
步骤 1 - 连接设备
将 USB 设备连接到运行通用 Linux 内核的物理机。
步骤 2 - 准备 USB 内核驱动程序识别脚本
- 将 `/opt/Citrix/VDA/sbin/usbazure/ctxusbkodriver.sh` 复制到物理机并使其可执行。
步骤 3 - 获取设备 VID 和 PID
使用 lsusb 识别连接的 USB 设备。
lsusb
Example output:
Bus 001 Device 040: ID 0930:6544 Toshiba Corp. TransMemory-Mini / Kingston DataTraveler 2.0 Stick
<!--NeedCopy-->
- #### 步骤 4 - 识别所需的内核驱动程序
- 使用设备的 `VID:PID` 运行帮助程序脚本：
./ctxusbkodriver.sh 0930:6544
Example output:
All USB Kernel drivers for 0930:6544:
usb-storage
<!--NeedCopy-->
在 VDA 计算机上构建并安装内核驱动程序
步骤 1 - 配置构建环境
运行配置脚本以设置构建环境并将必要的内核源代码下载到 /root/.ctxusb：
sudo /opt/Citrix/VDA/sbin/usbazure/ctxusbcfg.sh
步骤 2 - 确定内核构建配置
使用配置脚本检索相应的内核模块构建选项：
sudo /opt/Citrix/VDA/sbin/usbazure/ctxusbkoconfig.sh /root/.ctxusb/linux usb-storage
Example output:
Config option: CONFIG_USB_STORAGE
Folder: /root/.ctxusb/linux/drivers/usb/storage
<!--NeedCopy-->
步骤 3 - 检查并记录内核配置选项
cd /root/.ctxusb/linux
make menuconfig
<!--NeedCopy-->
- 使用搜索功能（按 /）查找选项（例如，
CONFIG_USB_STORAGE）。 - 记录相关设置（例如，
CONFIG_USB_SUPPORT=y、CONFIG_USB_STORAGE=m）。 - 退出而不保存更改。
步骤 4 - 构建并安装内核驱动程序
编译并安装内核模块：
sudo /opt/Citrix/VDA/sbin/usbazure/ctxusbkobuild.sh /root/.ctxusb/linux/drivers/usb/storage "CONFIG_USB_SUPPORT=y CONFIG_USB_STORAGE=m"
步骤 5 - 验证内核驱动程序
modinfo usb-storage
成功完成后，已为指定的 USB 设备构建并安装了内核驱动程序。
解决 USB 设备重定向问题
使用本节中的信息解决在使用 Linux VDA 时可能遇到的各种问题。
无法卸载重定向的 USB 磁盘
Linux VDA 在管理权限下管理从 Citrix Workspace 应用程序重定向的所有 USB 磁盘，以确保只有所有者才能访问重定向的设备。因此，您只能在管理权限下卸载设备。
停止重定向 USB 磁盘时文件丢失
如果您使用 Citrix Workspace 应用程序的工具栏立即停止重定向 USB 磁盘，则您在磁盘上修改或创建的文件可能会丢失。出现此问题的原因是，当您向文件系统写入数据时，系统会将内存缓存装载到文件系统中。数据不会写入磁盘本身。如果您使用 Citrix Workspace 应用程序的工具栏停止重定向，则没有剩余时间将数据刷新到磁盘，从而导致数据丢失。
要解决此问题，请在停止 USB 重定向之前，在终端中使用 sync 命令将数据刷新到磁盘。
Citrix Workspace 应用程序的工具栏中没有设备
有时，您可能无法在 Citrix Workspace 应用程序的工具栏中看到列出的设备，这表示没有进行 USB 重定向。
如果遇到此问题，请验证以下各项：
- 策略已配置为允许 USB 设备重定向。
- Citrix USB 服务模块正在运行。
如果策略设置不正确，请参考本文中的设置 USB 设备重定向策略部分进行更正。
如果 Citrix USB 服务模块未运行，请完成以下步骤：
-
使用以下命令检查您的 Linux 发行版上是否提供了 USB/IP 内核模块：
modinfo usbip-core <!--NeedCopy--> -
如果输出显示如下，请根据您的 Linux 发行版安装或编译 USB/IP 内核模块：
modinfo: ERROR: Module usbip-core not found. <!--NeedCopy-->- 对于 RHEL 和 Rocky Linux，请参阅本文中的仅适用于 RHEL 和 Rocky Linux：安装或编译 USB/IP 内核模块部分。
- 对于 SUSE，请从 https://software.opensuse.org/package/usbip 下载并安装 USB/IP 软件包。
-
对于 Ubuntu/Debian，请完成以下步骤以编译并安装 USB/IP 内核模块：
-
下载 USB/IP 内核模块源代码。
转到 Linux 内核存储库 https://github.com/torvalds/linux/tree/master/drivers/usb/usbip，选择目标 Linux 内核版本（v4.15 或更高版本）标记，并获取链接，例如 https://github.com/torvalds/linux/tree/v4.15/drivers/usb/usbip。
转到 DownGit 并输入上述链接以创建下载 USB/IP 源代码的下载链接。
-
使用以下命令解压缩源文件：
unzip ${USBIP_SRC}.zip cd usbip <!--NeedCopy--> -
按如下方式修改 Makefile 文件：
# 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--> -
编译源代码：
apt-get install linux-headers-`uname -r` make -C /lib/modules/`uname -r`/build M=$PWD <!--NeedCopy--> -
安装 USB/IP 内核模块：
cp usbip-core.ko vhci-hcd.ko /opt/Citrix/VDA/lib64/ <!--NeedCopy--> -
重新启动 ctxusbsd 服务以加载 USB/IP 内核模块：
systemctl restart ctxusbsd <!--NeedCopy-->
-
当 USB 设备在 Citrix Workspace 应用程序的工具栏中可见但被标记为“策略受限”时重定向失败
当出现此问题时，请执行以下操作：
- 配置 Linux VDA 策略以启用重定向。
-
检查 Citrix Workspace 应用程序的注册表中是否配置了任何其他策略限制。检查注册表路径中的 DeviceRules，以确保此设置未拒绝设备访问：
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\GenericUSB
USB 设备已成功重定向，但我无法在会话中使用它
通常，只有支持的 USB 设备才能重定向。其他设备也可能重定向到活动的 Linux VDA 会话。对于每个重定向的设备，都会在系统 /dev 路径中创建一个由用户拥有的节点。但是，驱动程序和配置决定了用户是否可以成功使用该设备。如果您发现设备已拥有（已插入）但无法访问，请将该设备添加到不受限制的策略中。
注意：
对于 USB 驱动器，Linux VDA 会配置并装载磁盘。用户（且只有安装它的所有者）无需任何额外配置即可访问磁盘。对于不在支持设备列表中的设备，情况可能并非如此。