From 03ea549c67d5d0feb70d928020eabf287c8e8538 Mon Sep 17 00:00:00 2001 From: Craig Loewen Date: Wed, 15 Nov 2023 11:07:43 -0500 Subject: [PATCH] Added WSL enterprise feature info (#1851) * Added WSL enterprise feature info * Small link fix * Updated networking link --- WSL/enterprise.md | 81 ++++++++++++++++++++++--------- WSL/intune.md | 60 +++++++++++++++++++++++ WSL/networking.md | 53 ++++++++++++++++----- WSL/toc.yml | 10 +++- WSL/wsl-plugins.md | 116 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 285 insertions(+), 35 deletions(-) create mode 100644 WSL/intune.md create mode 100644 WSL/wsl-plugins.md diff --git a/WSL/enterprise.md b/WSL/enterprise.md index a77d4435..926ea0e4 100644 --- a/WSL/enterprise.md +++ b/WSL/enterprise.md @@ -1,18 +1,67 @@ --- title: Set up Windows Subsystem for Linux for your company description: Resources and instructions on how to best use the Windows Subsystem for Linux in an Enterprise environment. -ms.date: 09/27/2021 +ms.date: 10/14/2023 ms.topic: article --- # Enterprise environment: Set up Windows Subsystem for Linux for your company -As an administrator or manager, you may require all developers to use the same approved software. This consistency helps to create a well-defined work environment. The Windows Subsystem for Linux aids in this consistency by allowing you to import and export custom WSL images from one machine to the next. Read the guide below to learn more about: +This guidance is intended for IT Administrators or Security Analysts responsible for setting up enterprise work environments with the goal of distributing software across multiple machines and maintaining a consistent level of security settings across those work machines. +Many companies use [Microsoft Intune]( https://learn.microsoft.com/mem/intune/) and [Microsoft Defender]( https://learn.microsoft.com/microsoft-365/security/defender/) to manage these security settings. However, setting up WSL and accessing Linux distributions in this context requires some specific setup. This guidance provides what you need to know to enable the secure use of Linux with WSL in an enterprise environment. + +* [Recommended setup](#enterprise-set-up-recommendations) + * [Microsoft Defender for Endpoint (MDE) integration](#enable-microsoft-defender-for-endpoint-mde-integration) + * [Configure settings with Intune](#configure-recommended-settings-with-intune) + * [Advanced networking controls](#use-advanced-networking-features-and-controls) * [Creating a custom WSL image](#creating-a-custom-wsl-image) * [Distributing a WSL image](#distributing-your-wsl-image) * [Update and patch Linux distributions and packages](#update-and-patch-linux-distributions-and-packages) -* [Enterprise security and control options](#enterprise-security-and-control-options) +* [Windows file system access](#windows-file-system-access) + +## Enterprise set up recommendations + +There are a variety of ways to set up a secure enterprise environment, but we recommend the following for setting up a secure environment that utilizes WSL. + +### Pre-requisites + +To get started ensure that all enterprise devices have the following minimum versions installed: + +* Windows 10 22H2 or higher, or Windows 11 22H2 or higher + * Advanced networking features are only available on Windows 11 22H2 or higher. +* [WSL version 2.0.9](https://github.com/microsoft/WSL/releases) or higher + - You can check the WSL version by running `wsl --version`. + +### Enable Microsoft Defender for Endpoint (MDE) integration + +[Microsoft Defender for Endpoint](https://learn.microsoft.com/microsoft-365/security/defender-endpoint/microsoft-defender-endpoint) is an enterprise endpoint security platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats. MDE now integrates with WSL as a [WSL plugin](./wsl-plugins.md), which allows security teams to see and continuously monitor for security events in all running WSL distributions with Defender for Endpoint while minimally impacting performance on developer workloads. + +Please visit [the MDE plugin for WSL docs page](https://aka.ms/mdeplugindocs) to learn more on how to get started. + +### Configure recommended settings with Intune + +[Microsoft Intune](https://learn.microsoft.com/mem/intune/fundamentals/what-is-intune) is a cloud-based endpoint management solution. It manages user access to organizational resources and simplifies app and device management across your many devices, including mobile devices, desktop computers, and virtual endpoints. You can use Microsoft Intune to manage devices inside of your organization, which now also includes managing access to WSL and its key security settings. + +Please visit [the WSL Intune docs page](./intune.md) to see how you can get started with enabling these, and the recommended settings. + +### Use advanced networking features and controls + +Starting from Windows 11 22H2 and WSL 2.0.9 or later, Windows firewall rules will automatically apply to WSL. This ensures that the firewall rules set on the Windows host will automatically apply to all WSL distros by default. To customize the firewall settings for WSL, please visit [the Hyper-V firewall docs](https://learn.microsoft.com/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall). + +Additionally, there are user configurable settings that we recommend users enable in Enterprise scenarios by setting [these settings under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-setting-for-wslconfig). + +#### Mirrored mode networking + +`networkingMode=mirrored` enables mirrored mode networking. This new networking mode improves compatibility with complex networking environments, especially VPNs and more, as well as adding support for new networking features unavailable in the default NAT mode like IPv6. + +#### DNS Tunneling + +`dnsTunneling=true` changes how WSL obtains DNS information. This setting improves compatibility in different networking environments, and makes use of virtualization features to obtain DNS information rather than a networking packet. It's recommended to turn this on if experiencing any connectivity issues, and can be especially helpful when using VPNs, advanced firewall settings, and more. + +#### Auto proxy + +`autoProxy=true` enforces WSL to use Windows' HTTP proxy information. We recommend turning this setting on when using a proxy on Windows, as it will make that proxy automatically apply to your WSL distributions. ## Creating a custom WSL image @@ -24,7 +73,7 @@ Once installed, use The Microsoft Store for Business to download and install the ### Exporting your WSL image -Export your custom WSL image by running wsl --export ` `, which will wrap your image in a tar file and make it ready for distribution on to other machines. +Export your custom WSL image by running wsl --export ` `, which will wrap your image in a tar file and make it ready for distribution on to other machines. You can [create custom distributions including CentOS, RedHat and more using the custom distro guide](./use-custom-distro.md). ## Distributing your WSL image @@ -34,26 +83,17 @@ Distribute the WSL image from a share or storage device by running wsl --import Using Linux configuration manager tools is strongly recommended for monitoring and managing Linux user space. There are a host of Linux configuration managers to choose from. Check out this [blog post](http://www.craigloewen.com/blog/2019/12/04/running-puppet-quickly-in-wsl2/) on how to install Puppet in WSL 2. -## Enterprise security and control options - -Currently, WSL offers limited control mechanisms in regard to modifying the user experience in an Enterprise scenario. Enterprise features continue in development however, below are the areas of supported and unsupported features. To request a new feature not covered in this list, file an issue in our [GitHub repo](https://github.com/microsoft/WSL/issues?q=is%3Aissue+is%3Aopen+enterprise). - -### Configuring WSL firewall rules - -Microsoft implements Firewall protocols used by Windows to maintain security and block unauthorized network traffic flowing into or out of a local device. To optimize protection for devices in your network, [configure your Windows Firewall based on best practices](/windows/security/threat-protection/windows-firewall/best-practices-configuring). - -In regard to WSL, if the [local policy merge](/openspecs/windows_protocols/ms-gpfas/2c979624-900a-4b6e-b4ef-09b387cd62ab) firewall policy is set to "No" then WSL networking will not work. (For more information, see [Establish local policy merge and application rules](/windows/security/threat-protection/windows-firewall/best-practices-configuring#establish-local-policy-merge-and-application-rules).) - -To change this configuration, you can add the following to Windows firewall settings: - -- Action allow, direction Inbound, Protocol UDP, LocalPort 53, program: `%Systemroot%\System32\svchost.exe`, service SharedAccess +## Windows file system access -Also see: [WSL has no network connection on my work machine or in an Enterprise environment](./troubleshooting.md#wsl-has-no-network-connection-on-my-work-machine-or-in-an-enterprise-environment). +When a Linux binary inside of WSL accesses a Windows file, it does so with the user permissions of the Windows user that ran `wsl.exe`. So even though a Linux user has root access inside of WSL, they cannot do Windows administrator level operations on Windows if the Windows user does not have those permission. With regards to Windows file and Windows executable access from WSL, running a shell like `bash` has the same security level permissions as running `powershell` from Windows as that user. ### Supported * Sharing an approved image internally using `wsl --import` and `wsl --export` * Creating your own WSL distro for your Enterprise using the [WSL Distro Launcher repo](https://github.com/microsoft/WSL-DistroLauncher) +* Monitor security events inside of WSL distros using Microsoft Defender for Endpoint (MDE) +* Use firewall settings to control networking in WSL (Includes syncing Windows firewall settings to WSL) +* Control access to WSL and its key security settings with Intune or group policy Here's a list of features for which we don't yet have support for, but are investigating. @@ -61,10 +101,7 @@ Here's a list of features for which we don't yet have support for, but are inves Below is a list of commonly asked features that are currently unsupported within WSL. These requests are on our backlog and we are investigating ways to add them. -* Synchronizing the user inside WSL with the Windows user on the host machine * Managing updates and patching of the Linux distributions and packages using Windows tools * Having Windows update also update WSL distro contents * Controlling which distributions users in your Enterprise can access -* Running mandatory services (logging or monitoring) inside of WSL -* Monitoring Linux instances using Windows configuration manager tools such as SCCM or Intune -* McAfee support +* Controlling root access for users diff --git a/WSL/intune.md b/WSL/intune.md new file mode 100644 index 00000000..7da6fed3 --- /dev/null +++ b/WSL/intune.md @@ -0,0 +1,60 @@ +--- +title: Intune settings +description: Available settings in Intune for the Windows Subsystem for Linux (WSL) +ms.date: 10/14/2023 +ms.topic: article +--- + +# Intune settings for WSL + +You can now use management tools like Intune to manage WSL as a Windows component. + +To access these settings please navigate to your Microsoft Intune admin center portal, and then select: `Devices -> Configuration Profiles -> Create -> New Policy -> Windows 10 and later -> Settings catalog`, create a name for the new profile and search for "Windows Subsystem for Linux" to see and add the full list of available settings. + +## Recommended settings + +To maximize security in an enterprise environment, we recommend that you specify these settings: + +| Setting Name | Value | Description | +| --- | --- | --- | +| Allow the Inbox version of the Windows Subsystem for Linux | Disabled | When set to disabled, this policy disables the inbox version (optional component) of the Windows Subsystem For Linux. If this policy is disabled, only the store version of WSL can be used. | +| Allow WSL1 | Disabled | When set to disabled, this policy disables WSL1. When disabled, only WSL2 distributions can be used. | +| Allow the debug shell | Disabled | When set to disabled, this policy disables the debug shell (wsl.exe --debug-shell). This policy only applies to Store WSL. | +| Allow custom kernel configuration | Disabled | When set to disabled, this policy disables custom kernel configuration via .wslconfig (wsl2.kernel). This policy only applies to Store WSL. | +| Allow kernel command line configuration | Disabled | When set to disabled, this policy disables kernel command line configuration via .wslconfig (wsl2.kernelCommandLine). This policy only applies to Store WSL. | +| Allow custom system distribution configuration | Disabled | When set to disabled, this policy disables custom system distribution configuration via .wslconfig (wsl2.systemDistro). This policy only applies to Store WSL. | +| Allow custom networking configuration | Disabled | When set to disabled, this policy disables custom networking configuration via .wslconfig (wsl2.networkingmode). This policy only applies to Store WSL. | +| Allow user setting firewall configuration | Disabled | When set to disabled, this policy disables firewall configuration via .wslconfig (wsl2.firewall). This policy only applies to Store WSL. | +| Allow nested virtualization | Disabled | When set to disabled, this policy disables nested virtualization configuration via .wslconfig (wsl2.nestedVirtualization). This policy only applies to Store WSL. | +| Allow kernel debugging | Disabled | When set to disabled, this policy disables kernel kernel debugging configuration via .wslconfig (wsl2.kernelDebugPort). This policy only applies to Store WSL. | + +## Control access to WSL + +The `AllowWSL`, `AllowInboxWSL`, and `AllowWSL1` settings control user access to WSL. You can configure these settings to enable or disable access to the in-Windows version of WSL, WSL 1 distros, or WSL itself. + +This will allow you to configure WSL to ensure that users are only using the latest version of WSL with Enterprise feature support. + +## Control WSL commands + +`AllowDebugShell` and `AllowDiskMount` control whether users can run the `wsl --debug-shell` and `wsl --mount` commands. You can [learn more about mounting disks in WSL with the mount command here](./wsl2-mount-disk.md). + +## Control access to WSL settings in `.wslconfig` + +The last group of settings that end with `*UserSettingConfigurable` control access to WSL advanced settings in `.wslconfig`. When these are set to disabled then users will only be able to use the default value for that setting, and not able to configure it to custom values. To [learn more about these settings please see the advanced settings doc page](./wsl-config.md#configuration-setting-for-wslconfig). + +## Full list of available settings + +| Setting Name | Description | +| --- | --- | +| Allow the Windows Subsystem For Linux | When set to disabled, this policy disables access to the Windows Subsystem For Linux for all users on the machine. | +| Allow the Inbox version of the Windows Subsystem For Linux | When set to disabled, this policy disables the inbox version (optional component) of the Windows Subsystem For Linux. If this policy is disabled, only the store version of WSL can be used. | +| Allow WSL1 | When set to disabled, this policy disables WSL1. When disabled, only WSL2 distributions can be used. | +| Allow the debug shell | When set to disabled, this policy disables the debug shell (wsl.exe --debug-shell). This policy only applies to Store WSL. | +| Allow passthrough disk mount | When set to disabled, this policy disables passthrough disk mounting in WSL2 (wsl.exe --mount). This policy only applies to Store WSL. | +| Allow custom kernel configuration | When set to disabled, this policy disables custom kernel configuration via .wslconfig (wsl2.kernel). This policy only applies to Store WSL. | +| Allow kernel command line configuration | When set to disabled, this policy disables kernel command line configuration via .wslconfig (wsl2.kernelCommandLine). This policy only applies to Store WSL. | +| Allow custom system distribution configuration | When set to disabled, this policy disables custom system distribution configuration via .wslconfig (wsl2.systemDistro). This policy only applies to Store WSL. | +| Allow custom networking configuration | When set to disabled, this policy disables custom networking configuration via .wslconfig (wsl2.networkingmode). This policy only applies to Store WSL. | +| Allow user setting firewall configuration | When set to disabled, this policy disables firewall configuration via .wslconfig (wsl2.firewall). This policy only applies to Store WSL. | +| Allow nested virtualization | When set to disabled, this policy disables nested virtualization configuration via .wslconfig (wsl2.nestedVirtualization). This policy only applies to Store WSL. | +| Allow kernel debugging | When set to disabled, this policy disables kernel kernel debugging configuration via .wslconfig (wsl2.kernelDebugPort). This policy only applies to Store WSL. | diff --git a/WSL/networking.md b/WSL/networking.md index 481df3e3..8f48ab23 100644 --- a/WSL/networking.md +++ b/WSL/networking.md @@ -8,31 +8,34 @@ ms.topic: article # Accessing network applications with WSL -There are a few considerations to be aware of when working with networking apps, whether you are accessing a Linux networking app from a Windows app or accessing a Windows networking app from a Linux app, you may need to identify the IP address of the virtual machine you are working with, which will be different than the IP address of your local physical machine. +There are a few considerations to be aware of when working with networking apps and WSL. By default WSL uses a [NAT based architecture](#default-networking-mode-nat), and we recommend trying the new [Mirrored networking mode](#mirrored-mode-networking) to get the latest features and improvements. -## Accessing Linux networking apps from Windows (localhost) +## Default networking mode: NAT +By default, WSL uses a NAT (Network address translatiintuon) based networking architecture. Keep the following considerations in mind when working with a NAT-based networking architecture: + +### Accessing Linux networking apps from Windows(localhost) + If you are building a networking app (for example an app running on a NodeJS or SQL server) in your Linux distribution, you can access it from a Windows app (like your Edge or Chrome internet browser) using `localhost` (just like you normally would). -## Accessing Windows networking apps from Linux (host IP) +### Accessing Windows networking apps from Linux (host IP) If you want to access a networking app running on Windows (for example an app running on a NodeJS or SQL server) from your Linux distribution (ie Ubuntu), then you need to use the IP address of your host machine. While this is not a common scenario, you can follow these steps to make it work. -1. Obtain the IP address of your host machine by running this command from your Linux distribution: `cat /etc/resolv.conf` -2. Copy the IP address following the term: `nameserver`. -3. Connect to any Windows server using the copied IP address. +1. Obtain the IP address of your host machine by running this command from your Linux distribution: ` ip route show | grep -i default | awk '{ print $3}' +2. Connect to any Windows server using the copied IP address. The picture below shows an example of this by connecting to a Node.js server running in Windows via curl. ![Connect to NodeJS server in Windows via Curl](media/wsl2-network-l2w.png) -## Connecting via remote IP addresses +### Connecting via remote IP addresses When using remote IP addresses to connect to your applications, they will be treated as connections from the Local Area Network (LAN). This means that you will need to make sure your application can accept LAN connections. For example, you may need to bind your application to `0.0.0.0` instead of `127.0.0.1`. In the example of a Python app using Flask, this can be done with the command: `app.run(host='0.0.0.0')`. Please keep security in mind when making these changes as this will allow connections from your LAN. -## Accessing a WSL 2 distribution from your local area network (LAN) +### Accessing a WSL 2 distribution from your local area network (LAN) When using a WSL 1 distribution, if your computer was set up to be accessed by your LAN, then applications run in WSL could be accessed on your LAN as well. @@ -55,10 +58,38 @@ netsh interface portproxy add v4tov4 listenport=4000 listenaddress=0.0.0.0 conne To obtain the IP address, use: - `wsl hostname -i` for the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address) -- `cat /etc/resolv.conf` for the IP address of the Windows machine as seen from WSL 2 (the WSL 2 VM) +- `ip route show | grep -i default | awk '{ print $3}'` for the IP address of the Windows machine as seen from WSL 2 (the WSL 2 VM) Using `listenaddress=0.0.0.0` will listen on all [IPv4 ports](https://stackoverflow.com/questions/9987409/want-to-know-what-is-ipv4-and-ipv6#:~:text=The%20basic%20difference%20is%20the,whereas%20IPv6%20has%20128%20bits.). -## IPv6 access +## Mirrored mode networking + +You can [set `networkingMode=mirrored` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-setting-for-wslconfig) to enable mirrored mode networking. Enabling this changes WSL to an entirely new networking architecture which has the goal of 'mirroring' the network interfaces that you have on Windows into Linux, to add new networking features and improve compatibility. + +Here are the current benefits to enabling this mode: + +- IPv6 support +- Connect to Windows servers from within Linux using the localhost address `127.0.0.1` +- Connect to WSL directly from your local area network (LAN) + - > **__NOTE:__** Please run the following command in PowerShell window with admin privileges to set a [Hyper-V firewall](https://learn.microsoft.com/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) setting to allow inbound connections: `Set-NetFirewallHyperVVMSetting -Name ‘{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}’ -DefaultInboundConnection Allow` or `New-NetFirewallHyperVRule -Name MyWebServer -DisplayName “My Web Server” -Direction Inbound -VMCreatorId “{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}” -Protocol TCP -LocalPorts 80` +- Improved networking compatibility for VPNs +- Multicast support + +This new mode addresses many of the networking issues that are seen with NAT that you can see above in this docs page. There are some initial known issues, so as you explore this mode please file feedback on any bugs at the [WSL GitHub repo](http://github.com/microsoft/wsl). + +## DNS Tunneling + +Setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-setting-for-wslconfig) has WSL use a virtulization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups. + +## Auto Proxy + +Setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-setting-for-wslconfig) enforces WSL to use Windows' HTTP proxy information. If you have a proxy already set up in Windows, enabling this feature will make that proxy be set automatically in WSL as well. + +## WSL and firewall + +On machines running Windows 11 22H2 and higher, with WSL 2.0.9 and higher, the Hyper-V firewall feature will be turned on by default. This will ensure that: + +- Regular [Windows firewall rules and settings in](https://learn.microsoft.com/windows/security/operating-system-security/network-security/windows-firewall/windows-firewall-with-advanced-security) will automatically apply to WSL +- [Hyper-V firewall](https://learn.microsoft.com/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) rules and settings can be set to apply specifically to WSL -WSL 2 distributions currently cannot reach IPv6-only addresses. We are working on adding this feature. +Please see the [Hyper-V firewall docs page](https://learn.microsoft.com/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to learn more about applying these rules and settings both locally and via online tools like Intune. diff --git a/WSL/toc.yml b/WSL/toc.yml index 9ef83b40..74fe5363 100644 --- a/WSL/toc.yml +++ b/WSL/toc.yml @@ -52,8 +52,6 @@ href: systemd.md - name: How-to items: - - name: Set up WSL for your company - href: enterprise.md - name: Import any Linux distribution href: use-custom-distro.md - name: Build a custom distribution @@ -66,6 +64,14 @@ href: case-sensitivity.md - name: Manage available disk space href: disk-space.md + - name: Create WSL plugins + href: wsl-plugins.md +- name: Enterprise security + items: + - name: Set up WSL for your company + href: enterprise.md + - name: Intune settings for WSL + href: intune.md - name: Frequently Asked Questions href: faq.yml - name: Troubleshooting diff --git a/WSL/wsl-plugins.md b/WSL/wsl-plugins.md new file mode 100644 index 00000000..56085ed6 --- /dev/null +++ b/WSL/wsl-plugins.md @@ -0,0 +1,116 @@ +--- +title: WSL Plugins +description: Learn how Windows applications can use WSL plugins to integrate their workflow inside of WSL +ms.date: 10/14/2023 +ms.topic: article +--- + +# WSL Plugins + +Windows applications can now create and interact with Linux processes running inside of the Windows Subsystem for Linux (WSL) with WSL plugins. This article gives an overview of how they work, and how to get started using them. + +## Understanding Plugin functionality + +WSL plugins provide these core functionalities: + +- Allows applications to specify a Windows executable that starts when the WSL virtual machine is started +- The Windows executable can create Linux processes inside of WSL, and it can communicate directly to them using a virtualized socket + +Using these, Windows applications can build ontop of WSL experiences and provide additional functionality related to the Windows Subsystem for Linux. + +## Installing a Plugin + +As a WSL plugin creator, you can install your plugin on a machine by setting a registry key to point to your plugin’s DLL file. + +And as a WSL user, any application that you use will automatically install WSL plugins as part of their normal install process. + +## Creating your own Plugin + +To start a plugin project you will need to build a Win32 dll. The simplest way to get set up with this is to try our WSL plugin sample project. You can do this by cloning the [WSL plugin sample repository](https://github.com/microsoft/wsl-plugin-sample) to a local folder with `git clone` and open it in Visual Studio. + +When you open the project please navigate to the `dllmain.cpp` file (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) and you will see the list of functions available to WSL plugins. + +You can then press the “Build” tab and build your project, which will output a DLL ready you to use, likely under `wsl-plugin-sample\x64\Debug\WSLPluginSample.dll`. + +### Testing your Plugin + +WSL plugins will only run if they are [digitally signed]( https://learn.microsoft.com/windows-hardware/drivers/install/digital-signatures). To test this you will need to enable test signing on your machine. + +#### Enabling test signing and creating a test certification + +Open an elevated PowerShell Window and [enable test signing]( https://learn.microsoft.com/windows-hardware/drivers/install/the-testsigning-boot-configuration-option#enable-or-disable-use-of-test-signed-code) by running this command: +```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 +``` + +Once test signing is enabled (A reboot may required), in an elevated Powershell command prompt that is at the directory of your WSLPluginSample.dll file created above we will create a WSL test certificate: + +```powershell +# 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 +``` + +Last import the certificate to the Trusted Root Certification Authority: + +```powershell +certutil -addstore "Root" ".\$certname.cer" +``` + +See the [how to create a self signed certificate]( https://learn.microsoft.com/entra/identity-platform/howto-create-self-signed-certificate) docs page for more info. + +#### Install the plugin + +In the same elevated PowerShell window, run the command below to install the plugin, and be sure to change the path to the plugin DLL to your existing path: + +```powershell +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 +``` + +To use the plugin, restart the wsl service via: + +```powershell +sc.exe stop wslservice +wsl.exe echo “test” +``` + +Your plugin should now be loaded. See the [Troubleshooting and additional information](#troubleshooting-and-additional-information) section for more information if the plugin failed to load. + +And then when you are finished, you can run this command to remove the plugin (Please keep in mind you will need to restart the WSL service for it to take effect): + +```powershell +Reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin +``` + +## Troubleshooting and additional information + + +Common error codes: + +- Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> The plugin DLL could not be loaded. Check that the plugin registration path is correct +- Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> The plugin DLL is not signed, or its signature is not trusted by the computer + - Please [enable test signing]( https://learn.microsoft.com/windows-hardware/drivers/install/the-testsigning-boot-configuration-option#enable-or-disable-use-of-test-signed-code) and see [the signing section above on how to set up a test certificate](#enabling-test-signing-and-creating-a-test-certification). +- Wsl/Service/CreateInstance/CreateVm/Plugin/* -> The plugin DLL returned an error in WSLPLUGINAPI_ENTRYPOINTV1 or OnVmStarted() +- Wsl/Service/CreateInstance/Plugin/* -> The plugin DLL returned an error in OnDistributionStarted() + +## Plugins Linux user space + +Linux processes created via ExecuteBinary() will run in the root namespace of the WSL2 Virtual Machine. This namespace is not associated to any distribution and has a very minimal Mariner based root file system. + +That file system is a writable tmpfs, meaning that all changes made to it will be dropped when the WSL2 Virtual Machine is shut down. + +You can inspect the content of the root namespace by running `wsl --debug-shell` while WSL is running. + +### Additional considerations + +- All WSL plugin hooks are synchronous, meaning that WSL will wait for the plugin hooks to be completed before continuing. +- Any error returned by a plugin is considered fatal by WSL (meaning that the user’s distribution will not start) +- The plugin code runs in the same address space as the WSL service. Any crash in a plugin will crash the entire WSL service, potentially causing data loss