Condividi tramite

Plug-in WSL

  • Articolo

Le applicazioni Windows possono ora creare e interagire con i processi Linux in esecuzione all'interno del sottosistema Windows per Linux (WSL) con i plug-in WSL. Questo articolo offre una panoramica del loro funzionamento e di come iniziare a usarli.

Informazioni sulle funzionalità dei plug-in

I plug-in WSL offrono queste funzionalità di base:

  • Consente alle applicazioni di specificare un eseguibile windows che viene avviato all'avvio della macchina virtuale WSL
  • L'eseguibile di Windows può creare processi Linux all'interno di WSL e può comunicare direttamente con essi usando un socket virtualizzato

Usando questi strumenti, le applicazioni Windows possono basarsi su esperienze WSL e offrire funzionalità aggiuntive correlate al sottosistema Windows per Linux.

Installazione di un plug-in

In qualità di creatore di plug-in WSL, è possibile installare il plug-in in un computer impostando una chiave del Registro di sistema in modo che punti al file DLL del plug-in.

E come utente WSL, qualsiasi applicazione usata installerà automaticamente i plug-in WSL come parte del normale processo di installazione.

Creazione di un plug-in personalizzato

Per avviare un progetto di plug-in è necessario compilare una DLL Win32. Il modo più semplice per configurare questo approccio consiste nel provare il progetto di esempio di plug-in WSL. A tale scopo, clonare il repository di esempio del plug-in WSL in una cartella locale con git clone e aprirlo in Visual Studio.

Quando si apre il progetto, passare al dllmain.cpp file (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) e verrà visualizzato l'elenco delle funzioni disponibili per i plug-in WSL.

È quindi possibile premere la scheda "Compila" e compilare il progetto, che restituirà una DLL pronta per l'uso, probabilmente in wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Test del plug-in

I plug-in WSL verranno eseguiti solo se sono firmati digitalmente. Per testare questa operazione, è necessario abilitare la firma di test nel computer.

Abilitazione della firma dei test e creazione di una certificazione di test

Aprire una finestra di PowerShell con privilegi elevati e abilitare la firma dei test eseguendo questo comando:

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

Dopo aver abilitato la firma di test (potrebbe essere necessario un riavvio), in un prompt dei comandi di PowerShell con privilegi elevati nella directory del file WSLPluginSample.dll creato in precedenza verrà creato un certificato di test 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

Importare infine il certificato nell'autorità di certificazione radice attendibile:

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

Per altre informazioni, vedere la pagina come creare una documentazione del certificato autofirmato.

Installare il plug-in

Nella stessa finestra di PowerShell con privilegi elevati eseguire il comando seguente per installare il plug-in e assicurarsi di modificare il percorso della DLL del plug-in nel percorso esistente:

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

Per usare il plug-in, riavviare il servizio wsl tramite:

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

Il plug-in dovrebbe ora essere caricato. Per altre informazioni, vedere la sezione Risoluzione dei problemi e informazioni aggiuntive se il plug-in non è riuscito a caricare.

E quindi al termine, è possibile eseguire questo comando per rimuovere il plug-in (Tenere presente che sarà necessario riavviare il servizio WSL per renderlo effettivo):

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

Risoluzione dei problemi e informazioni aggiuntive

Codici di errore comuni:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND:> impossibile caricare la DLL del plug-in. Verificare che il percorso di registrazione del plug-in sia corretto
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> La DLL del plug-in non è firmata o la firma non è attendibile dal computer
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* -> La DLL del plug-in ha restituito un errore in WSLPLUGINAPI_ENTRYPOINTV1 o OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* -> La DLL del plug-in ha restituito un errore in OnDistributionStarted()

Plug-in Spazio utente Linux

I processi Linux creati tramite ExecuteBinary() verranno eseguiti nello spazio dei nomi radice della macchina virtuale WSL2. Questo spazio dei nomi non è associato ad alcuna distribuzione e ha un file system radice basato su Mariner molto minimo.

Il file system è un tmpf scrivibile, vale a dire che tutte le modifiche apportate verranno eliminate quando la macchina virtuale WSL2 viene arrestata.

È possibile esaminare il contenuto dello spazio dei nomi radice eseguendo wsl --debug-shell durante l'esecuzione di WSL.

Considerazioni aggiuntive

  • Tutti gli hook del plug-in WSL sono sincroni, ovvero WSL attenderà il completamento degli hook del plug-in prima di continuare.
  • Qualsiasi errore restituito da un plug-in è considerato irreversibile da WSL (ovvero la distribuzione dell'utente non verrà avviata)
  • Il codice del plug-in viene eseguito nello stesso spazio indirizzi del servizio WSL. Qualsiasi arresto anomalo in un plug-in arresta anomalo dell'intero servizio WSL, causando potenzialmente la perdita di dati