WSL プラグイン

  • [アーティクル]

Windows アプリケーションでは、WSL プラグインを使用して、Linux 用 Windows サブシステム (WSL) 内で実行中の Linux プロセスを作成および操作できるようになりました。 この記事では、そのしくみの概要と、その使用を開始する方法について説明します。

プラグイン機能の理解

WSL プラグインでは、次のコア機能が提供されます。

  • WSL 仮想マシンの起動時に起動する Windows 実行可能ファイルをアプリケーションで指定できるようにします
  • Windows 実行可能ファイルは、WSL 内に Linux プロセスを作成でき、仮想化されたソケットを使用して Linux プロセスと直接通信できます

これらの機能を使用して、Windows アプリケーションは WSL エクスペリエンスの上に構築し、Linux 用 Windows サブシステムに関連する追加機能を提供できます。

プラグインのインストール

WSL プラグイン作成者として、プラグインの DLL ファイルを指すようにレジストリ キーを設定することで、コンピューターにプラグインをインストールできます。

また、WSL ユーザーとして、使用するすべてのアプリケーションが、通常のインストール プロセスの一環として WSL プラグインが自動的にインストールされます。

独自のプラグインの作成

プラグイン プロジェクトを開始するには、Win32 dll をビルドする必要があります。 これを設定する最も簡単な方法は、WSL プラグインのサンプル プロジェクトを試すことです。 WSL プラグイン サンプル リポジトリを git clone でローカル フォルダーに複製し、Visual Studio で開くことでこれを行うことができます。

プロジェクトを開いたら、dllmain.cpp ファイル (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) に移動して、WSL プラグインで使用できる関数の一覧が表示してください。

その後、[ビルド] タブを押してプロジェクトをビルドできます。これにより、wsl-plugin-sample\x64\Debug\WSLPluginSample.dll の下で使用できる DLL が出力されます。

プラグインのテスト

WSL プラグインは、デジタル署名されている場合にのみ実行されます。 これをテストするには、コンピューターでテスト署名を有効にする必要があります。

テスト署名の有効化とテスト証明書の作成

管理者特権の PowerShell ウィンドウを開き、次のコマンドを実行してテスト署名を有効にします。

## If this command results in "The value is protected by Secure Boot policy and cannot be modified or deleted"
## Then reboot the PC, go into BIOS settings, and disable Secure Boot. BitLocker may also affect your ability to modify this setting.
Bcdedit.exe -set TESTSIGNING ON

テスト署名が有効になったら (再起動が必要な場合があります)、上で作成した WSLPluginSample.dll ファイルのディレクトリにある管理者特権の Powershell コマンド プロンプトで、WSL テスト証明書を作成します。

# Create the cert
$certname = "WSLPluginTestCert"
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -Type CodeSigningCert

# Export it to a local path
Export-Certificate -Cert $cert -FilePath ".\$certname.cer"

# Sign the DLL file
Set-AuthenticodeSignature -FilePath "C:\dev\Path\To\Your\WSLPlugin.dll" -Certificate $cert

最後に、信頼されたルート証明機関に次の証明書をインポートします。

certutil -addstore "Root" ".\$certname.cer"

詳細については、「自己署名証明書の作成方法」に関するドキュメント ページを参照してください。

プラグインをインストールする

同じ管理者特権の PowerShell ウィンドウで、次のコマンドを実行してプラグインをインストールし、プラグイン DLL へのパスを既存のパスに変更してください。

Reg.exe add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin /t REG_SZ /d C:\Path\to\plugin.dll  /f

プラグインを使用するには、次の方法で WSL サービスを再起動します。

sc.exe stop wslservice
wsl.exe echo “test”

これでプラグインが読み込まれるはずです。 プラグインの読み込みに失敗した場合の詳細については、「トラブルシューティングと追加情報」セクションを参照してください。

完了したら、次のコマンドを実行してプラグインを削除できます (有効にするには、WSL サービスを再起動する必要があることに注意してください)。

Reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin

トラブルシューティングと追加情報

一般的なエラー コード:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> プラグイン DLL を読み込めませんでした。 プラグイン登録パスが正しいことを確認する
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> プラグイン DLL が署名されていないか、その署名がコンピューターによって信頼されていません
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> プラグイン DLL が WSLPLUGINAPI_ENTRYPOINTV1 または OnVmStarted() でエラーを返しました
  • Wsl/Service/CreateInstance/Plugin/* -> プラグイン DLL が OnDistributionStarted() でエラーを返しました

プラグイン Linux ユーザー領域

ExecuteBinary() を介して作成された Linux プロセスは、WSL2 仮想マシンのルート名前空間で実行されます。 この名前空間はどのディストリビューションにも関連付けられていないため、Mariner ベースのルート ファイル システムはごくわずかです。

そのファイル システムは書き込み可能な tmpfs です。つまり、WSL2 仮想マシンがシャットダウンされると、そこで加えられたすべての変更が削除されます。

WSL の実行中に wsl --debug-shell を実行することで、ルート名前空間の内容を調べることができます。

その他の注意点

  • すべての WSL プラグイン フックは同期型で、WSL はプラグイン フックが完了するまで待機してから続行します。
  • プラグインで返されるすべてのエラーは、WSL で致命的と見なされます (つまり、ユーザーのディストリビューションは開始されません)
  • プラグイン コードは、WSL サービスと同じアドレス空間で実行されます。 プラグインでクラッシュすると WSL サービス全体がクラッシュし、データが失われる可能性があります