Compartilhar via

Plugins do WSL

  • Artigo

Os aplicativos do Windows agora podem criar e interagir com processos do Linux em execução dentro do Subsistema do Windows para Linux (WSL) com plugins do WSL. Este artigo fornece uma visão geral de como eles funcionam e como começar a usá-los.

Noções básicas sobre a funcionalidade do plugin

Os plugins do WSL fornecem estas funcionalidades principais:

  • Permite que os aplicativos especifiquem um executável do Windows que começa quando a máquina virtual do WSL é iniciada
  • O executável do Windows pode criar processos do Linux dentro do WSL e pode se comunicar diretamente com eles usando um soquete virtualizado

Com isso, os aplicativos do Windows podem se basear nas experiências do WSL e fornecer funcionalidades adicionais relacionadas ao Subsistema do Windows para Linux.

Instalar um plugin

Como um criador de plugin do WSL, você pode instalar seu plugin em um computador definindo uma chave do Registro para apontar para o arquivo DLL do plugin.

E como usuário do WSL, qualquer aplicativo usado instalará automaticamente plugins do WSL como parte do processo normal de instalação.

Criar seu próprio plugin

Para iniciar um projeto de plugin, você precisará criar uma DLL Win32. A maneira mais simples de iniciar é testar nosso projeto de exemplo de plugin para o WSL. Você pode fazer isso clonando o repositório de exemplo de plugin do WSL para uma pasta local com git clone e abri-lo no Visual Studio.

Ao abrir o projeto, navegue até o arquivo dllmain.cpp (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) e você verá a lista de funções disponíveis para plugins do WSL.

Em seguida, você pode pressionar a guia "Compilar" e compilar seu projeto, que produzirá uma DLL pronta para uso, provavelmente em wsl-plugin-sample\x64\Debug\WSLPluginSample.dll.

Testar seu plugin

Os plugins do WSL só serão executados se forem assinados digitalmente. Para testar isso, você precisará habilitar a assinatura de teste em seu computador.

Habilitar a assinatura de teste e criar uma certificação de teste

Abra uma janela do PowerShell com privilégios elevados e habilite a assinatura de teste executando este 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

Depois que a assinatura de teste estiver habilitada (pode ser necessário reiniciar), em um prompt de comando do PowerShell com privilégios elevados que está no diretório do arquivo WSLPluginSample.dll criado acima, criaremos um certificado de teste 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

Por fim, importe o certificado para a autoridade de certificação raiz confiável:

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

Confira a página de documentos Como criar um certificado autoassinado para obter mais informações.

Instalar o plug-in

Na mesma janela com privilégios elevados do PowerShell, execute o comando abaixo para instalar o plugin e altere o caminho da DLL do plugin para o caminho existente:

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

Para usar o plugin, reinicie o serviço WSL por meio de:

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

Seu plugin agora deve ser carregado. Consulte a seção Solução de problemas e informações adicionais para obter mais informações se o plugin não tiver sido carregado.

E, quando terminar, você poderá executar este comando para remover o plugin (lembre-se de que você precisará reiniciar o serviço WSL para que ele entre em vigor):

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

Solução de problemas e informações adicionais

Códigos de erro comuns:

  • Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND –> não foi possível carregar a DLL do plugin. Verifique se o caminho de registro do plugin está correto
  • Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> A DLL do plugin não está assinada ou sua assinatura não é confiável pelo computador
  • Wsl/Service/CreateInstance/CreateVm/Plugin/* –> A DLL do plugin retornou um erro em WSLPLUGINAPI_ENTRYPOINTV1 ou OnVmStarted()
  • Wsl/Service/CreateInstance/Plugin/* –> A DLL do plugin retornou um erro em OnDistributionStarted()

Espaço de usuário Linux de plugins

Os processos do Linux criados por meio de ExecuteBinary() serão executados no namespace raiz da Máquina Virtual WSL2. Esse namespace não está associado a nenhuma distribuição e tem um sistema de arquivos raiz baseado no Mariner muito mínimo.

Esse sistema de arquivos é um tmpfs gravável, o que significa que todas as alterações feitas nele serão descartadas quando a Máquina Virtual WSL2 for desligada.

Você pode inspecionar o conteúdo do namespace raiz executando wsl --debug-shell enquanto o WSL está em execução.

Considerações adicionais

  • Todos os ganchos de plugin do WSL são síncronos, o que significa que o WSL aguardará a conclusão dos ganchos de plugin antes de continuar.
  • Qualquer erro retornado por um plugin é considerado fatal pelo WSL (o que significa que a distribuição do usuário não será iniciada)
  • O código do plugin é executado no mesmo espaço de endereço que o serviço WSL. Qualquer falha em um plugin falhará em todo o serviço WSL, potencialmente causando perda de dados