다음을 통해 공유

WSL 플러그 인

  • 아티클

이제 Windows 애플리케이션은 WSL(Linux용 Windows 하위 시스템) 내에서 실행되는 Linux 프로세스를 만들고 WSL 플러그 인과 상호 작용할 수 있습니다. 이 문서에서는 작동 방식 및 사용을 시작하는 방법에 대한 개요를 제공합니다.

플러그 인 기능 이해

WSL 플러그 인은 다음과 같은 핵심 기능을 제공합니다.

  • 애플리케이션에서 WSL 가상 머신이 시작될 때 시작되는 Windows 실행 파일을 지정할 수 있습니다.
  • Windows 실행 파일은 WSL 내부에 Linux 프로세스를 만들 수 있으며 가상화된 소켓을 사용하여 직접 통신할 수 있습니다.

이러한 기능을 사용하여 Windows 애플리케이션은 WSL 환경을 기반으로 빌드하고 Linux용 Windows 하위 시스템 관련된 추가 기능을 제공할 수 있습니다.

플러그 인 설치

WSL 플러그 인 작성자는 플러그 인의 DLL 파일을 가리키도록 레지스트리 키를 설정하여 컴퓨터에 플러그 인을 설치할 수 있습니다.

또한 WSL 사용자로서 사용하는 모든 애플리케이션은 일반 설치 프로세스의 일부로 WSL 플러그 인을 자동으로 설치합니다.

고유한 플러그 인 만들기

플러그 인 프로젝트를 시작하려면 Win32 dll을 빌드해야 합니다. 이를 통해 설정하는 가장 간단한 방법은 WSL 플러그 인 샘플 프로젝트를 시도하는 것입니다. WSL 플러그 인 샘플 리포지토리를 로컬 폴더에 git clone 복제하고 Visual Studio에서 열어서 이 작업을 수행할 수 있습니다.

프로젝트를 열면 파일(https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp)로 이동 dllmain.cpp 하면 WSL 플러그 인에서 사용할 수 있는 함수 목록이 표시됩니다.

그런 다음 "빌드" 탭을 누르고 프로젝트를 빌드할 수 있습니다. 그러면 사용할 wsl-plugin-sample\x64\Debug\WSLPluginSample.dll준비가 된 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

테스트 서명을 사용하도록 설정하면(다시 부팅이 필요할 수 있음) 위에서 만든 WSLPluginSample.dll 파일의 디렉터리에 있는 관리자 권한 Powershell 명령 프롬프트에서 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 사용자 공간

ExecuteBinary()를 통해 만든 Linux 프로세스는 WSL2 Virtual Machine의 루트 네임스페이스에서 실행됩니다. 이 네임스페이스는 배포에 연결되지 않으며 매우 최소한의 Mariner 기반 루트 파일 시스템을 가지고 있습니다.

해당 파일 시스템은 쓰기 가능한 tmpfs입니다. 즉, WSL2 Virtual Machine이 종료될 때 모든 변경 내용이 삭제됩니다.

WSL이 실행되는 동안 실행 wsl --debug-shell 하여 루트 네임스페이스의 콘텐츠를 검사할 수 있습니다.

추가 고려 사항

  • 모든 WSL 플러그 인 후크는 동기식이므로 WSL은 계속하기 전에 플러그 인 후크가 완료될 때까지 기다립니다.
  • 플러그 인에서 반환된 오류는 WSL에 의해 치명적인 것으로 간주됩니다(사용자의 배포가 시작되지 않음을 의미).
  • 플러그 인 코드는 WSL 서비스와 동일한 주소 공간에서 실행됩니다. 플러그 인의 충돌이 발생하면 전체 WSL 서비스가 충돌하여 데이터 손실이 발생할 수 있습니다.