Поделиться через

Подключаемые модули WSL

  • Статья

Теперь приложения Windows могут создавать и взаимодействовать с процессами Linux, выполняемыми внутри подсистема Windows для Linux (WSL) с подключаемыми модулями WSL. В этой статье приводятся общие сведения о том, как они работают и как приступить к работе с ними.

Общие сведения о функциональных возможностях подключаемого модуля

Подключаемые модули WSL предоставляют следующие основные функции:

  • Позволяет приложениям указывать исполняемый файл Windows, который запускается при запуске виртуальной машины WSL.
  • Исполняемый файл Windows может создавать процессы Linux внутри WSL, и он может напрямую взаимодействовать с ними с помощью виртуализированного сокета.

С помощью этих приложений Windows можно создавать на основе интерфейсов WSL и предоставлять дополнительные функциональные возможности, связанные с подсистема Windows для Linux.

Установка подключаемого модуля

В качестве создателя подключаемого модуля WSL вы можете установить подключаемый модуль на компьютере, задав раздел реестра, чтобы указать dll-файл подключаемого модуля.

И как пользователь WSL, любое приложение, которое вы используете, автоматически установит подключаемые модули WSL в рамках их обычного процесса установки.

Создание собственного подключаемого модуля

Чтобы запустить проект подключаемого модуля, необходимо создать библиотеку DLL Win32. Самый простой способ настроить это — попробовать пример проекта подключаемого модуля WSL. Это можно сделать, клонируя пример репозитория подключаемого модуля WSL в локальную папку git clone и открыв ее в Visual Studio.

При открытии проекта перейдите к dllmain.cpp файлу (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp), и вы увидите список функций, доступных для подключаемых модулей WSL.

Затем можно нажать вкладку "Сборка" и создать проект, который будет выводить библиотеку DLL, которая будет готова к использованию, скорее всего, в разделе wsl-plugin-sample\x64\Debug\WSLPluginSample.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

После включения тестовой подписи (может потребоваться перезагрузка), в командной строке с повышенными привилегиями PowerShell, которая находится в каталоге файла WSLPluginSample.dll, созданного выше, мы создадим тестовый сертификат 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

Процессы Linux, созданные с помощью ExecuteBinary(), будут выполняться в корневом пространстве имен виртуальной машины WSL2. Это пространство имен не связано с любым дистрибутивом и имеет очень минимальную корневую файловую систему на основе Маринера.

Эта файловая система представляет собой записываемые tmpfs, что означает, что все изменения, внесенные в него, будут удалены при завершении работы виртуальной машины WSL2.

Содержимое корневого пространства имен можно проверить, выполнив во wsl --debug-shell время выполнения WSL.

Дополнительные рекомендации

  • Все перехватчики подключаемых модулей WSL синхронны, что означает, что WSL будет ожидать завершения перехватчиков подключаемых модулей перед продолжением.
  • Любая ошибка, возвращаемая подключаемым модулем, считается неустранимой WSL (это означает, что распространение пользователя не начнется).
  • Код подключаемого модуля выполняется в том же адресном пространстве, что и служба WSL. Любой сбой в подключаемом модуле завершится сбоем всей службы WSL, что может привести к потере данных.