Linux Virtual Delivery Agent 2103

查看 PDF

配置 USB 重定向

May 5, 2025

投稿者:

C Y

USB 设备在 Citrix Workspace 应用程序与 Linux VDA 桌面之间共享。将 USB 设备重定向到桌面后，用户就可以像使用本地连接的 USB 设备那样使用它。

提示：

当网络延迟低于 100 毫秒时，我们建议使用 USB 重定向。当网络延迟超过 200 毫秒时，请勿使用 USB 重定向。

USB 重定向包含三个主要方面的功能：

开源项目实施 (VHCI)
VHCI 服务
USB 服务

开源 VHCI：

这部分 USB 重定向功能发展了通过 IP 网络的通用 USB 设备共享系统。它由 Linux 内核驱动程序和一些用户模式库组成，这些库使您可以与内核驱动程序通信以获取所有 USB 数据。在 Linux VDA 实现中，Citrix 重用 VHCI 的内核驱动程序。但是，Linux VDA 与 Citrix Workspace 应用程序之间的所有 USB 数据传输都封装在 Citrix ICA 协议软件包中。

VHCI 服务：

VHCI 服务是 Citrix 提供用来与 VHCI 内核模块通信的开源服务。此服务充当 VHCI 与 Citrix USB 服务之间的网关。

USB 服务：

USB 服务相当于管理 USB 设备上的所有虚拟化和数据传输的 Citrix 模块。

USB 重定向的工作方式

通常情况下，如果 USB 设备成功重定向至 Linux VDA，会在系统 /dev 路径中创建一个或多个设备节点。但是，重定向的设备有时不可用于活动的 Linux VDA 会话。 USB 设备依赖于驱动程序才能正常使用，且有些设备需要特殊的驱动程序。如果并未提供驱动程序，活动 Linux VDA 会话无法使用重定向的 USB 设备。为确保 USB 设备的连接性，请安装驱动程序并正确配置系统。

Linux VDA 支持一组成功重定向至客户端和从客户端重定向的 USB 设备。此外，正确装载设备（尤其是 USB 磁盘）后，用户就可以访问磁盘，而无需进行任何其他配置。

支持的 USB 设备

下列设备已确认支持此 Linux VDA 版本。可以随意使用其他设备，但会有意外结果：

注意：

Linux VDA 仅支持 USB 2.0 协议。

USB 大容量存储设备	VID:PID	文件系统
Netac Technology Co., Ltd	0dd8:173c	FAT32
Kingston Datatraveler 101 II	0951:1625	FAT32
Kingston Datatraveler GT101 G2	1567:8902	FAT32
SanDisk SDCZ80 闪存驱动器	0781:5580	FAT32
WD HDD	1058:10B8	FAT32

USB 3D 鼠标	VID:PID
3DConnexion SpaceMouse Pro	046d: c62b

USB 扫描仪	VID:PID
Epson Perfection V330 照片	04B8: 0142

配置 USB 重定向

有一个 Citrix 策略控制是否启用或禁用 USB 设备重定向。此外，还可以使用 Delivery Controller 策略指定设备类型。为 Linux VDA 配置 USB 重定向时，请配置以下策略和规则：

客户端 USB 设备重定向策略
客户端 USB 设备重定向规则

启用 USB 重定向策略

在 Citrix Studio 中，启用（或禁用）与客户端之间的 USB 设备重定向（仅限工作站主机）。

在编辑设置对话框中：

选择允许。
单击确定。

启用 USB 重定向示意图

设置 USB 重定向规则

启用 USB 重定向策略后，使用 Citrix Studio 设置重定向规则，方法是指定允许（或拒绝）在 Linux VDA 上使用哪些设备。

在客户端 USB 设备重定向规则对话框中：

单击新建添加重定向规则，或单击编辑检查现有规则。
创建（或编辑）规则后，单击确定。

客户端 USB 重定向规则设置示意图

构建 VHCI 内核模块

USB 重定向依赖于 VHCI 内核模块（usb-vhci-hcd.ko 和 usb-vhci-iocif.ko）。这些模块包含在 Linux VDA 发行版中（作为 RPM 软件包的一部分）。它们根据正式的 Linux 发行版内核进行编译，请见下表：

支持的 Linux 发行版	内核版本
RHEL 8.3	4.18.0-240.10.1
RHEL 8.2	4.18.0-240.10.1
RHEL 8.1	4.18.0-240.10.1
RHEL 7.9	3.10.0-1160.11.1
RHEL 7.8	3.10.0-1160.11.1
SUSE 12.5	4.12.14-122.57.1
Ubuntu 20.04	5.4.0-58
Ubuntu 18.04	4.15.0-128
Ubuntu 16.04	4.4.0-197
Debian 10	4.19.0-13

重要：

如果您的计算机的内核与为 Linux VDA 构建的驱动程序不兼容，USB 服务可能无法启动。在这种情况下，仅当您构建自己的 VHCI 内核模块时，才能使用 USB 重定向功能。

确认您的内核与 Citrix 构建的模块是否一致

在命令行上，运行以下命令来确认内核是否一致：

  insmod /opt/Citrix/VDA/lib64/usb-vhci-hcd.ko
<!--NeedCopy-->

如果命令运行成功，则内核模块已成功加载，且版本与 Citrix 安装的模块一致。

如果命令运行后显示错误，则内核与 Citrix 模块不一致，必须重新构建。

重新构建 VHCI 内核模块

如果您的内核模块与 Citrix 的版本不一致，请执行以下操作：

从 Citrix 下载站点下载 LVDA 源代码。选择 Linux Virtual Delivery Agent (sources) 部分中包含的文件。
解压缩 citrix-linux-vda-sources.zip 文件。导航到 linux-vda-souces/vhci-hcd-1.15.tar.bz2，并使用 tar xvf vhci-hcd-1.15.tar.bz2 解压 VHCI 源文件。
基于头文件和 Module.symvers 文件构建内核模块。按照以下步骤安装内核头文件并根据相应的 Linux 发行版创建 Module.symvers：

RHEL/CentOS：
```
  yum install kernel-devel

```
SUSE 12：
```
  zypper install kernel-devel

  zypper install kernel-source

```
Ubuntu：
```
  apt-get install linux-headers

```
提示：

如果安装成功，将会有类似如下文件夹的内核文件夹：

/usr/src/kernels/3.10.0-327.10.1.el7.x86_64
在 /usr/src/kernels/3.10.0-327.10.1.el7.x86_64 文件夹中，验证 Module.symvers 文件是否存在。如果此文件不在该文件夹中，请构建内核（按顺序运行以下命令：make oldconfig、make prepare、make modules、make）以获取此文件或者从 /usr/src/kernels/3.10.0-327.10.1.el7.x86_64-obj/x86_64/defaults/module.* 进行复制

运行以下命令以安装开发工具。

RHEL 8、CentOS 8：

  yum groupinstall 'Development Tools'

  yum install elfutils-libelf-devel
<!--NeedCopy-->

RHEL 7、CentOS 7：

  yum groupinstall 'Development Tools'
<!--NeedCopy-->

Ubuntu 20.04、Ubuntu 18.04、Debian 10：

  apt install build-essential flex bison libelf-dev
<!--NeedCopy-->

Ubuntu 16.04：

  apt install build-essential flex bison

<!--NeedCopy-->

在 vhci-hcd-1.15/Makefile 文件中，更改 VCHI 的 Makefile，并将 KDIR 设置为内核目录：

  #KDIR = $(BUILD_PREFIX)/lib/modules/$(KVERSION)/build

  KDIR = /usr/src/kernels/3.10.0-327.10.1.el7.x86_64
<!--NeedCopy-->

在文件夹 vhci-hcd-1.15/ 中，运行 make 以构建 VHCI 内核。

注意：

如果构建成功，则会在文件夹 vhci-hcd-1.15/ 中创建 usb-vhci-hcd.ko 和 usb-vhci-iocifc.ko。
将该内核模块替换未新构建的内核模块 cp -f usb-vhci-*.ko /opt/Citrix/VDA/lib64/

重新启动 USB 服务：

  service ctxusbsd restart
<!--NeedCopy-->

注销并重新登录会话。检查 USB 重定向是否正常。

解决内核构建问题

使用特定内核构建 VHCI 模块时可能会出现以下错误：

可能会出现 implicit declaration of function 'copy\_to\_user' 错误，请参见下面的屏幕截图：

该错误是由于内核中的头文件发生变化所致。作为一种解决方法，请将 #include <linux/uaccess.h> 行添加到 vhci-hcd-1.15/usb-vhci-iocifc.c 文件中。
可能会出现 'driver\_attr\_debug_output' undeclared 错误，请参见下面的屏幕截图：

当内核缺少符号时，将出现错误。作为一种解决方法，请在 vhci-hcd-1.15/usb-vhci-iocifc.c 和 vhci-hcd-1.15/usb-vhci-hcd.c 文件中禁用 DEBUG 的宏定义。
'make[3]: *** No rule to make target 'arch/x86/tools/relocs_32.c', needed by 'arch/x86/tools/relocs_32.o'. Stop. 错误可能会发生，请参见下面的屏幕截图：

作为一种解决方法，请通过在 vhci-hcd-1.15/ 路径下使用以下命令将 SUBDIRS=$(PWD) 替换为 M=$(shell pwd)：
```
   sed -i 's/SUBDIRS=$(PWD)/M=$(shell pwd)/g' Makefile

   sed -i 's/SUBDIRS=$(PWD)/M=$(shell pwd)/g' test/Makefile
 
```

./include/uapi/linux/stat.h:30:17: error: expected ')' before numeric constant #define S_IRUSR 00400 错误可能会发生，请参见下面的屏幕截图：

内核构建错误示意图

运行以下命令以解决此问题：

   sed -i 's/show_debug_output/debug_output_show/g' usb-vhci-iocifc.c usb-vhci-hcd.c  

   sed -i 's/store_debug_output/debug_output_store/g' usb-vhci-iocifc.c usb-vhci-hcd.c  

   sed -i 's/static DRIVER_ATTR(debug_output, S_IRUSR | S_IWUSR, debug_output_show, debug_output_store);/static DRIVER_ATTR_RW(debug_output);/g' usb-vhci-iocifc.c usb-vhci-hcd.c
 <!--NeedCopy-->

./arch/x86/include/asm/uaccess.h:433:29: error: invalid initializer __typeof__(ptr) __pu_ptr = (ptr); \ 错误可能会发生，请参见下面的屏幕截图：

作为一种解决方法，请将 usb-vhci-iocifc.c 文件的第 219 行从 __put_user('\0', arg->bus_id); 更改为 __put_user('\0', arg->bus_id + 0);。
error: 'access_ok' undeclared (first use in this function) if(unlikely((_IOC_DIR(cmd) & _IOC_READ) && !access_ok(VERIFY_WRITE, arg, _IOC_SIZE(cmd)))) 错误可能会发生，请参见下面的屏幕截图：

运行以下命令以解决此问题：
```
   sed -i 's/VERIFY_READ, //g' usb-vhci-iocifc.c  
   sed -i 's/VERIFY_WRITE, //g' usb-vhci-iocifc.c
 
```

解决 USB 重定向问题

请根据本节中的信息解决您在使用 Linux VDA 时可能遇到的各种问题。

无法卸载重定向的 USB 磁盘

为了对从 Citrix Workspace 应用程序重定向的所有 USB 磁盘进行访问控制，Linux VDA 采用管理权限管理所有这些设备，确保只有所有者才能访问重定向的设备。因此，没有管理权限的用户不能卸载设备。

无法卸载设备的示意图

停止重定向 USB 磁盘时文件丢失

如果将 USB 磁盘重定向到会话并尝试修改该磁盘（例如，在磁盘上创建一些文件），然后立即使用 Citrix Workspace 应用程序的工具栏停止重定向，则您修改或创建的文件可能会丢失。出现此问题是因为您将数据写入文件系统时，系统在文件系统中装载内存缓存。数据并未写入磁盘本身。如果使用 Citrix Workspace 应用程序的工具栏停止重定向，则没有时间将数据刷新至磁盘，从而导致数据丢失。为了解决此问题，请先在终端上使用 sync 命令将数据刷新至磁盘，然后再停止 USB 重定向。

停止重定向 USB 磁盘时文件丢失示意图

Citrix Workspace 应用程序的工具栏中无设备

有时，您可能无法看到 Citrix Workspace 应用程序的工具栏中没有列出设备，这表示没有进行 USB 重定向。如果遇到该问题，请确认以下事项：

策略已配置为允许 USB 重定向
内核模块与您的内核兼容

Workspace 应用程序工具栏中的设备选项卡示意图

注意：

设备选项卡在适用于 Linux 的 Citrix Workspace 应用程序中不可用。

当 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 会配置和装载磁盘。用户（且仅限安装它的所有者）无需执行任何其他配置即可访问该磁盘。未包含在受支持设备列表中的设备可能不是这种情况。

本内容的正式版本为英文版。部分 Cloud Software Group 文档内容采用了机器翻译，仅供您参考。Cloud Software Group 无法控制机器翻译的内容，这些内容可能包含错误、不准确或不合适的语言。对于从英文原文翻译成任何其他语言的内容的准确性、可靠性、适用性或正确性，或者您的 Cloud Software Group 产品或服务沿用了任何机器翻译的内容，我们均不作任何明示或暗示的保证，并且适用的最终用户许可协议或服务条款或者与 Cloud Software Group 签订的任何其他协议（产品或服务与已进行机器翻译的任何文档保持一致）下的任何保证均不适用。对于因使用机器翻译的内容而引起的任何损害或问题，Cloud Software Group 不承担任何责任。

配置 USB 重定向

May 5, 2025

投稿者:

C Y

May 5, 2025

投稿者:

C Y