Linux Virtual Delivery Agent

配置 USB 重定向

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 设备重定向(仅限工作站主机)。

编辑设置对话框中:

  1. 选择允许
  2. 单击确定

启用 USB 重定向示意图

设置 USB 重定向规则

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

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

  1. 单击新建添加重定向规则,或单击编辑检查现有规则。
  2. 创建(或编辑)规则后,单击确定

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

有关配置通用 USB 重定向的详细信息,请参阅 Citrix 通用 USB 重定向配置指南

构建 VHCI 内核模块

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

支持的 Linux 发行版 内核版本
RHEL 8.3 4.18.0-240.15.1
RHEL 8.2 4.18.0-240.15.1
RHEL 8.1 4.18.0-240.15.1
RHEL 7.9 3.10.0-1160.21.1
RHEL 7.8 3.10.0-1160.21.1
SUSE 12.5 4.12.14-122.63.1
Ubuntu 20.04 5.4.0-70
Ubuntu 18.04 4.15.0-140
Ubuntu 16.04 4.4.0-206
Debian 10 4.19.0-16

重要:

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

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

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

insmod /opt/Citrix/VDA/lib64/usb-vhci-hcd.ko

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

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

重新构建 VHCI 内核模块

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

  1. Citrix 下载站点下载 LVDA 源代码。选择 Linux Virtual Delivery Agent (sources) 部分中包含的文件。

  2. 解压缩 citrix-linux-vda-sources.zip 文件。导航到 linux-vda-souces/vhci-hcd-1.15.tar.bz2,并使用 tar xvf vhci-hcd-1.15.tar.bz2 解压 VHCI 源文件。

  3. 基于头文件和 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

  4. 在 /usr/src/kernels/3.10.0-327.10.1.el7.x86_64 文件夹中,确认是否存在 Module.symvers 文件。如果该文件夹中没有此文件,请(通过按顺序运行以下命令:make oldconfigmake preparemake modulesmake)构建内核以获取此文件,或者从 /usr/src/kernels/3.10.0-327.10.1.el7.x86_64-obj/x86_64/defaults/module* 复制此文件。

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

    RHEL 8、CentOS 8:

    yum groupinstall 'Development Tools'
    
    yum install elfutils-libelf-devel
    

    RHEL 7、CentOS 7:

    yum groupinstall 'Development Tools'
    

    Ubuntu 20.04、Ubuntu 18.04、Debian 10:

    apt install build-essential flex bison libelf-dev
    

    Ubuntu 16.04:

    apt install build-essential flex bison
    
    
  6. 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
    
  7. 在文件夹 vhci-hcd-1.15/ 中,运行 make 以构建 VHCI 内核。

    注意:

    如果构建成功,则会在文件夹 vhci-hcd-1.15/ 中创建 usb-vhci-hcd.kousb-vhci-iocifc.ko

  8. 将内核模块替换为新构建的模块:cp -f usb-vhci-*.ko /opt/Citrix/VDA/lib64/

  9. 重新启动 USB 服务:

    service ctxusbsd restart
    
  10. 注销并重新登录会话。检查 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.cvhci-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
    
  • 可能会出现 ./arch/x86/include/asm/uaccess.h:433:29: error: invalid initializer __typeof__(ptr) __pu_ptr = (ptr); \ 错误,请参见下面的屏幕截图:

    内核构建错误示意图

    解决方法为,将第 219 行的 usb-vhci-iocifc.c 文件从 __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 应用程序的工具栏停止重定向,则没有时间将数据刷新至磁盘,从而导致数据丢失。为了解决此问题,请先在终端使用同步命令将数据刷新至磁盘,然后再停止 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 设备已成功重定向,但无法在会话中使用

通常情况下,只能重定向支持的 USB 设备。其他设备可能也会重定向到活动 Linux VDA 会话。对于每个重定向的设备,都会在系统 /dev 路径中创建用户拥有的节点。但是,用户是否可以成功使用设备由驱动程序和配置决定。如果您发现拥有(已插入)的某个设备无法访问,请将该设备添加到不受限制策略。

注意:

如果是 USB 驱动器,Linux VDA 会配置和装载磁盘。用户(且仅限安装它的所有者)无需执行任何其他配置即可访问该磁盘。未包含在受支持设备列表中的设备可能不是这种情况。

配置 USB 重定向