Linux Virtual Delivery Agent 2104

USBリダイレクトの設定

USBデバイスは、Citrix WorkspaceアプリとLinux VDAデスクトップ間で共有されます。USBデバイスがデスクトップにリダイレクトされると、USBデバイスをローカルに接続されているかのように使用することができます。

ヒント:

ネットワーク遅延が100ミリ秒未満の場合は、USBリダイレクトを使用することをお勧めします。ネットワーク遅延が200ミリ秒を超える場合は、USBリダイレクトを使用しないでください。

USBリダイレクトの主な機能として、次の3つが挙げられます:

  • オープンソースプロジェクトの導入(VHCI)
  • VHCIサービス
  • USBサービス

オープンソースVHCI:

USBリダイレクトのこの機能により、IPネットワーク上でシステムを共有する汎用USBデバイスを開発します。この機能はLinuxカーネルドライバーおよびユーザーモードのライブラリで構成されており、ユーザーはカーネルドライバーと通信してすべてのUSBデータを取得することができます。Linux VDAの導入では、VHCIのカーネルドライバーがCitrixで再利用されます。ただし、Linux VDAとCitrix Workspaceアプリ間のUSBデータ転送はすべてCitrix ICAプロトコルパッケージに格納されます。

VHCIサービス:

VHCIサービスは、Citrixが提供する、VHCIカーネルモジュールとの通信のためのオープンソースサービスです。このサービスはVHCIとCitrix USBサービスの間のゲートウェイとして機能します。

USBサービス:

USBサービスは、USBデバイスでの仮想化およびデータ転送をすべて管理するCitrixモジュールです。

USBリダイレクトのしくみ

通常、Linux VDAへのUSBデバイスのリダイレクトが正常に行われると、デバイスノードがシステムの/devパスに作成されます。ただし、リダイレクトされたデバイスがアクティブなLinux VDAセッションで使用できない場合があります。USBデバイスが正常に機能するかどうかはドライバーによって決まり、一部のデバイスは特別なドライバーを必要とします。ドライバーが提供されていない場合、リダイレクトされたUSBデバイスはアクティブなLinux VDAセッションにアクセスできません。確実に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 Flash Drive 0781:5580 FAT32
WD HDD 1058:10B8 FAT32
USB 3Dマウス VID:PID
3DConnexion SpaceMouse Pro 046d: c62b
USBスキャナー VID:PID
Epson Perfection V330 photo 04B8: 0142

USBリダイレクトの設定

USBデバイスのリダイレクトの有効化および無効化は、Citrixポリシーにより制御されます。また、Delivery Controllerポリシーを使用してデバイスの種類を指定することもできます。USBリダイレクトをLinux VDAに設定するには、次のポリシーと規則を設定します:

  • クライアントUSBデバイスリダイレクトポリシー
  • クライアントUSBデバイスリダイレクト規則

USBリダイレクトポリシーを有効にする

Citrix Studioで、クライアントとUSBデバイス間のリダイレクトを有効または無効にします(ワークステーションのホストの場合のみ)。

[設定の編集] ダイアログボックスで、以下の設定を行います:

  1. [許可] を選択します。
  2. [OK] をクリックします。

USBリダイレクト有効化の画像

USBリダイレクト規則を設定する

USBリダイレクトポリシーを有効にしたら、Citrix Studioを使用して、Linux VDAでの使用を許可または禁止するデバイスを指定して、リダイレクト規則を設定します。

[クライアントUSBデバイスリダイレクト規則] ダイアログボックスで、次の操作を行います:

  1. [新規] をクリックしてリダイレクト規則を追加するか、[編集] をクリックして既存の規則を確認します。
  2. 規則の作成または編集後、[OK] をクリックします。

クライアントUSBリダイレクト規則設定の画像

汎用USBリダイレクトの設定について詳しくは、「Citrixの汎用USBリダイレクトの設定ガイド」を参照してください。

VHCIカーネルモジュールを構築します

USBリダイレクトはVHCIカーネルモジュール(usb-vhci-hcd.koおよびusb-vhci-iocif.ko)によって異なります。これらのモジュールは、RPMパッケージの一部としてLinux VDAディストリビューションに含まれます。これらは、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
<!--NeedCopy-->

コマンドが正常に実行される場合は、カーネルモジュールのロードに成功し、バージョンがCitrixによりインストールされたものに対応しています。

コマンドの実行でエラーが生じた場合、カーネルはCitrixのモジュールに対応していないため、再構築の必要があります。

VHCIカーネルモジュールの再構築

カーネルモジュールがCitrixのバージョンに対応していない場合は、次の手順に従います:

  1. Citrixのダウンロードサイトから、LVDAソースコードをダウンロードします。セクション [Linux Virtual Delivery Agent(ソース)] に含まれるファイルを選択します。

  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
    <!--NeedCopy-->
    

    SUSE 12:

    zypper install kernel-devel
    
    zypper install kernel-source
    <!--NeedCopy-->
    

    Ubuntu:

    apt-get install linux-headers
    <!--NeedCopy-->
    

    ヒント:

    インストールが正常に完了すると、以下に類似したカーネルフォルダーが作成されます:

    /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 oldconfig; make prepare; make modules; make)、/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
    <!--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-->
    
  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
    <!--NeedCopy-->
    
  7. vhci-hcd-1.15/フォルダーでmakeコマンドを実行して、VHCIカーネルを構築します。

    注:

    構築に成功すると、usb-vhci-hcd.koおよびusb-vhci-iocifc.kovhci-hcd-1.15/フォルダーに作成されます。

  8. カーネルモジュールを新しく構築したモジュールに置き換えます:cp -f usb-vhci-*.ko /opt/Citrix/VDA/lib64/

  9. USBサービスを再起動します:

    service ctxusbsd restart
    <!--NeedCopy-->
    
  10. ログオフして再びセッションに戻ります。USBリダイレクトが機能しているかを確認します。

カーネル構築の問題のトラブルシューティング

特定のカーネルを使用してVHCIモジュールを構築すると、次のエラーが発生する可能性があります:

  • implicit declaration of function 'copy\_to\_user'エラーが発生する可能性があります。次のスクリーンキャプチャを参照してください。

    関数の暗黙の宣言エラーの画像

    このエラーは、カーネルのヘッダーファイルの変更が原因で発生します。この問題を回避するには、vhci-hcd-1.15/usb-vhci-iocifc.cファイルに #include <linux/uaccess.h> という行を追加します。

    カーネル構築エラーの回避の行を追加する画像

  • 'driver\_attr\_debug_output' undeclaredエラーが発生する可能性があります。次のスクリーンキャプチャを参照してください。

    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
     <!--NeedCopy-->
    
  • ./include/uapi/linux/stat.h:30:17: error: expected ')' before numeric constant
    #define S_IRUSR 00400エラーが発生する可能性があります。次のスクリーンキャプチャを参照してください。

    Image of a kernel building error

    Run the following commands to work around the issue:

     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); \エラーが発生する可能性があります。次のスクリーンキャプチャを参照してください。

    Image of a kernel building error

    As a workaround, change the 219 line of the usb-vhci-iocifc.c file from __put_user('\0', arg->bus_id); to __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))))エラーが発生する可能性があります。次のスクリーンキャプチャを参照してください。

    Image of a kernel building error

    Run the following commands to work around the issue:

     sed -i 's/VERIFY_READ, //g' usb-vhci-iocifc.c  
     sed -i 's/VERIFY_WRITE, //g' usb-vhci-iocifc.c
     <!--NeedCopy-->
    

USBリダイレクト問題のトラブルシューティング

このセクションでは、Linux VDAの使用におけるさまざまな問題のトラブルシューティングについて説明します。

リダイレクトされたUSBディスクをマウント解除できない

Linux VDAでは、Citrix WorkspaceアプリからリダイレクトされたすべてのUSBディスクのアクセスを制御するため、これらのデバイスをすべて管理者権限で管理し、リダイレクトされたデバイスに所有者のみがアクセスできるようにしています。そのため、管理者権限を持たないユーザーはデバイスをマウント解除できません。

デバイスをマウント解除できない場合の画像

USBディスクのリダイレクトを停止するとファイルが失われる

USBディスクをセッションにリダイレクトして、ディスク上でのファイルの作成などでディスクを変更した後に、Citrix Workspaceアプリのツールバーを使用して直ちにリダイレクトを停止すると、変更または作成したファイルが失われることがあります。この問題は、ファイルシステムにデータを書き込むとメモリキャッシュがファイルシステムにマウントされることが原因で発生します。データはディスクそのものには書き込まれません。Citrix Workspaceアプリのツールバーを使用してリダイレクトを停止した場合、データがディスクにフラッシュされる時間が残っていないため、データが失われます。この問題を解決するには、ターミナルのsyncコマンドを使用してデータをディスクにフラッシュしてからUSBリダイレクトを停止します。

USBディスクのリダイレクトを停止してファイルが失われた場合の画像

Citrix Workspaceアプリのツールバーにデバイスが見つからない場合

Citrix Workspaceアプリのツールバーにデバイスが表示されなくなることがありますが、これはUSBリダイレクトが行われていないことを示します。問題が発生した場合は、次の点を確認してください。

  • ポリシーが、USBリダイレクトを許可する設定になっている
  • カーネルモジュールが、使用するカーネルに対応している

Workspaceアプリツールバーのデバイスタブの画像

注:

[デバイス] タブはLinux向けCitrix Workspaceアプリで使用できません。

Citrix WorkspaceアプリのツールバーにUSBデバイスが表示されるが [ポリシーの制限] と表記されリダイレクトが失敗する

問題が発生した場合は、次の手順を実行してください:

  • Linux VDAポリシーを、リダイレクトを有効にする設定にします。
  • Citrix Workspaceアプリのレジストリで追加のポリシー制限が構成されているかを確認します。レジストリパスでDeviceRulesを確認し、この設定がデバイスのアクセスを拒否していないことを確認します:

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\GenericUSB

USBデバイスのリダイレクトは正常に行われるが、セッションでデバイスを使用できない

通常、リダイレクトできるのはサポートされているUSBデバイスのみとなります。他のデバイスがLinux VDAのアクティブなセッションにリダイレクトできる場合もあります。リダイレクトしたデバイスごとに、ユーザーの所有するノードがシステムの /dev パスに作成されます。ただし、ユーザーがデバイスを正常に使用できるかどうかはドライバーと構成によって決定されます。所有(プラグイン)しているもののアクセスできないデバイスを見つけた場合は、そのデバイスを制限されていないポリシーに追加します。

注:

USBドライバーの場合は、Linux VDAがディスクの設定とマウントを行います。ユーザー(およびデバイスをインストールした所有者のみ)は追加の設定なしでディスクにアクセスできます。「サポートされているデバイス一覧」に掲載されていないデバイスについては、これが適用されないことがあります。

USBリダイレクトの設定