WSL プラグイン

[アーティクル]
11/20/2023

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 サービス全体がクラッシュし、データが失われる可能性があります

次の方法で共有