Partager via

Plug-ins WSL

Les applications Windows peuvent désormais créer et interagir avec des processus Linux s’exécutant à l’intérieur du sous-système Windows pour Linux (WSL) avec des plug-ins WSL. Cet article donne une vue d’ensemble de leur fonctionnement et explique comment commencer à les utiliser.

Présentation des fonctionnalités du plug-in

Les plug-ins WSL fournissent ces fonctionnalités principales :

  • Permet aux applications de spécifier un exécutable Windows qui démarre lorsque la machine virtuelle WSL est démarrée
  • L’exécutable Windows peut créer des processus Linux à l’intérieur de WSL et peut communiquer directement avec eux à l’aide d’un socket virtualisé

Ces applications Windows peuvent s’appuyer sur des expériences WSL et fournir des fonctionnalités supplémentaires liées au sous-système Windows pour Linux.

Installation d’un plug-in

En tant que créateur de plug-in WSL, vous pouvez installer votre plug-in sur un ordinateur en définissant une clé de Registre pour pointer vers le fichier DLL de votre plug-in.

En tant qu’utilisateur WSL, toute application que vous utilisez installe automatiquement les plug-ins WSL dans le cadre de leur processus d’installation normal.

Création de votre propre plug-in

Pour démarrer un projet de plug-in, vous devez générer une dll Win32. La façon la plus simple de se configurer avec cela consiste à essayer notre exemple de projet de plug-in WSL. Pour ce faire, clonez l’exemple de référentiel de plug-in WSL dans un dossier local et git clone ouvrez-le dans Visual Studio.

Lorsque vous ouvrez le projet, accédez au dllmain.cpp fichier et vous verrez la liste des fonctions disponibles pour les plug-ins WSL.

Vous pouvez ensuite appuyer sur l’onglet « Générer » et générer votre projet, ce qui génère une DLL prête à être utilisée, probablement sous wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Test de votre plug-in

Les plug-ins WSL s’exécutent uniquement s’ils sont signés numériquement. Pour tester cela, vous devez activer la signature de test sur votre ordinateur.

Activation de la signature de test et création d’une certification de test

Ouvrez une fenêtre PowerShell avec élévation de privilèges et activez la signature de test en exécutant cette commande :

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

Une fois la signature de test activée (un redémarrage peut être nécessaire), dans une invite de commandes PowerShell avec élévation de privilèges qui se trouve dans le répertoire de votre fichier WSLPluginSample.dll créé ci-dessus, nous allons créer un certificat de 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

Dernière importation du certificat dans l’autorité de certification racine approuvée :

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

Consultez la page de documentation comment créer un certificat auto-signé pour plus d'informations.

Installation du plug-in

Dans la même fenêtre PowerShell avec élévation de privilèges, exécutez la commande ci-dessous pour installer le plug-in et veillez à modifier le chemin d’accès à la DLL du plug-in en votre chemin existant :

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

Pour utiliser le plug-in, redémarrez le service wsl via :

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

Votre plug-in doit maintenant être chargé. Consultez la section Résolution des problèmes et informations supplémentaires pour plus d’informations si le plug-in n’a pas pu être chargé.

Ensuite, lorsque vous avez terminé, vous pouvez exécuter cette commande pour supprimer le plug-in (N’oubliez pas que vous devrez redémarrer le service WSL pour qu’il prenne effet) :

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

Résolution des problèmes et informations supplémentaires

Codes d’erreur courants :

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND :> la DLL du plug-in n’a pas pu être chargée. Vérifiez que le chemin d’inscription du plug-in est correct
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> La DLL de plug-in n’est pas signée ou sa signature n’est pas approuvée par l’ordinateur
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* :> la DLL du plug-in a renvoyé une erreur dans WSLPLUGINAPI_ENTRYPOINTV1 ou OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* :> la DLL du plug-in a renvoyé une erreur dans OnDistributionStarted()

Plugins espace utilisateur Linux

Les processus Linux créés via ExecuteBinary() s’exécutent dans l’espace de noms racine de la machine virtuelle WSL2. Cet espace de noms n’est associé à aucune distribution et a un système de fichiers racine basé sur Mariner très minimal.

Ce système de fichiers est un tmpfs accessible en écriture, ce qui signifie que toutes les modifications apportées à celui-ci seront supprimées lorsque la machine virtuelle WSL2 est arrêtée.

Vous pouvez inspecter le contenu de l’espace de noms racine en exécutant wsl --debug-shell pendant que WSL est en cours d'exécution.

Considérations supplémentaires

  • Tous les hooks de plug-in WSL sont synchrones, ce qui signifie que WSL attend que les hooks de plug-in soient terminés avant de continuer.
  • Toute erreur retournée par une extension est considérée comme fatale par WSL, ce qui signifie que la distribution de l’utilisateur ne démarre pas.
  • Le code du plug-in s’exécute dans le même espace d’adressage que le service WSL. Tout incident dans un plug-in bloque l’intégralité du service WSL, ce qui peut entraîner une perte de données
  • Last updated on