Pluginy WSL

Aplikace pro Windows teď můžou vytvářet a pracovat s linuxovými procesy běžícími uvnitř subsystému Windows pro Linux (WSL) s moduly plug-in WSL. Tento článek poskytuje přehled o tom, jak fungují a jak je začít používat.

Principy funkcí modulu plug-in

Moduly plug-in WSL poskytují tyto základní funkce:

• Umožňuje aplikacím určit spustitelný soubor Windows, který se spustí při spuštění virtuálního počítače WSL.
• Spustitelný soubor Windows může vytvářet linuxové procesy uvnitř WSL a může s nimi komunikovat přímo pomocí virtualizovaného soketu.

Díky těmto funkcím mohou aplikace pro Windows budovat na zkušenostech WSL a poskytovat dodatečné funkce související se subsystémem Windows pro Linux.

Instalace modulu plug-in

Jako tvůrce pluginu WSL můžete nainstalovat plugin na počítač nastavením klíče registru tak, aby odkazoval na DLL soubor vašeho pluginu.

A jako uživatel WSL všechny aplikace, které použijete, automaticky nainstalují moduly plug-in WSL jako součást jejich normálního procesu instalace.

Vytvoření vlastního modulu plug-in

Chcete-li spustit projekt modulu plug-in, budete muset sestavit knihovnu DLL win32. Nejjednodušším způsobem, jak to udělat, je vyzkoušet náš ukázkový projekt modulu plug-in WSL. Můžete to provést klonováním ukázkového úložiště pluginu WSL do místní složky a otevřením v aplikaci Visual Studio.

Při otevření projektu přejděte do dllmain.cpp souboru a zobrazí se seznam funkcí dostupných pro moduly plug-in WSL.

Pak můžete stisknout kartu Sestavení a sestavit projekt, který vypíše knihovnu DLL připravenou k použití, pravděpodobně pod wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Testování pluginu

Moduly plug-in WSL se spustí jenom v případě, že jsou digitálně podepsané. Abyste to mohli otestovat, budete muset na svém počítači povolit podepisování testů.

Povolení podepisování testů a vytvoření testovací certifikace

Otevřete okno PowerShellu se zvýšenými oprávněními a povolte podepisování testů spuštěním tohoto příkazu:

## 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

Po povolení testovacího podepisování (může se vyžadovat restartování) v příkazovém řádku PowerShellu se zvýšenými oprávněními, který je v adresáři vašeho WSLPluginSample.dll souboru vytvořeného výše, vytvoříme testovací certifikát 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

Poslední import certifikátu do důvěryhodné kořenové certifikační autority:

Import-Certificate -FilePath ".\$certname.cer" -CertStoreLocation Cert:\LocalMachine\Root"

Další informace najdete na stránce dokumentace jak vytvořit samosignovaný certifikát.

Instalace modulu plug-in

Ve stejném okně PowerShellu se zvýšenými oprávněními spusťte následující příkaz, který nainstaluje modul plug-in, a nezapomeňte změnit cestu ke knihovně DLL modulu plug-in na vaši stávající cestu:

Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Value "C:\Path\to\plugin.dll" -Force

Pokud chcete použít modul plug-in, restartujte službu wsl prostřednictvím:

Stop-Service -Name "wslservice" -Force
wsl.exe echo "test"

Váš plug-in by se teď měl načíst. Další informace najdete v sekci Řešení potíží a další informace, pokud se modul plug-in nepodařilo načíst.

A až budete hotovi, můžete spuštěním tohoto příkazu odebrat modul plug-in (mějte na paměti, že budete muset restartovat službu WSL, aby se projevila):

Remove-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins" -Name "demo-plugin" -Force

Řešení potíží a další informace

Běžné kódy chyb:

• Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND –> nepodařilo se načíst knihovnu DLL pluginu. Zkontrolujte správnost cesty registrace modulu plug-in.
• Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE –> knihovna DLL zásuvného modulu není podepsaná, nebo počítač jejímu podpisu nedůvěřuje
  • Povolte podepisování testů a přečtěte si část o tom, jak nastavit testovací certifikát.
• Wsl/Service/CreateInstance/CreateVm/Plugin/* –> knihovna DLL modulu plug-in vrátila chybu v WSLPLUGINAPI_ENTRYPOINTV1 nebo OnVmStarted()
• Wsl/Service/CreateInstance/Plugin/* –> knihovna DLL modulu plug-in vrátila chybu v OnDistributionStarted()

Pluginy v linuxovém uživatelském prostoru

Procesy Linuxu vytvořené prostřednictvím ExecuteBinary() se spustí v kořenovém oboru názvů virtuálního počítače WSL2. Tento obor názvů není přidružený k žádné distribuci a má velmi minimální kořenový systém souborů založený na Mariner.

Tento systém souborů je zapisovatelný tmpfs, což znamená, že všechny změny provedené v něm budou vyřazeny při vypnutí virtuálního počítače WSL2.

Obsah kořenového oboru názvů můžete zkontrolovat spuštěním wsl --debug-shell, zatímco je WSL spuštěn.

Další důležité informace

• Všechny háky modulu plug-in WSL jsou synchronní, což znamená, že WSL před pokračováním počká na dokončení hooků modulu plug-in.
• Jakákoli chyba vrácená pluginem je považována za závažnou prostředím WSL (což znamená, že distribuce uživatele se nespustí).
• Kód modulu plug-in běží ve stejném adresní prostoru jako služba WSL. Jakékoli chybové ukončení modulu plug-in způsobí chybové ukončení celé služby WSL, což může způsobit ztrátu dat.