From 5e6050de2098596e16cfaedaf6480f87b358b57a Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Wed, 15 Nov 2023 13:08:35 -0800 Subject: [PATCH] Resolve issues Nov 23 (#1848) * Reorganize, reword config doc * fix hostname command * Clarify to resolve https://github.com/MicrosoftDocs/WSL/issues/1722 * Add systemd and ipv6 to comparison table * Update prereqs for docker * Fix based on issue 1793 * Add more context to address issue 1795 * Resolve issue 1798 * Add note about hostname flag IP differences * Add note about terminate command * Fix hardcoded links * Fix links * Editorial fixes * Remove repeated anchor links * Fix firewall config link --- WSL/compare-versions.md | 6 ++- WSL/disk-space.md | 4 +- WSL/enterprise.md | 29 ++++-------- WSL/intune.md | 6 +-- WSL/networking.md | 34 +++++++++----- WSL/troubleshooting.md | 6 +-- WSL/tutorials/wsl-containers.md | 11 ++++- WSL/wsl-config.md | 82 ++++++++++++++++----------------- 8 files changed, 95 insertions(+), 83 deletions(-) diff --git a/WSL/compare-versions.md b/WSL/compare-versions.md index d175cc7d..a13bca1d 100644 --- a/WSL/compare-versions.md +++ b/WSL/compare-versions.md @@ -1,7 +1,7 @@ --- title: Comparing WSL Versions description: WSL 2 provides the benefits of WSL 1, but uses an actual Linux kernel, rather than a translation layer like WSL 1, resulting in faster performance. -ms.date: 10/04/2022 +ms.date: 11/10/2023 ms.topic: conceptual ms.custom: seo-windows-dev --- @@ -26,11 +26,15 @@ Feature | WSL 1 | WSL 2 Full Linux Kernel| ❌ |✅ Full system call compatibility| ❌ | ✅ Performance across OS file systems| ✅ | ❌ + systemd support| ❌ | ✅ + IPv6 support| ❌ | ✅ As you can tell from the comparison table above, the WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems, which can be addressed by storing your project files on the same operating system as the tools you are running to work on the project. WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. Check your Windows version by selecting the **Windows logo key + R**, type **winver**, select **OK**. (Or enter the `ver` command in Windows Command Prompt). You may need to [update to the latest Windows version](ms-settings:windowsupdate). For builds lower than 14393, WSL is not supported at all. +For more info on the latest WSL 2 updates, see the [Windows Command Line blog](https://devblogs.microsoft.com/commandline/), including [Systemd support is now available in WSL](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/) and [WSL September 2023 update](https://devblogs.microsoft.com/commandline/windows-subsystem-for-linux-september-2023-update/) for more info on IPv6 support. + > [!NOTE] > WSL 2 will work with [VMware 15.5.5+](https://blogs.vmware.com/workstation/2020/05/vmware-workstation-now-supports-hyper-v-mode.html) and [VirtualBox 6+](https://www.virtualbox.org/wiki/Changelog-6.0). Learn more in our [FAQs.](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-) diff --git a/WSL/disk-space.md b/WSL/disk-space.md index 81d80f49..c7cb3909 100644 --- a/WSL/disk-space.md +++ b/WSL/disk-space.md @@ -1,7 +1,7 @@ --- title: How to manage WSL disk space description: Learn how to check the amount of disk space available, expand the size of the Virtual Hard Disk (VHD), repair a VHD mounting or read-only error, and locate the .vhdx file and disk path for Linux distributions installed with WSL 2. -ms.date: 01/12/2023 +ms.date: 11/10/2023 ms.topic: article --- @@ -69,7 +69,7 @@ To expand the VHD size for a Linux distribution beyond the **default 1TB maximum detail vdisk ``` -6. You will need to convert the **Virtual size** to megabytes. For example, if **Virtual size: 512 GB**, convert this to **512000**. The new value you enter must be greater than this original value. For example, to double the virtual size of 512 GB to 1024 GB, you would convert to MB and enter the value: **1024000**. Be careful not to enter a value higher than you actually want as the process of reducing a virtual disk size is much more complicated. +6. You will need to convert the **Virtual size** to megabytes. For example, if **Virtual size: 512 GB**, this is equal to **512000 MB**. The new value you enter must be greater than this original value. To double the virtual size of 512 GB to 1024 GB, you would enter the value in MB as: **1024000**. Be careful not to enter a value higher than you actually want as the process of reducing a virtual disk size is much more complicated. 7. Enter the value for the new maximum size you want to allocate to this Linux distribution using the Windows Command Prompt `DISKPART>` prompt: diff --git a/WSL/enterprise.md b/WSL/enterprise.md index 926ea0e4..af1ec37f 100644 --- a/WSL/enterprise.md +++ b/WSL/enterprise.md @@ -1,7 +1,7 @@ --- 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: 10/14/2023 +ms.date: 11/15/2023 ms.topic: article --- @@ -9,18 +9,9 @@ ms.topic: article 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. +Many companies use [Microsoft Intune](/mem/intune/) and [Microsoft Defender](/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) -* [Windows file system access](#windows-file-system-access) - -## Enterprise set up recommendations +## Recommended Enterprise set up with Microsoft Defender for Endpoint, Intune, and Advanced Networking Controls 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. @@ -35,21 +26,21 @@ To get started ensure that all enterprise devices have the following minimum ver ### 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. +[Microsoft Defender for Endpoint](/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. +See [Microsoft Defender for Endpoint plug-in for WSL](/microsoft-365/security/defender-endpoint/mde-plugin-wsl) to learn more about 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. +[Microsoft Intune](/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. +See [Intune settings for WSL](./intune.md) for guidance on using InTune to manage WSL as a Windows component 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). +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 distributions by default. For guidance on customizing the firewall settings for WSL, visit [Configure Hyper-V firewall](/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). +Additionally, we recommend configuring [settings under `[wsl2]` in the `.wslconfig` file](/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to suite your specific Enterprise scenario. #### Mirrored mode networking @@ -81,7 +72,7 @@ Distribute the WSL image from a share or storage device by running wsl --import ## Update and patch Linux distributions and packages -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. +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. See this blog post on [Running Puppet quickly in WSL 2](http://www.craigloewen.com/blog/2019/12/04/running-puppet-quickly-in-wsl2/). ## Windows file system access diff --git a/WSL/intune.md b/WSL/intune.md index 7da6fed3..6e79a78f 100644 --- a/WSL/intune.md +++ b/WSL/intune.md @@ -1,7 +1,7 @@ --- title: Intune settings description: Available settings in Intune for the Windows Subsystem for Linux (WSL) -ms.date: 10/14/2023 +ms.date: 11/15/2023 ms.topic: article --- @@ -36,11 +36,11 @@ This will allow you to configure WSL to ensure that users are only using the lat ## 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). +`AllowDebugShell` and `AllowDiskMount` control whether users can run the `wsl --debug-shell` and `wsl --mount` commands. Learn more about how to [Mount a disk in WSL 2](./wsl2-mount-disk.md) using the `wsl --mount` command. ## 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). +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. Learn more about [Configuration setting for .wslconfig](./wsl-config.md#configuration-setting-for-wslconfig), including a list of settings that can be configured globally for all Linux distributions running with WSL 2. ## Full list of available settings diff --git a/WSL/networking.md b/WSL/networking.md index 8f48ab23..15f17cb7 100644 --- a/WSL/networking.md +++ b/WSL/networking.md @@ -2,7 +2,7 @@ title: Accessing network applications with WSL description: Learn about the considerations for accessing network applications when using Windows Subsystem for Linux (WSL). keywords: wsl, Linux, Windows, networking, ip address, ip addr, host IP, server, network, localhost, local area network, lan, ipv6, remote -ms.date: 09/27/2021 +ms.date: 11/15/2023 ms.topic: article --- @@ -12,9 +12,9 @@ There are a few considerations to be aware of when working with networking apps ## 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: +By default, WSL uses a NAT (Network Address Translation) based architecture for networking. Keep the following considerations in mind when working with a NAT-based networking architecture: -### Accessing Linux networking apps from Windows(localhost) +### 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). @@ -33,7 +33,7 @@ The picture below shows an example of this by connecting to a Node.js server run 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. +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')`. 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) @@ -47,7 +47,7 @@ Here's an example of using the [Netsh interface portproxy](/windows-server/netwo netsh interface portproxy add v4tov4 listenport= listenaddress=0.0.0.0 connectport= connectaddress=(wsl hostname -I) ``` -In this example, you will need to update `` to a port number, for example `listenport=4000`. `listenaddress=0.0.0.0` means that incoming requests will be accepted from ANY IP address. The Listen Address specifies the IPv4 address for which to listen and can be changed to values that include: IP address, computer NetBIOS name, or computer DNS name. If an address isn't specified, the default is the local computer. You need to update the `` value to a port number where you want WSL to connect, for example `connectport=4000`. Lastly, the `connectaddress` value needs to be the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address), which can be found by entering the command: `wsl.exe hostname -i`. +In this example, you will need to update `` to a port number, for example `listenport=4000`. `listenaddress=0.0.0.0` means that incoming requests will be accepted from ANY IP address. The Listen Address specifies the IPv4 address for which to listen and can be changed to values that include: IP address, computer NetBIOS name, or computer DNS name. If an address isn't specified, the default is the local computer. You need to update the `` value to a port number where you want WSL to connect, for example `connectport=4000`. Lastly, the `connectaddress` value needs to be the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address), which can be found by entering the command: `wsl.exe hostname -I`. So this command may look something like: @@ -57,6 +57,16 @@ 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) + +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.). + +> [!NOTE] +> Using a lowercase "i" with the hostname command will generate a different result than using an uppercase "I". `wsl hostname -i` is your local machine (127.0.1.1 is a placeholder diagnostic address), whereas `wsl hostname -I` will return your local machine's IP address as seen by other machines and should be used to identify the `connectaddress` of your Linux distribution running via WSL 2. + +## IPv6 access + - `wsl hostname -i` for the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address) - `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) @@ -70,12 +80,14 @@ 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 +- Connect to WSL directly from your local area network (LAN) -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). +> [!NOTE] +> Run the following command in PowerShell window with admin privileges to [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) settings 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`. + +This new mode addresses networking issues seen with using a NAT (Network Address Translation) based architecture. Find known issues or file feedback on any bugs identified in the [WSL product repo on GitHub](https://github.com/microsoft/wsl). ## DNS Tunneling @@ -89,7 +101,5 @@ Setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config. 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 - -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. +- See [Windows Defender Firewall with Advanced Security](/windows/security/operating-system-security/network-security/windows-firewall/windows-firewall-with-advanced-security) to learn more about Windows security features that will automatically apply to WSL. +- See [Configure Hyper-V firewall](/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/troubleshooting.md b/WSL/troubleshooting.md index b36dc3d9..f5279b1f 100644 --- a/WSL/troubleshooting.md +++ b/WSL/troubleshooting.md @@ -1,7 +1,7 @@ --- title: Troubleshooting Windows Subsystem for Linux description: Provides detailed information about common errors and issues people run into while running Linux on the Windows Subsystem for Linux. -ms.date: 11/09/2023 +ms.date: 11/15/2023 ms.topic: article --- @@ -168,7 +168,7 @@ Please enable the Virtual Machine Platform Windows feature and ensure virtualiza 1. Check the [Hyper-V system requirements](/windows-server/virtualization/hyper-v/system-requirements-for-hyper-v-on-windows#:~:text=on%20Windows%20Server.-,General%20requirements,the%20processor%20must%20have%20SLAT.) -2. If your machine is a VM, please enable [nested virtualization](./faq.yml#can-i-run-wsl-2-in-a-virtual-machine-) manually. Launch powershell with admin, and run: +2. If your machine is a VM, enable [nested virtualization](./faq.yml#can-i-run-wsl-2-in-a-virtual-machine-) manually. Launch powershell with admin, and run the following command, replacing `` with the name of the virtual machine on your host system (you can find the name in your Hyper-V Manager): ```powershell Set-VMProcessor -VMName -ExposeVirtualizationExtensions $true @@ -211,7 +211,7 @@ You can confirm local rule merging's setting by following these steps: 5. Select "Customize" under the "Settings" section 6. Check in the "Customize Settings for the Public Profile" window that opens to see if "Rule Merging" is set to "No". This will block access to WSL. -You can find instructions on how to change this Firewall setting in [Enterprise environment: Set up WSL for your company](./enterprise.md#configuring-wsl-firewall-rules). +You can find instructions on how to change this Firewall setting in [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall). ### WSL has no network connectivity once connected to a VPN diff --git a/WSL/tutorials/wsl-containers.md b/WSL/tutorials/wsl-containers.md index d825d84e..ffeba4f6 100644 --- a/WSL/tutorials/wsl-containers.md +++ b/WSL/tutorials/wsl-containers.md @@ -27,13 +27,22 @@ To learn more, check out [Introduction to Docker containers](/training/modules/i ## Prerequisites -- Ensure your machine is running Windows 10, [updated to version 2004](ms-settings:windowsupdate), **Build 18362** or later. +- WSL version 1.1.3.0 or later. +- Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher. +- Windows 10 64-bit (Recommended): Home or Pro 22H2 (build 19045) or higher, or Enterprise or Education 22H2 (build 19045) or higher. (Minimum): Home or Pro 21H2 (build 19044) or higher, or Enterprise or Education 21H2 (build 19044) or higher. [Update Windows](ms-settings:windowsupdate) +- 64-bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation). +- 4GB system RAM. +- Enable hardware virtualization in BIOS. - [Install WSL and set up a user name and password for your Linux distribution running in WSL 2](../install.md). - [Install Visual Studio Code](https://code.visualstudio.com/download) *(optional)*. This will provide the best experience, including the ability to code and debug inside a remote Docker container and connected to your Linux distribution. - [Install Windows Terminal](/windows/terminal/get-started) *(optional)*. This will provide the best experience, including the ability to customize and open multiple terminals in the same interface (including Ubuntu, Debian, PowerShell, Azure CLI, or whatever you prefer to use). - [Sign up for a Docker ID at Docker Hub](https://hub.docker.com/signup) *(optional)*. - See the [Docker Desktop license agreement](https://docs.docker.com/subscription/#docker-desktop-license-agreement) for updates on the terms of use. +For more information, see the [Docker docs System requirements to Install Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/). + +To learn how to install Docker on Windows Server, see [Get started: Prep Windows for containers](/virtualization/windowscontainers/quick-start/set-up-environment). + > [!NOTE] > WSL can run distributions in both WSL version 1 or WSL 2 mode. You can check this by opening PowerShell and entering: `wsl -l -v`. Ensure that the your distribution is set to use WSL 2 by entering: `wsl --set-version 2`. Replace `` with the distro name (e.g. Ubuntu 18.04). > diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index 2c0c00c6..5d670eec 100644 --- a/WSL/wsl-config.md +++ b/WSL/wsl-config.md @@ -1,7 +1,7 @@ --- title: Advanced settings configuration in WSL description: A guide to the wsl.conf and .wslconfig files used for configuring settings when running multiple Linux distributions on Windows Subsystem for Linux. -ms.date: 11/09/2023 +ms.date: 11/10/2023 ms.topic: article ms.custom: seo-windows-dev adobe-target: true @@ -15,43 +15,34 @@ The [wsl.conf](#wslconf) and [.wslconfig](#wslconfig) files are used to configur You can configure the settings for your installed Linux distributions that will automatically be applied every time you launch WSL in two ways, by using: -- **[.wslconfig](#wslconfig)** to configure settings **globally** across all installed distributions running on WSL 2. -- **[wsl.conf](#wslconf)** to configure settings **per-distribution** for Linux distros running on WSL 1 or WSL 2. +- **[.wslconfig](#wslconfig)** to configure **global settings** across all installed distributions running on WSL 2. +- **[wsl.conf](#wslconf)** to configure **local settings** per-distribution for each Linux distribution running on WSL 1 or WSL 2. -Both file types are used for configuring WSL settings, but the location where the file is stored, the scope of the configuration, and the version of WSL running your distribution all impact which file type to choose. +Both file types are used for configuring WSL settings, but the location where the file is stored, the scope of the configuration, the type of options that can be configured, and the version of WSL running your distribution all impact which file type to choose. -The version of WSL that you are running will impact the configuration settings. WSL 2 runs as a lightweight virtual machine (VM), so uses virtualization settings that allow you to control the amount of memory or processors used (which may be familiar if you use Hyper-V or VirtualBox). +WSL 1 and WSL 2 run with different architecture and will impact the configuration settings. WSL 2 runs as a lightweight virtual machine (VM), so uses virtualization settings that allow you to control the amount of memory or processors used (which may be familiar if you use Hyper-V or VirtualBox). [Check which version of WSL you are running.](./install.md#check-which-version-of-wsl-you-are-running) + +## The 8 second rule for configuration changes + +You must wait until the subsystem running your Linux distribution completely stops running and restarts for configuration setting updates to appear. This typically takes about 8 seconds after closing ALL instances of the distribution shell. + +If you launch a distribution (e.g. Ubuntu), modify the configuration file, close the distribution, and then re-launch it, you might assume that your configuration changes have immediately gone into effect. This is not currently the case as the subsystem could still be running. You must wait for the subsystem to stop before relaunching in order to give enough time for your changes to be picked up. You can check to see whether your Linux distribution (shell) is still running after closing it by using PowerShell with the command: `wsl --list --running`. If no distributions are running, you will receive the response: "There are no running distributions." You can now restart the distribution to see your configuration updates applied. + +The command `wsl --shutdown` is a fast path to restarting WSL 2 distributions, but it will shut down all running distributions, so use wisely. You can also use `wsl --terminate ` to terminate a a specific distribution that's running instantly. ## wsl.conf +Configure **local settings** with **wsl.conf** per-distribution for each Linux distribution running on WSL 1 or WSL 2. + - Stored in the `/etc` directory of the distribution as a unix file. - Used to configure settings on a per-distribution basis. Settings configured in this file will only be applied to the specific Linux distribution that contains the directory where this file is stored. - Can be used for distributions run by either version, WSL 1 or WSL 2. - To get to the `/etc` directory for an installed distribution, use the distribution's command line with `cd /` to access the root directory, then `ls` to list files or `explorer.exe .` to view in Windows File Explorer. The directory path should look something like: `/etc/wsl.conf`. -## .wslconfig - -- Stored in your `%UserProfile%` directory. -- Used to configure settings globally across all installed Linux distributions running as the WSL 2 version. -- Can be used **only for distributions run by WSL 2**. Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine. -- To get to your `%UserProfile%` directory, in PowerShell, use `cd ~` to access your home directory (which is typically your user profile, `C:\Users\`) or you can open Windows File Explorer and enter `%UserProfile%` in the address bar. The directory path should look something like: `C:\Users\\.wslconfig`. - -WSL will detect the existence of these files, read the contents, and automatically apply the configuration settings every time you launch WSL. If the file is missing or malformed (improper markup formatting), WSL will continue to launch as normal without the configuration settings applied. - -[Check which version of WSL you are running.](./install.md#check-which-version-of-wsl-you-are-running) - > [!NOTE] > Adjusting per-distribution settings with the wsl.conf file is only available in Windows Build 17093 and later. -### The 8 second rule - -You must wait until the subsystem running your Linux distribution completely stops running and restarts for configuration setting updates to appear. This typically takes about 8 seconds after closing ALL instances of the distribution shell. - -If you launch a distribution (e.g. Ubuntu), modify the configuration file, close the distribution, and then re-launch it, you might assume that your configuration changes have immediately gone into effect. This is not currently the case as the subsystem could still be running. You must wait for the subsystem to stop before relaunching in order to give enough time for your changes to be picked up. You can check to see whether your Linux distribution (shell) is still running after closing it by using PowerShell with the command: `wsl --list --running`. If no distributions are running, you will receive the response: "There are no running distributions." You can now restart the distribution to see your configuration updates applied. - -The command `wsl --shutdown` is a fast path to restarting WSL 2 distributions, but it will shut down all running distributions, so use wisely. - -## Configuration settings for wsl.conf +### Configuration settings for wsl.conf The wsl.conf file configures settings on a per-distribution basis. *(For global configuration of WSL 2 distributions see [.wslconfig](#wslconfig)).* @@ -72,7 +63,7 @@ You will then need to close your WSL distribution using `wsl.exe --shutdown` fro ### Automount settings -Section label: `[automount]` +wsl.conf section label: `[automount]` | key | value | default | notes | |:-----------|:---------|:--------|:------| @@ -110,7 +101,7 @@ DrvFs is a filesystem plugin to WSL that was designed to support interop between ### Network settings -Section label: `[network]` +wsl.conf section label: `[network]` | key | value | default | notes| |:----|:----|:----|:----| @@ -120,7 +111,7 @@ Section label: `[network]` ### Interop settings -Section label: `[interop]` +wsl.conf section label: `[interop]` These options are available in Insider Build 17713 and later. @@ -131,7 +122,7 @@ These options are available in Insider Build 17713 and later. ### User settings -Section label: `[user]` +wsl.conf section label: `[user]` These options are available in Build 18980 and later. @@ -143,16 +134,12 @@ These options are available in Build 18980 and later. The Boot setting is only available on Windows 11 and Server 2022. -Section label: `[boot]` +wsl.conf section label: `[boot]` | key | value | default | notes| |:----|:----|:----|:----| | command | string | "" | A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: `service docker start`.| - - ### Example wsl.conf file The `wsl.conf` sample file below demonstrates some of the configuration options available. In this example, the distribution is Ubuntu-20.04 and the file path is `\\wsl.localhost\Ubuntu-20.04\etc\wsl.conf`. @@ -193,20 +180,31 @@ default = DemoUser command = service docker start ``` -## Configuration setting for .wslconfig +## .wslconfig + +Configure **global settings** with **.wslconfig** across all installed distributions running on WSL. + +- The .wslconfig file does not exist by default. It must be created and stored in your `%UserProfile%` directory to apply these configuration settings. +- Used to configure settings globally across all installed Linux distributions running as the WSL 2 version. +- Can be used **only for distributions run by WSL 2**. Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine. +- To get to your `%UserProfile%` directory, in PowerShell, use `cd ~` to access your home directory (which is typically your user profile, `C:\Users\`) or you can open Windows File Explorer and enter `%UserProfile%` in the address bar. The directory path should look something like: `C:\Users\\.wslconfig`. + +WSL will detect the existence of these files, read the contents, and automatically apply the configuration settings every time you launch WSL. If the file is missing or malformed (improper markup formatting), WSL will continue to launch as normal without the configuration settings applied. + +### Configuration settings for .wslconfig The .wslconfig file configures settings globally for all Linux distributions running with WSL 2. *(For per-distribution configuration see [wsl.conf](#wslconf)).* See [.wslconfig](#wslconfig) for info on where to store the .wslconfig file. > [!NOTE] -> Global configuration options with `.wslconfig` are only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to run `wsl --shutdown` to shut down the WSL 2 VM and then restart your WSL instance for these changes to take effect. +> Configuring global settings with `.wslconfig` are only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to run `wsl --shutdown` to shut down the WSL 2 VM and then restart your WSL instance for these changes to take effect. This file can contain the following options that affect the VM that powers any WSL 2 distribution: ### Main WSL settings -Section label: `[wsl2]` +.wslconfig section label: `[wsl2]` | key | value | default | notes| |:----|:----|:----|:----| @@ -226,9 +224,9 @@ Section label: `[wsl2]` ### Experimental settings -These settings are opt-in previews of experimental features that we aim to make default in the future. +These settings are opt-in previews of experimental features that we aim to make default in the future. -Section label: `[experimental]` +.wslconfig section label: `[experimental]` | Setting name | Value | Default | Notes | |:----|:----|:----|:----| @@ -243,7 +241,7 @@ Section label: `[experimental]` This group of settings configures aspects of the experimental settings above. -Section label: `[experimental]` +.wslconfig section label: `[experimental]` | Setting name | Value | Default | Notes | |:----|:----|:----|:----| @@ -259,7 +257,7 @@ Entries with the `size` value must be a size followed by a unit, for example, `8 Entries with an * after the value type are only available on Windows 11. -Entries with an ** after the value type are only available on the [Windows Insiders Program](https://www.microsoft.com/windowsinsider/). +Entries with an ** after the value type require [Windows version 22H2](https://blogs.windows.com/windows-insider/2023/09/14/releasing-windows-11-build-22621-2359-to-the-release-preview-channel/) or higher. See the Windows Command Line Blog to learn more about [Experimental features included in the WSL September 2023 update](https://devblogs.microsoft.com/commandline/windows-subsystem-for-linux-september-2023-update/) and the [2.0.0 WSL pre-release](https://github.com/microsoft/WSL/releases/tag/2.0.0). @@ -292,7 +290,7 @@ swapfile=C:\\temp\\wsl-swap.vhdx # Disable page reporting so WSL retains all allocated memory claimed from Windows and releases none back when free pageReporting=false -# Turn off default connection to bind WSL 2 localhost to Windows localhost +# Turn on default connection to bind WSL 2 localhost to Windows localhost localhostforwarding=true # Disables nested virtualization