From efd3429d188499e970b3eecccb622c729e1bd66a Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 28 Nov 2023 15:21:29 -0800 Subject: [PATCH 1/3] Issue resolutions from Nov23 (#1857) * 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 * Added wsl 2 note to import vhd flag * Add warning about switching between architectures * Remove issue link replace with FAQ link * Add stacko tip re virtualbox * Add Alma Linux to list * Update USB support for Win10 Resolves https://github.com/MicrosoftDocs/WSL/issues/1675 * Add note about VM architecture for WSL 2 Resolves https://github.com/MicrosoftDocs/WSL/issues/1573 * Update WSL 2 explainer * Add PS command Resolves https://github.com/MicrosoftDocs/WSL/issues/1656 * Update descriptions and add link to Linux resources * Fixes typo in set default command (#1856) * Fix broken link to GH learning lab * typo fix * Fix the command parameter of configuring Hyper-V firewall (#1858) --------- Co-authored-by: Jacob Wortmann Co-authored-by: Zhaoqiu Sheng <51221150+zhaoqiu-china@users.noreply.github.com> --- WSL/about.md | 30 +++++++++++++++--------------- WSL/basic-commands.md | 7 +++++-- WSL/compare-versions.md | 6 +++--- WSL/connect-usb.md | 4 ++-- WSL/faq.yml | 4 ++-- WSL/install-manual.md | 3 ++- WSL/install.md | 4 ++-- WSL/networking.md | 2 +- WSL/setup/environment.md | 4 ++-- WSL/tutorials/wsl-git.md | 2 +- 10 files changed, 35 insertions(+), 31 deletions(-) diff --git a/WSL/about.md b/WSL/about.md index f2b328cf..1df9de93 100644 --- a/WSL/about.md +++ b/WSL/about.md @@ -1,20 +1,18 @@ --- title: What is Windows Subsystem for Linux -description: Learn about the Windows Subsystem for Linux, including the different versions and ways you can use them. -keywords: BashOnWindows, bash, wsl, windows, windowssubsystem, gnu, linux -ms.date: 09/27/2021 +description: Learn about the Windows Subsystem for Linux, including the different versions and ways you can use them. Microsoft Loves Linux. +ms.date: 11/20/2023 ms.topic: article -ms.assetid: 3cefe0db-7616-4848-a2b6-9296746a178b --- # What is the Windows Subsystem for Linux? -The Windows Subsystem for Linux lets developers run a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup. +Windows Subsystem for Linux (WSL) is a feature of Windows that allows you to run a Linux environment on your Windows machine, without the need for a separate virtual machine or dual booting. WSL is designed to provide a seamless and productive experience for developers who want to use both Windows and Linux at the same time. -You can: - -- Choose your favorite GNU/Linux distributions [from the Microsoft Store](https://aka.ms/wslstore). -- Run common command-line tools such as `grep`, `sed`, `awk`, or other ELF-64 binaries. +- Use WSL to install and run various Linux distributions, such as Ubuntu, Debian, Kali, and more. [Install Linux distributions](./install.md) and receive automatic updates from the [Microsoft Store](./compare-versions.md#wsl-in-the-microsoft-store), [import Linux distributions not available in the Microsoft Store](./use-custom-distro.md), or [build your own customer Linux distribution](./build-custom-distro.md). +- Store files in an isolated Linux file system, specific to the installed distribution. +- Run command-line tools, such as BASH. +- Run common BASH command-line tools such as `grep`, `sed`, `awk`, or other ELF-64 binaries. - Run Bash scripts and GNU/Linux command-line applications including: - Tools: vim, emacs, tmux - Languages: [NodeJS](/windows/nodejs/setup-on-wsl2), JavaScript, [Python](/windows/python/web-frameworks), Ruby, C/C++, C# & F#, Rust, Go, etc. @@ -23,7 +21,7 @@ You can: - Invoke Windows applications using a Unix-like command-line shell. - Invoke GNU/Linux applications on Windows. - [Run GNU/Linux graphical applications](./tutorials/gui-apps.md) integrated directly to your Windows desktop -- [Use GPU acceleration](./tutorials/gpu-compute.md) for machine learning, data science scenarios and more +- Use your device [GPU to accelerate Machine Learning workloads running on Linux.](./tutorials/gpu-compute.md) > [!div class="nextstepaction"] > [Install WSL](install.md) @@ -34,12 +32,14 @@ You can: ## What is WSL 2? -WSL 2 is a new version of the Windows Subsystem for Linux architecture that powers the Windows Subsystem for Linux to run ELF64 Linux binaries on Windows. It's primary goals are to **increase file system performance**, as well as adding **full system call compatibility**. - -This new architecture changes how these Linux binaries interact with Windows and your computer's hardware, but still provides the same user experience as in WSL 1 (the current widely available version). +WSL 2 is the default distro type when installing a Linux distribution. WSL 2 uses virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). Linux distributions run as isolated containers inside of the WSL 2 managed VM. Linux distributions running via WSL 2 will share the same network namespace, device tree (other than `/dev/pts`), CPU/Kernel/Memory/Swap, `/init` binary, but have their own PID namespace, Mount namespace, User namespace, Cgroup namespace, and `init` process. -Individual Linux distributions can be run with either the WSL 1 or WSL 2 architecture. Each distribution can be upgraded or downgraded at any time and you can run WSL 1 and WSL 2 distributions side by side. WSL 2 uses an entirely new architecture that benefits from running a real Linux kernel. +WSL 2 **increases file system performance** and adds **full system call compatibility** in comparison to the WSL 1 architecture. Learn more about how [WSL 1 and WSL 2 compare](./compare-versions.md). -
+Individual Linux distributions can be run with either the WSL 1 or WSL 2 architecture. Each distribution can be upgraded or downgraded at any time and you can run WSL 1 and WSL 2 distributions side by side. See the [Set WSL version command](/windows/wsl/basic-commands#set-default-wsl-version). > [!VIDEO https://www.youtube.com/embed/MrZolfGm8Zk] + +## Microsoft Loves Linux + +Learn more about [Linux resources at Microsoft](/linux), including Microsoft tools that run on Linux, Linux training courses, Cloud Solution Architecture for Linux, and Microsoft + Linux news, events, and partnerships. **Microsoft Loves Linux!** diff --git a/WSL/basic-commands.md b/WSL/basic-commands.md index 5f80dbde..d70bc805 100644 --- a/WSL/basic-commands.md +++ b/WSL/basic-commands.md @@ -1,7 +1,7 @@ --- title: Basic commands for WSL description: Reference for the basic commands included with Windows Subsystem for Linux (WSL). -ms.date: 06/21/2023 +ms.date: 11/20/2023 ms.topic: article --- @@ -56,6 +56,9 @@ wsl --set-version To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace `` with the name of the distribution and replace `` with 1 or 2. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. +> [!WARNING] +> Switching between WSL 1 and WSL 2 can be time-consuming and result in failures due to the differences between the two architectures. For distributions with large projects, we recommend backing up files before attempting a conversion. + ## Set default WSL version ```powershell @@ -180,7 +183,7 @@ wsl --import Imports and exports the specified tar file as a new distribution. The filename can be - for standard input. Options include: -- `--vhd`: Specifies the import/export distribution should be a .vhdx file instead of a tar file +- `--vhd`: Specifies the import/export distribution should be a .vhdx file instead of a tar file (this is only supported using WSL 2) - `--version`: For import only, specifies whether to import the distribution as a WSL 1 or WSL 2 distribution ## Import a distribution in place diff --git a/WSL/compare-versions.md b/WSL/compare-versions.md index a13bca1d..8caa9650 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: 11/10/2023 +ms.date: 11/20/2023 ms.topic: conceptual ms.custom: seo-windows-dev --- @@ -12,7 +12,7 @@ Learn more about different WSL versions, including why WSL 2 is now the default ## Comparing WSL 1 and WSL 2 -This guide will compare WSL 1 and WSL 2, including [exceptions for using WSL 1 rather than WSL 2](#exceptions-for-using-wsl-1-rather-than-wsl-2). The primary differences between WSL 1 and WSL 2 are the use of an actual Linux kernel inside a managed VM, support for full system call compatibility, and performance across the Linux and Windows operating systems. WSL 2 is the current default version when installing a Linux distribution and uses the latest and greatest in virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). If your distribution is currently running WSL 1 and you want to update to WSL 2, see [update from WSL 1 to WSL 2](./install.md#upgrade-version-from-wsl-1-to-wsl-2). +This guide will compare WSL 1 and WSL 2, including [exceptions for using WSL 1 rather than WSL 2](#exceptions-for-using-wsl-1-rather-than-wsl-2). The primary differences between WSL 1 and WSL 2 are the use of an actual Linux kernel inside a managed VM, support for full system call compatibility, and performance across the Linux and Windows operating systems. WSL 2 is the current default version when installing a Linux distribution and uses the latest and greatest in virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). WSL2 runs Linux distributions as isolated containers inside the managed VM. If your distribution is currently running WSL 1 and you want to update to WSL 2, see [update from WSL 1 to WSL 2](./install.md#upgrade-version-from-wsl-1-to-wsl-2). ### Comparing features @@ -86,7 +86,7 @@ We recommend that you use WSL 2 as it offers faster performance and 100% system - WSL 2 does not include support for accessing serial ports. Learn more in the [FAQs](./faq.yml#can-i-access-the-gpu-in-wsl-2--are-there-plans-to-increase-hardware-support-) or in [WSL GitHub repo issue on serial support](https://github.com/microsoft/WSL/issues/4322). - You have strict memory requirements - WSL 2's memory usage grows and shrinks as you use it. When a process frees memory this is automatically returned to Windows. However, as of right now WSL 2 does not yet release cached pages in memory back to Windows until the WSL instance is shut down. If you have long running WSL sessions, or access a very large amount of files, this cache can take up memory on Windows. We are tracking the work to improve this experience on [the WSL GitHub repository issue 4166](https://github.com/microsoft/WSL/issues/4166). -- For those using VirtualBox, you may need to consider the version that you are running and whether it is compatible with WSL 2. (See [WSL GitHub repository issue 798](https://github.com/MicrosoftDocs/WSL/issues/798) for the full discussion. It appears that VirtualBox v6.1.16 works well with WSL 2, but that other versions may experience issues.) +- For those using VirtualBox, be sure to use the latest version of both VirtualBox and WSL 2. See the [related FAQ](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-). - If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a hyper-v virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for its virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150). > [!NOTE] diff --git a/WSL/connect-usb.md b/WSL/connect-usb.md index 4102a597..c85ebeeb 100644 --- a/WSL/connect-usb.md +++ b/WSL/connect-usb.md @@ -1,7 +1,7 @@ --- title: Connect USB devices description: Learn how to connect a USB device to your WSL 2 Linux distribution using usbipd-win. -ms.date: 11/09/2021 +ms.date: 11/20/2023 ms.topic: article --- @@ -23,7 +23,7 @@ Setting up the USB/IP project on your Windows machine will enable common develop > To check your Linux kernel version, open your Linux distribution and enter the command: `uname -a`. To manually update to the latest kernel, open PowerShell and enter the command: 'wsl --update`. > [!IMPORTANT] -> Windows 11 is recommended for connecting USB devices to a Linux distribution running on WSL 2. However, Windows 10 can be used to connect USB devices by building your own USBIP enabled WSL 2 kernel following the [instructions in the USBIPD-WIN project repo](https://github.com/dorssel/usbipd-win/wiki/WSL-support). +> WSL now supports both Windows 10 and Windows 11 via the Microsoft Store, meaning that Windows 10 users now have access to the latest kernel versions without needing to compile from source. See [WSL in the Microsoft Store is now generally available on Windows 10 and 11](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/) for info on how to update to the Store-supported version of WSL. If you are unable to update to the Store-supported version of WSL and automatically receive kernel updates, see the [USBIPD-WIN project repo](https://github.com/dorssel/usbipd-win/wiki/WSL-support) for instructions on connecting USB devices to a Linux distribution running on WSL 2 by building your own USBIP enabled WSL 2 kernel. ## Install the USBIPD-WIN project diff --git a/WSL/faq.yml b/WSL/faq.yml index 9d13c282..1e2fe4a5 100644 --- a/WSL/faq.yml +++ b/WSL/faq.yml @@ -3,7 +3,7 @@ metadata: title: FAQ's about Windows Subsystem for Linux description: "Find answers to frequently asked questions (FAQs) about the Windows Subsystem for Linux, such as 'What can I do with WSL?'." keywords: BashOnWindows, bash, wsl, windows, windowssubsystem, faq - ms.date: 09/27/2021 + ms.date: 11/20/2023 ms.topic: faq ms.localizationpriority: high title: Frequently Asked Questions about Windows Subsystem for Linux @@ -229,7 +229,7 @@ sections: - question: | Will I be able to run WSL 2 and other 3rd party virtualization tools such as VMware, or VirtualBox? answer: | - Some 3rd party applications cannot work when Hyper-V is in use, which means they will not be able to run when WSL 2 is enabled, such as VMware and VirtualBox. However, recently both VirtualBox and VMware have released versions that support Hyper-V and WSL2. Learn more about [VirtualBox's changes here](https://www.virtualbox.org/wiki/Changelog-6.0) and [VMware's changes here](https://blogs.vmware.com/workstation/2020/01/vmware-workstation-tech-preview-20h1.html). For troubleshooting issues, take a look at the [VirtualBox issue discussions in the WSL repo on GitHub](https://github.com/MicrosoftDocs/WSL/issues?q=is%3Aissue+virtualbox+sort%3Acomments-desc). + Some 3rd party applications cannot work when Hyper-V is in use, which means they will not be able to run when WSL 2 is enabled, such as VMware and VirtualBox. However, recently both VirtualBox and VMware have released versions that support Hyper-V and WSL2. Learn more about [VirtualBox's changes here](https://www.virtualbox.org/wiki/Changelog-6.0) and [VMware's changes here](https://blogs.vmware.com/workstation/2020/01/vmware-workstation-tech-preview-20h1.html). For troubleshooting issues, take a look at the [VirtualBox issue discussions in the WSL repo on GitHub](https://github.com/MicrosoftDocs/WSL/issues?q=is%3Aissue+virtualbox+sort%3Acomments-desc). StackOverflow also offers a helpful tip: [How to get VirtualBox 6.0 and WSL working at the same time](https://stackoverflow.com/questions/58031941/how-to-get-virtualbox-6-0-and-wsl-working-at-the-same-time). We are consistently working on solutions to support third-party integration of Hyper-V. For example, we expose a set of APIs called [Hypervisor Platform](/virtualization/api/) that third-party virtualization providers can use to make their software compatible with Hyper-V. This lets applications use the Hyper-V architecture for their emulation such as [the Google Android Emulator](https://devblogs.microsoft.com/visualstudio/hyper-v-android-emulator-support/), and VirtualBox 6 and above which are both now compatible with Hyper-V. diff --git a/WSL/install-manual.md b/WSL/install-manual.md index be678db3..47bee86d 100644 --- a/WSL/install-manual.md +++ b/WSL/install-manual.md @@ -2,7 +2,7 @@ title: Manual installation steps for older versions of WSL description: Step by step instructions to manually install WSL on older versions of Windows, rather than using the wsl install command. keywords: wsl, install, BashOnWindows, bash, windows subsystem for linux, install ubuntu on windows, enable WSL2, linux on windows -ms.date: 03/22/2023 +ms.date: 11/20/2023 ms.topic: article adobe-target: true --- @@ -97,6 +97,7 @@ wsl --set-default-version 2 - [Pengwin Enterprise](https://www.microsoft.com/store/apps/9N8LP0X93VCP) - [Alpine WSL](https://www.microsoft.com/store/apps/9p804crf0395) - [Raft(Free Trial)](https://www.microsoft.com/store/apps/9msmjqd017x7) + - [Alma Linux](https://apps.microsoft.com/search?query=alma+linux) 2. From the distribution's page, select "Get". diff --git a/WSL/install.md b/WSL/install.md index 7f859b3a..142e50b0 100644 --- a/WSL/install.md +++ b/WSL/install.md @@ -63,7 +63,7 @@ You can list your installed Linux distributions and check the version of WSL eac To set the default version to WSL 1 or WSL 2 when a new Linux distribution is installed, use the command: `wsl --set-default-version `, replacing `` with either 1 or 2. -To set the default Linux distribution used with the `wsl` command, enter: `wsl -s ` or `wsl --setdefault `, replacing `` with the name of the Linux distribution you would like to use. For example, from PowerShell/CMD, enter: `wsl -s Debian` to set the default distribution to Debian. Now running `wsl npm init` from Powershell will run the `npm init` command in Debian. +To set the default Linux distribution used with the `wsl` command, enter: `wsl -s ` or `wsl --set-default `, replacing `` with the name of the Linux distribution you would like to use. For example, from PowerShell/CMD, enter: `wsl -s Debian` to set the default distribution to Debian. Now running `wsl npm init` from Powershell will run the `npm init` command in Debian. To run a specific wsl distribution from within PowerShell or Windows Command Prompt without changing your default distribution, use the command: `wsl -d `, replacing `` with the name of the distribution you want to use. @@ -90,7 +90,7 @@ WSL supports running as many different Linux distributions as you would like to There are several ways to run your Linux distributions once installed: - [Install Windows Terminal](/windows/terminal/get-started) ***(Recommended)*** Using Windows Terminal supports as many command lines as you would like to install and enables you to open them in multiple tabs or window panes and quickly switch between multiple Linux distributions or other command lines (PowerShell, Command Prompt, Azure CLI, etc). You can fully customize your terminal with unique color schemes, font styles, sizes, background images, and custom keyboard shortcuts. [Learn more.](/windows/terminal) -- You can directly open your Linux distribution by visiting the Windows Start menu and typing the name of your installed distributions. For example: "Ubuntu". This will open Ubuntu in it's own console window. +- You can directly open your Linux distribution by visiting the Windows Start menu and typing the name of your installed distributions. For example: "Ubuntu". This will open Ubuntu in its own console window. - From Windows Command Prompt or PowerShell, you can enter the name of your installed distribution. For example: `ubuntu` - From Windows Command Prompt or PowerShell, you can open your default Linux distribution inside your current command line, by entering: `wsl.exe`. - From Windows Command Prompt or PowerShell, you can use your default Linux distribution inside your current command line, without entering a new one, by entering:`wsl [command]`. Replacing `[command]` with a WSL command, such as: `wsl -l -v` to list installed distributions or `wsl pwd` to see where the current directory path is mounted in wsl. From PowerShell, the command `get-date` will provide the date from the Windows file system and `wsl date` will provide the date from the Linux file system. diff --git a/WSL/networking.md b/WSL/networking.md index 15f17cb7..98242571 100644 --- a/WSL/networking.md +++ b/WSL/networking.md @@ -85,7 +85,7 @@ Here are the current benefits to enabling this mode: - Connect to WSL directly from your local area network (LAN) > [!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`. +> 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}’ -DefaultInboundAction 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). diff --git a/WSL/setup/environment.md b/WSL/setup/environment.md index 5852ce01..5fc3ea92 100644 --- a/WSL/setup/environment.md +++ b/WSL/setup/environment.md @@ -1,7 +1,7 @@ --- title: Set up a WSL development environment description: Set up a WSL development environment using best practices from this set-by-step guide. Learn how to run Ubuntu, Visual Studio Code or Visual Studio, Git, Windows Credential Manager, MongoDB, MySQL, Docker remote containers and more. -ms.date: 01/04/2022 +ms.date: 11/20/2023 ms.topic: article no-loc: [Terminal] ms.custom: seo-windows-dev @@ -174,7 +174,7 @@ In addition, many commands are interoperable between Windows and Linux. Here are - [Run a Windows tool directly from the WSL command line](../filesystems.md#run-windows-tools-from-linux): `.exe` For example, to open your .bashrc file (the shell script that runs whenever your Linux command line is started), enter: `notepad.exe .bashrc` -- [Run the Windows ipconfig.exe tool with the Linux Grep tool](../filesystems.md#run-windows-tools-from-linux): `ipconfig.exe | grep IPv4 | cut -d: -f2` +- [Run the Windows ipconfig.exe tool with the Linux Grep tool](../filesystems.md#run-windows-tools-from-linux): From Bash enter the command `ipconfig.exe | grep IPv4 | cut -d: -f2` or from PowerShell enter `ipconfig.exe | wsl grep IPv4 | wsl cut -d: -f2` This example demonstrates the ipconfig tool on the Windows file system being used to display the current TCP/IP network configuration values and then being filtered to only the IPv4 result with grep, a Linux tool. ## Mount an external drive or USB diff --git a/WSL/tutorials/wsl-git.md b/WSL/tutorials/wsl-git.md index 240f53e2..db48985e 100644 --- a/WSL/tutorials/wsl-git.md +++ b/WSL/tutorials/wsl-git.md @@ -138,6 +138,6 @@ Since Windows and Linux use different default line endings, Git may report a lar ## Additional resources * [WSL & VS Code](./wsl-vscode.md) -* [GitHub Learning Lab: Online courses](https://lab.github.com/) +* [GitHub Learning Lab: Online courses](https://github.com/apps/github-learning-lab) * [Git Visualization Tool](http://git-school.github.io/visualizing-git/) * [Git Tools - Credential Storage](https://git-scm.com/book/it/v2/Git-Tools-Credential-Storage) From d90da18952911dfbdbe3d46904784904769277ca Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Wed, 10 Jan 2024 12:01:14 -0800 Subject: [PATCH 2/3] Main > Live (#1894) * Fixing small formatting and writing errors. (#1863) * Fix broken code block and bookmark link (#1866) * Fix broken code block * Update broken wslconfig bookmark * Update install-on-server.md (#1871) Fix indent and numbering for better readability. * Fix punctuation errors (#1876) * small improvements in troubleshooting.md (#1877) Some small formatting improvements. Also added the command to restart the hns service. * Fix a few typos (#1879) Co-authored-by: Matt Wojciakowski * Updated guide to fix an issue because of a wrong command (#1884) * Update wsl-containers.md Running Dev Containers: **Open Folder in Container...** when using this guide is not / no longer correct, as most readers will already have opened the folder while connected to WSL based on the steps provided above. We need to use **Dev Containers: Reopen in Container** or it will fail to create the .devcontainer folder and devcontainer.json and give a (unfortunately not very clear) error message. See also: https://code.visualstudio.com/docs/devcontainers/containers#_open-a-wsl-2-folder-in-a-container-on-windows - Use the Dev Containers: Reopen in Container command from a folder already opened using the WSL extension. - Select Dev Containers: Open Folder in Container... from the Command Palette (F1) and choose a WSL folder using the local \\wsl$ share (from the Windows side). * Update wsl-containers.md --------- Co-authored-by: Matt Wojciakowski * Update faq.yml -- tiny grammar change (#1885) * Update faq.yml -- tiny grammar change 'changes to locale to' -> 'changes the locale to' * Update basic-commands.md 'If you running WSL' -> 'If you run WSL' * Update basic-commands.md * rephrase a long sentence * swap order of two sentences to make example of command closer to the description of the command example of command: `wsl --set-default-version 2` * Update basic-commands.md Replace wsl -u `, `wsl --user with wsl --user `wsl -u ` and `wsl --user ` are equivalent. Both commands are correct for the section of the documentation, but the display of the commands in the documentation was incorrect due to the stray ticks and comma. * Update gui-apps.md to simplify commits. (#1880) * Update gui-apps.md If we are already referencing apt, why not just use apt to install google chrome? * Update gui-apps.md forgot --fix-missing * Add a note to explain the command flags and path --------- Co-authored-by: Matt Wojciakowski * Fix anchor warning --------- Co-authored-by: Stefan Nikolaj <51296436+snikolaj@users.noreply.github.com> Co-authored-by: Anton Kesy Co-authored-by: Ishan Jain Co-authored-by: Krishna Vivek Vitta <84629581+krishnacx@users.noreply.github.com> Co-authored-by: icyerasor Co-authored-by: Blake-Madden <66873089+Blake-Madden@users.noreply.github.com> Co-authored-by: vmsteiner <107506233+vmsteiner@users.noreply.github.com> Co-authored-by: Andrew Zipperer <47086307+zipperer@users.noreply.github.com> Co-authored-by: Wes Bryie --- WSL/basic-commands.md | 6 +++--- WSL/enterprise.md | 2 +- WSL/faq.yml | 14 +++++++------- WSL/file-permissions.md | 2 +- WSL/install-on-server.md | 20 ++++++++++---------- WSL/install.md | 2 +- WSL/intune.md | 6 +++--- WSL/networking.md | 8 ++++---- WSL/troubleshooting.md | 18 +++++++++++------- WSL/tutorials/gui-apps.md | 8 ++++---- WSL/tutorials/wsl-containers.md | 4 ++-- WSL/tutorials/wsl-database.md | 4 ++-- WSL/wsl-config.md | 2 +- WSL/wsl2-mount-disk.md | 4 ++-- 14 files changed, 52 insertions(+), 48 deletions(-) diff --git a/WSL/basic-commands.md b/WSL/basic-commands.md index e675ac93..4dc648f9 100644 --- a/WSL/basic-commands.md +++ b/WSL/basic-commands.md @@ -30,7 +30,7 @@ When WSL is not installed options include: - `--no-distribution`: Do not install a distribution when installing WSL. > [!NOTE] -> If you running WSL on Windows 10 or an older version, you may need to include the `-d` flag with the `--install` command to specify a distribution: `wsl --install -d `. +> If you run WSL on Windows 10 or an older version, you may need to include the `-d` flag with the `--install` command to specify a distribution: `wsl --install -d `. ## List available Linux distributions @@ -65,7 +65,7 @@ To designate the version of WSL (1 or 2) that a Linux distribution is running on wsl --set-default-version ``` -To set a default version of WSL 1 or WSL 2, replacing `` with either the number 1 or 2 to represent which version of WSL you would like the installation to default on for new Linux distribution installations. For example, `wsl --set-default-version 2`. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. +To set a default version of WSL 1 or WSL 2, replace `` with either the number 1 or 2. For example, `wsl --set-default-version 2`. The number represents the version of WSL to default to for new Linux distribution installations. [Comparing WSL 1 and WSL 2](./compare-versions.md). WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. ## Set default Linux distribution @@ -128,7 +128,7 @@ See a list of options and commands available with WSL. ## Run as a specific user ```powershell -wsl -u `, `wsl --user +wsl --user ``` To run WSL as a specified user, replace `` with the name of a user that exists in the WSL distribution. diff --git a/WSL/enterprise.md b/WSL/enterprise.md index af1ec37f..9e3890b9 100644 --- a/WSL/enterprise.md +++ b/WSL/enterprise.md @@ -40,7 +40,7 @@ See [Intune settings for WSL](./intune.md) for guidance on using InTune to manag 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, we recommend configuring [settings under `[wsl2]` in the `.wslconfig` file](/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to suite your specific Enterprise scenario. +Additionally, we recommend configuring [settings under `[wsl2]` in the `.wslconfig` file](/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to suit your specific Enterprise scenario. #### Mirrored mode networking diff --git a/WSL/faq.yml b/WSL/faq.yml index 1e2fe4a5..8096ccf1 100644 --- a/WSL/faq.yml +++ b/WSL/faq.yml @@ -22,7 +22,7 @@ sections: - question: | Who is WSL for? answer: | - This is primarily a tool for developers, especially web developers, those working on open source projects, or deploying to Linux server environments. WSL is for anyone who likes using Bash, common Linux tools (`sed`, `awk`, etc.) and Linux-first frameworks (Ruby, Python, etc.) but also enjoys using Windows productivity tools + This is primarily a tool for developers, especially web developers, those working on open source projects, or deploying to Linux server environments. WSL is for anyone who likes using Bash, common Linux tools (`sed`, `awk`, etc.) and Linux-first frameworks (Ruby, Python, etc.) but also enjoys using Windows productivity tools. - question: | What can I do with WSL? @@ -38,7 +38,7 @@ sections: - question: | Could you describe a typical development workflow that incorporates WSL? answer: | - WSL targets a developer audience with the intent to be used as part of an inner development loop. Let's say that Sam is creating a CI/CD pipeline (Continuous Integration & Continuous Delivery) and wants to test it first on a local machine (laptop) before deploying it to the cloud. Sam can enable WSL (& WSL 2 to improve speed and performance), and then use a genuine Linux Ubuntu instance locally (on the laptop) with whatever Bash commands and tools they prefer. Once the development pipeline is verified locally, Sam can then push that CI/CD pipeline up to the cloud (ie Azure) by making it into a Docker container and pushing the container to a cloud instance where it runs on a production-ready Ubuntu VM. + WSL targets a developer audience with the intent to be used as part of an inner development loop. Let's say that Sam is creating a CI/CD pipeline (Continuous Integration & Continuous Delivery) and wants to test it first on a local machine (laptop) before deploying it to the cloud. Sam can enable WSL (& WSL 2 to improve speed and performance), and then use a genuine Linux Ubuntu instance locally (on the laptop) with whatever Bash commands and tools they prefer. Once the development pipeline is verified locally, Sam can then push that CI/CD pipeline up to the cloud (i.e. Azure) by making it into a Docker container and pushing the container to a cloud instance where it runs on a production-ready Ubuntu VM. - question: | What is Bash? @@ -94,9 +94,9 @@ sections: answer: | One of the benefits of WSL is being able to access your files via both Windows and Linux apps or tools. - WSL mounts your machine's fixed drives under the `/mnt/` folder in your Linux distros. For example, your `C:` drive is mounted under `/mnt/c/` + WSL mounts your machine's fixed drives under the `/mnt/` folder in your Linux distros. For example, your `C:` drive is mounted under `/mnt/c/`. - Using your mounted drives, you can edit code in, for example, `C:\dev\myproj\` using [Visual Studio](https://visualstudio.microsoft.com/vs/) / or [VS Code](https://code.visualstudio.com/), and build/test that code in Linux by accessing the same files via `/mnt/c/dev/myproj`. + Using your mounted drives, you can edit code in, for example, `C:\dev\myproj\` using [Visual Studio](https://visualstudio.microsoft.com/vs/) or [VS Code](https://code.visualstudio.com/), and build/test that code in Linux by accessing the same files via `/mnt/c/dev/myproj`. Learn more in [Working across Windows and Linux file systems](./filesystems.md) article. @@ -106,7 +106,7 @@ sections: 1. Files under the Linux root (i.e. `/`) are controlled by WSL which aligns with Linux behavior, including but not limited to: * Files which contain invalid Windows filename characters * Symlinks created for non-admin users - * Changing file attributes through chmod and chown + * Changing file attributes through `chmod` and `chown` * File/folder case sensitivity 2. Files in mounted drives are controlled by Windows and have the following behaviors: @@ -125,14 +125,14 @@ sections: - question: | How do I run an OpenSSH server? answer: | - OpenSSH ships with Windows as an optional feature. See the [Install OpenSSH](/windows-server/administration/openssh/openssh_install_firstuse) doc. Administrator privileges in Windows are required to run OpenSSH in WSL. To run an OpenSSH server, run your WSL distribution (ie Ubuntu) or Windows Terminal as an administrator. There are several resources out there covering SSH scenarios with WSL. Check out Scott Hanselman's blog articles: [How to SSH into a Windows 10 Machine from Linux OR Windows OR anywhere](https://www.hanselman.com/blog/how-to-ssh-into-a-windows-10-machine-from-linux-or-windows-or-anywhere), [How to SSH into WSL2 on Windows 10 from an external machine](https://www.hanselman.com/blog/how-to-ssh-into-wsl2-on-windows-10-from-an-external-machine), [THE EASY WAY how to SSH into Bash and WSL2 on Windows 10 from an external machine](https://www.hanselman.com/blog/the-easy-way-how-to-ssh-into-bash-and-wsl2-on-windows-10-from-an-external-machine), and [How to use Windows 10's built-in OpenSSH to automatically SSH into a remote Linux machine](https://www.hanselman.com/blog/how-to-use-windows-10s-builtin-openssh-to-automatically-ssh-into-a-remote-linux-machine). + OpenSSH ships with Windows as an optional feature. See the [Install OpenSSH](/windows-server/administration/openssh/openssh_install_firstuse) doc. Administrator privileges in Windows are required to run OpenSSH in WSL. To run an OpenSSH server, run your WSL distribution (i.e. Ubuntu) or Windows Terminal as an administrator. There are several resources out there covering SSH scenarios with WSL. Check out Scott Hanselman's blog articles: [How to SSH into a Windows 10 Machine from Linux OR Windows OR anywhere](https://www.hanselman.com/blog/how-to-ssh-into-a-windows-10-machine-from-linux-or-windows-or-anywhere), [How to SSH into WSL2 on Windows 10 from an external machine](https://www.hanselman.com/blog/how-to-ssh-into-wsl2-on-windows-10-from-an-external-machine), [THE EASY WAY how to SSH into Bash and WSL2 on Windows 10 from an external machine](https://www.hanselman.com/blog/the-easy-way-how-to-ssh-into-bash-and-wsl2-on-windows-10-from-an-external-machine), and [How to use Windows 10's built-in OpenSSH to automatically SSH into a remote Linux machine](https://www.hanselman.com/blog/how-to-use-windows-10s-builtin-openssh-to-automatically-ssh-into-a-remote-linux-machine). - question: | How do I change the display language of WSL? answer: | WSL install will try to automatically change the Ubuntu locale to match the locale of your Windows install. If you do not want this behavior you can run this command to change the Ubuntu locale after install completes. You will have to relaunch your WSL distribution for this change to take effect. - The below example changes to locale to en-US: + The below example changes the locale to en-US: ```bash sudo update-locale LANG=en_US.UTF8 diff --git a/WSL/file-permissions.md b/WSL/file-permissions.md index 0a039851..99a2fe92 100644 --- a/WSL/file-permissions.md +++ b/WSL/file-permissions.md @@ -41,7 +41,7 @@ The result depends on if the file already has existing metadata. ##### DrvFS file does not have metadata (default) -If the file has no metadata associated with it then we translate the effective permissions of the Windows user to read/write/execute bits and set them to the this as the same value for user, group, and other. For example, if your Windows user account has read and execute access but not write access to the file then this will be shown as `r-x` for user, group and other. If the file has the 'Read Only' attribute set in Windows then we do not grant write access in Linux. +If the file has no metadata associated with it then we translate the effective permissions of the Windows user to read/write/execute bits and set them to this as the same value for user, group, and other. For example, if your Windows user account has read and execute access but not write access to the file then this will be shown as `r-x` for user, group and other. If the file has the 'Read Only' attribute set in Windows then we do not grant write access in Linux. ##### The file has metadata diff --git a/WSL/install-on-server.md b/WSL/install-on-server.md index 00e73b49..c0ac9a44 100644 --- a/WSL/install-on-server.md +++ b/WSL/install-on-server.md @@ -61,19 +61,19 @@ Now that you've downloaded a Linux distribution, in order to extract its content 2. Once the distribution has been downloaded, navigate to the folder containing the download and run the following command in that directory, where `app-name` is the name of the Linux distribution .appx file. -```Powershell -Add-AppxPackage .\app_name.appx -``` + ```Powershell + Add-AppxPackage .\app_name.appx + ``` -> [!CAUTION] -> **Installation failed with error 0x8007007e**: If you receive this error, then your system doesn't support WSL. Ensure that you're running Windows build 16215 or later. [Check your build](troubleshooting.md#check-your-build-number). Also check to [confirm that WSL is enabled](troubleshooting.md#confirm-wsl-is-enabled) and your computer was restarted after the feature was enabled. + > [!CAUTION] + > **Installation failed with error 0x8007007e**: If you receive this error, then your system doesn't support WSL. Ensure that you're running Windows build 16215 or later. [Check your build](troubleshooting.md#check-your-build-number). Also check to [confirm that WSL is enabled](troubleshooting.md#confirm-wsl-is-enabled) and your computer was restarted after the feature was enabled. -3.Add your Linux distribution path to the Windows environment PATH (`C:\Users\Administrator\Ubuntu` in this example), using PowerShell: +3. Add your Linux distribution path to the Windows environment PATH (`C:\Users\Administrator\Ubuntu` in this example), using PowerShell: -```powershell -$userenv = [System.Environment]::GetEnvironmentVariable("Path", "User") -[System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";C:\Users\Administrator\Ubuntu", "User") -``` + ```powershell + $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User") + [System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";C:\Users\Administrator\Ubuntu", "User") + ``` You can now launch your distribution from any path by typing `.exe`. For example: `ubuntu.exe`. diff --git a/WSL/install.md b/WSL/install.md index 142e50b0..29e76416 100644 --- a/WSL/install.md +++ b/WSL/install.md @@ -31,7 +31,7 @@ If you're running an older build, or just prefer not to use the install command The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for files to de-compress and be stored on your machine. All future launches should take less than a second. > [!NOTE] -> The above command only works if WSL is not installed at all, if you run `wsl --install` and see the WSL help text, please try running `wsl --list --online` to see a list of available distros and run `wsl --install -d ` to install a distro. +> The above command only works if WSL is not installed at all. If you run `wsl --install` and see the WSL help text, please try running `wsl --list --online` to see a list of available distros and run `wsl --install -d ` to install a distro. > To uninstall WSL, see [Uninstall legacy version of WSL](/windows/wsl/troubleshooting#uninstall-legacy-version-of-wsl) or [unregister or uninstall a Linux distribution](/windows/wsl/basic-commands#unregister-or-uninstall-a-linux-distribution). ## Change the default Linux distribution installed diff --git a/WSL/intune.md b/WSL/intune.md index 6e79a78f..d0752923 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: 11/15/2023 +ms.date: 01/10/2024 ms.topic: article --- @@ -26,7 +26,7 @@ To maximize security in an enterprise environment, we recommend that you specify | 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. | +| Allow kernel debugging | Disabled | When set to disabled, this policy disables kernel debugging configuration via .wslconfig (wsl2.kernelDebugPort). This policy only applies to Store WSL. | ## Control access to WSL @@ -40,7 +40,7 @@ This will allow you to configure WSL to ensure that users are only using the lat ## 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. 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. +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-settings-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 98242571..c9ea6eb0 100644 --- a/WSL/networking.md +++ b/WSL/networking.md @@ -22,7 +22,7 @@ If you are building a networking app (for example an app running on a NodeJS or 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: ` ip route show | grep -i default | awk '{ print $3}' +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. @@ -74,7 +74,7 @@ Using `listenaddress=0.0.0.0` will listen on all [IPv4 ports](https://stackoverf ## 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. +You can [set `networkingMode=mirrored` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-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: @@ -91,11 +91,11 @@ This new mode addresses networking issues seen with using a NAT (Network Address ## 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. +Setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-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. +Setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-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 diff --git a/WSL/troubleshooting.md b/WSL/troubleshooting.md index f5279b1f..37b205b6 100644 --- a/WSL/troubleshooting.md +++ b/WSL/troubleshooting.md @@ -20,7 +20,7 @@ The [WSL product repo issues](https://github.com/Microsoft/wsl/issues) enables y You can also: - **File a documentation issue** using the [WSL docs repo](https://github.com/MicrosoftDocs/wsl/issues). To contribute to the WSL docs, see the [Microsoft Docs contributor guide](/contribute). -- **File a Windows Terminal** issue using the the [Windows Terminal product repo](https://github.com/microsoft/terminal/issues) if your problem is related more to the Windows Terminal, Windows Console, or the command-line UI. +- **File a Windows Terminal** issue using the [Windows Terminal product repo](https://github.com/microsoft/terminal/issues) if your problem is related more to the Windows Terminal, Windows Console, or the command-line UI. ## Installation issues @@ -139,7 +139,7 @@ If there are no Win32 paths in your $PATH, interop isn't going to find the .exe. You can verify it by running `echo $PATH` in Linux. It's expected that you will see a Win32 path (for example, /mnt/c/Windows) in the output. If you can't see any Windows paths then most likely your PATH is being overwritten by your Linux shell. -Here is a an example that /etc/profile on Debian contributed to the problem: +Here is an example that /etc/profile on Debian contributed to the problem: ```Bash if [ "`id -u`" -eq 0 ]; then @@ -423,13 +423,17 @@ This must be unchecked for the NAT DNS proxy configuration to work from WSL, **o **4. The HNS Firewall rule to allow the DNS packets to shared access can become invalid, referencing a previous WSL interface identifier.** This is a flaw within HNS which has been fixed with the latest Windows 11 release. On earlier releases, if this occurs, it’s not easily discoverable, but it has a simple work around: - Stop WSL - 1. ```wsl.exe –shutdown``` + + ```wsl.exe –shutdown``` - Delete the old HNS Firewall rule. This Powershell command should work in most cases: - 1.```Get-NetFirewallRule -Name "HNS*" | Get-NetFirewallPortFilter | where Protocol -eq UDP | where LocalPort -eq 53 | Remove-NetFirewallRule``` -- Remove all HNS endpoints - 1. Note: if HNS is used to manage other containers, such as MDAG or Windows Sandbox, those should also be stopped. - 2. ```hnsdiag.exe delete all``` + + ```Get-NetFirewallRule -Name "HNS*" | Get-NetFirewallPortFilter | where Protocol -eq UDP | where LocalPort -eq 53 | Remove-NetFirewallRule``` +- Remove all HNS endpoints. Note: if HNS is used to manage other containers, such as MDAG or Windows Sandbox, those should also be stopped. + + ```hnsdiag.exe delete all``` - Reboot or restart the HNS service + + ```Restart-Service hns``` - When WSL is restarted, HNS will create new Firewall rules, correctly targeting the WSL interface. ### Starting WSL or installing a distribution returns an error code diff --git a/WSL/tutorials/gui-apps.md b/WSL/tutorials/gui-apps.md index ed10a49e..160f862f 100644 --- a/WSL/tutorials/gui-apps.md +++ b/WSL/tutorials/gui-apps.md @@ -1,7 +1,7 @@ --- title: Run Linux GUI apps with WSL description: Learn how WSL support running Linux GUI apps. -ms.date: 07/17/2023 +ms.date: 01/04/2024 ms.topic: article --- @@ -143,9 +143,9 @@ To install the Google Chrome for Linux: 1. Change directories into the temp folder: `cd /tmp` 2. Use wget to download it: `wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb` -3. Get the current stable version: `sudo dpkg -i google-chrome-stable_current_amd64.deb` -4. Fix the package: `sudo apt install --fix-broken -y` -5. Configure the package: `sudo dpkg -i google-chrome-stable_current_amd64.deb` +3. Install the package: `sudo apt install --fix-missing ./google-chrome-stable_current_amd64.deb` + +*The `--fix-missing` option is used to fix missing dependencies that may arise during the installation process. The `./` in the command specifies the current directory where the .deb file is located. If the .deb file is located in a different directory, you will need to specify the path to the file in the command. To launch, enter: `google-chrome` diff --git a/WSL/tutorials/wsl-containers.md b/WSL/tutorials/wsl-containers.md index ffeba4f6..dff57221 100644 --- a/WSL/tutorials/wsl-containers.md +++ b/WSL/tutorials/wsl-containers.md @@ -2,7 +2,7 @@ title: Get started with Docker containers on WSL description: Learn how to set up Docker containers on the Windows Subsystem for Linux. keywords: wsl, windows, windowssubsystem, windows 10, docker, containers -ms.date: 09/27/2021 +ms.date: 01/04/2024 ms.topic: article --- @@ -111,7 +111,7 @@ Let's use Docker to create a development container for an existing app project. ![VS Code WSL Remote indicator](../media/vscode-remote-indicator.png) -4. From the VS Code command pallette (Ctrl + Shift + P), enter: **Dev Containers: Open Folder in Container...** If this command doesn't display as you begin to type it, check to ensure that you've installed the Dev Containers extension linked above. +4. From the VS Code command pallette (Ctrl + Shift + P), enter: **Dev Containers: Reopen in Container** as we are using a folder already opened using the WSL extension. Alternativly use **Dev Containers: Open Folder in Container...** to choose a WSL folder using the local `\\wsl$` share (from the Windows side). See the Visual Studio Code [Quick start: Open an existing folder in a container](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container) for more details. If these commands don't display as you begin to type, check to ensure that you've installed the Dev Containers extension linked above. ![VS Code Dev Containers command](../media/docker-extension.png) diff --git a/WSL/tutorials/wsl-database.md b/WSL/tutorials/wsl-database.md index f3ac2fb0..7c3984da 100644 --- a/WSL/tutorials/wsl-database.md +++ b/WSL/tutorials/wsl-database.md @@ -35,7 +35,7 @@ Some [popular choices](https://insights.stackoverflow.com/survey/2021#section-mo **MongoDB** is an open-source NoSQL document database designed to work with JSON and store schema-free data. It is horizontally scalable, which means multiple smaller machines will do the work for you. It's good for flexibility and unstructured data, and caching real-time analytics. -**Redis** is is an open-source NoSQL in-memory data structure store. It uses key-value pairs for storage instead of documents. +**Redis** is an open-source NoSQL in-memory data structure store. It uses key-value pairs for storage instead of documents. ## Install MySQL @@ -54,7 +54,7 @@ Example using the Ubuntu distribution: For more about working with MySQL databases, see the [MySQL docs](https://dev.mysql.com/doc/mysql-getting-started/en/). -To work with with MySQL databases in VS Code, try the [MySQL extension](https://marketplace.visualstudio.com/items?itemName=cweijan.vscode-mysql-client2). +To work with MySQL databases in VS Code, try the [MySQL extension](https://marketplace.visualstudio.com/items?itemName=cweijan.vscode-mysql-client2). You may also want to run the included security script. This changes some of the less secure default options for things like remote root logins and sample users. This script also includes steps to change password for MySQL root user. To run the security script: diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index 6885a374..03f5264c 100644 --- a/WSL/wsl-config.md +++ b/WSL/wsl-config.md @@ -28,7 +28,7 @@ You must wait until the subsystem running your Linux distribution completely sto 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. +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 specific distribution that's running instantly. ## wsl.conf diff --git a/WSL/wsl2-mount-disk.md b/WSL/wsl2-mount-disk.md index 5cea9c12..08fde4f5 100644 --- a/WSL/wsl2-mount-disk.md +++ b/WSL/wsl2-mount-disk.md @@ -23,7 +23,7 @@ You will need to be on Windows 11 Build 22000 or later, or be running the Micros External drives formatted for Windows typically use the NTFS file system formatting. External drives formatted for Linux typically use the Ext4 file system formatting. -If you have mounted a NTFS-formatted drive on your Windows file system, you can access that drive from your Linux distribution using WSL by creating a mounted directory (`sudo mkdir /mnt/d`, replacing 'd' with whatever drive letter you'd like to use) and then using the `drvfs` file system interop plugin, with the command: +If you have mounted an NTFS-formatted drive on your Windows file system, you can access that drive from your Linux distribution using WSL by creating a mounted directory (`sudo mkdir /mnt/d`, replacing 'd' with whatever drive letter you'd like to use) and then using the `drvfs` file system interop plugin, with the command: ```bash sudo mount -t drvfs D: /mnt/d @@ -212,7 +212,7 @@ This will make the block device available inside WSL 2 so it can be mounted manu > [!NOTE] > This option is only available with [WSL from the Microsoft Store](https://devblogs.microsoft.com/commandline/a-preview-of-wsl-in-the-microsoft-store-is-now-available/) -By default the mountpoint name is generated based on the physical disk or VHD name. This can be overriden with `--name`. Example: +By default the mountpoint name is generated based on the physical disk or VHD name. This can be overridden with `--name`. Example: ```powershell wsl --mount --name myDisk From a7f1dfa727274fc8775396958dbb2690e3a956f8 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Fri, 2 Feb 2024 14:45:42 -0800 Subject: [PATCH 3/3] Merge main > live (#1919) * Fixing small formatting and writing errors. (#1863) * Fix broken code block and bookmark link (#1866) * Fix broken code block * Update broken wslconfig bookmark * Update install-on-server.md (#1871) Fix indent and numbering for better readability. * Fix punctuation errors (#1876) * small improvements in troubleshooting.md (#1877) Some small formatting improvements. Also added the command to restart the hns service. * Fix a few typos (#1879) Co-authored-by: Matt Wojciakowski * Updated guide to fix an issue because of a wrong command (#1884) * Update wsl-containers.md Running Dev Containers: **Open Folder in Container...** when using this guide is not / no longer correct, as most readers will already have opened the folder while connected to WSL based on the steps provided above. We need to use **Dev Containers: Reopen in Container** or it will fail to create the .devcontainer folder and devcontainer.json and give a (unfortunately not very clear) error message. See also: https://code.visualstudio.com/docs/devcontainers/containers#_open-a-wsl-2-folder-in-a-container-on-windows - Use the Dev Containers: Reopen in Container command from a folder already opened using the WSL extension. - Select Dev Containers: Open Folder in Container... from the Command Palette (F1) and choose a WSL folder using the local \\wsl$ share (from the Windows side). * Update wsl-containers.md --------- Co-authored-by: Matt Wojciakowski * Update faq.yml -- tiny grammar change (#1885) * Update faq.yml -- tiny grammar change 'changes to locale to' -> 'changes the locale to' * Update basic-commands.md 'If you running WSL' -> 'If you run WSL' * Update basic-commands.md * rephrase a long sentence * swap order of two sentences to make example of command closer to the description of the command example of command: `wsl --set-default-version 2` * Update basic-commands.md Replace wsl -u `, `wsl --user with wsl --user `wsl -u ` and `wsl --user ` are equivalent. Both commands are correct for the section of the documentation, but the display of the commands in the documentation was incorrect due to the stray ticks and comma. * Update gui-apps.md to simplify commits. (#1880) * Update gui-apps.md If we are already referencing apt, why not just use apt to install google chrome? * Update gui-apps.md forgot --fix-missing * Add a note to explain the command flags and path --------- Co-authored-by: Matt Wojciakowski * Fix anchor warning * Updated docs for usbipd-win updates (#1870) * Updated docs for usbipd-win updates * Update url to latest Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Fixes based on feedback Thank you @dorssel ! * Remove admin requirement Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Remove x86 support Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> --------- Co-authored-by: Matt Wojciakowski Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> * Moving experimental settings to the experimental section (#1901) * Moving experimental settings to the experimental section Some networking config settings are still experimental. Moving those to the experimental section of the document so customers know how to use these settings. * Added code ticks to new setting entries * Update wsl-config.md fixing settings which are no longer experimental, but the text still referred to them as experimental * Update wsl-config.md fixed the string referring to autoProxy. it's no longer experimental. --------- Co-authored-by: Matt Wojciakowski * Moving ms.prod and ms.technology to ms.service and ms.subservice * Update to new feedback mechanism (#1917) * Update to new feedback mechanism * fix desc syntax * Fix template link * add svg support --------- Co-authored-by: Stefan Nikolaj <51296436+snikolaj@users.noreply.github.com> Co-authored-by: Anton Kesy Co-authored-by: Ishan Jain Co-authored-by: Krishna Vivek Vitta <84629581+krishnacx@users.noreply.github.com> Co-authored-by: icyerasor Co-authored-by: Blake-Madden <66873089+Blake-Madden@users.noreply.github.com> Co-authored-by: vmsteiner <107506233+vmsteiner@users.noreply.github.com> Co-authored-by: Andrew Zipperer <47086307+zipperer@users.noreply.github.com> Co-authored-by: Wes Bryie Co-authored-by: Craig Loewen Co-authored-by: Frans van Dorsselaer <17404029+dorssel@users.noreply.github.com> Co-authored-by: Keith Horton Co-authored-by: Drew Batchelor (he/him) --- .github/ISSUE_TEMPLATE/doc-issue.yml | 63 ++++++++++++++++++++++++++++ WSL/connect-usb.md | 38 ++++++++--------- WSL/docfx.json | 18 +++++--- WSL/media/wsl-icon.svg | 32 ++++++++++++++ WSL/wsl-config.md | 24 ++++++----- 5 files changed, 139 insertions(+), 36 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/doc-issue.yml create mode 100644 WSL/media/wsl-icon.svg diff --git a/.github/ISSUE_TEMPLATE/doc-issue.yml b/.github/ISSUE_TEMPLATE/doc-issue.yml new file mode 100644 index 00000000..77a6b454 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/doc-issue.yml @@ -0,0 +1,63 @@ +name: Post a documentation issue +title: Contribute Feedback +description: >- + Post an issue specific to WSL documentation. +labels: + - "needs-triage" +body: + - type: markdown + attributes: + value: "## Enter your feedback" + - type: markdown + attributes: + value: Select the issue type, and describe the issue in the text box below. Add as much detail as needed to help us resolve the issue. + - type: dropdown + id: issue-type + attributes: + label: Type of issue + options: + - Typo + - Code doesn't work + - Missing information + - Outdated article + - Other (describe below) + validations: + required: true + - type: textarea + id: userfeedback + validations: + required: true + attributes: + label: Feedback + description: Provide details that will add context on what should be updated in the documentation. Additional details not needed for typos, grammar, formatting, etc. For technical or factual errors, please include code snippets and output to show how the documentation is incorrect. + - type: markdown + attributes: + value: "## Article information" + - type: markdown + attributes: + value: "*Don't modify the following fields*. They are automatically filled in for you. Doing so will disconnect your issue from the affected article. *Don't edit them*." + - type: input + id: pageUrl + validations: + required: true + attributes: + label: Page URL + - type: input + id: contentSourceUrl + validations: + required: true + attributes: + label: Content source URL + - type: input + id: author + validations: + required: true + attributes: + label: Author + description: GitHub Id of the author + - type: input + id: documentVersionIndependentId + validations: + required: true + attributes: + label: Document Id \ No newline at end of file diff --git a/WSL/connect-usb.md b/WSL/connect-usb.md index c85ebeeb..8a5d2920 100644 --- a/WSL/connect-usb.md +++ b/WSL/connect-usb.md @@ -1,7 +1,7 @@ --- title: Connect USB devices description: Learn how to connect a USB device to your WSL 2 Linux distribution using usbipd-win. -ms.date: 11/20/2023 +ms.date: 01/04/2024 ms.topic: article --- @@ -14,9 +14,9 @@ Setting up the USB/IP project on your Windows machine will enable common develop ## Prerequisites - Running Windows 11 (Build 22000 or later). *(Windows 10 support is possible, see note below).* -- A machine with an x64/x86 processor is required. (Arm64 is currently not supported with usbipd-win). +- A machine with an x64 processor is required. (x86 and Arm64 are currently not supported with usbipd-win). +- WSL is [installed and set up with the latest version](./install.md). - Linux distribution installed and [set to WSL 2](./basic-commands.md#set-wsl-version-to-1-or-2). -- Running [Linux kernel 5.10.60.1 or later](./kernel-release-notes.md). > [!NOTE] > To check your Windows version and build number, select **Windows logo key + R**, type **winver**, select **OK**. You can update to the latest Windows version by selecting **Start** > **Settings** > **Windows Update** > **[Check for updates](ms-settings:windowsupdate)**. @@ -42,33 +42,29 @@ This will install: - A command line tool `usbipd`. The location of this tool will be added to the PATH environment variable. - A firewall rule called `usbipd` to allow all local subnets to connect to the service. You can modify this firewall rule to fine tune access control. -## Install the USBIP tools and hardware database in Linux - -Once the USB/IP project has completed installing, you will need to install the user space tools and a database of USB hardware identifiers. These instructions are for Ubuntu — [other distributions may require a different usbip client package](https://github.com/dorssel/usbipd-win/wiki/WSL-support#usbip-client-tools). +## Attach a USB device -On Ubuntu, run this command: +Before attaching your USB device, ensure that a WSL command line is open. This will keep the WSL 2 lightweight VM active. -```bash -sudo apt install linux-tools-generic hwdata -sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20 -``` +> [!NOTE] +> This doc assumes that you have [`usbipd-win 4.0.0` or higher installed](https://github.com/dorssel/usbipd-win/releases/latest) -At this point a service is running on Windows to share USB devices, and the necessary tools are installed in WSL to attach to shared devices. +1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the following command. Once the devices are listed, select and copy the bus ID of the device you’d like to attach to WSL. -## Attach a USB device - -Before attaching your USB device, ensure that a WSL command line is open. This will keep the WSL 2 lightweight VM active. + ```powershell + usbipd list + ``` -1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the command: +2. Before attaching the USB device, the command `usbipd bind` must be used to share the device, allowing it to be attached to WSL. This requires administrator privileges. Select the bus ID of the device you would like to use in WSL and run the following command. After running the command, verify that the device is shared using the command `usbipd list` again. ```powershell - usbipd wsl list + usbipd bind --busid 4-4 ``` -2. Select the bus ID of the device you’d like to attach to WSL and run this command. You’ll be prompted by WSL for a password to run a sudo command. The Linux distribution to be attached must be your default distribution. (See the [Basic commands for WSL](./basic-commands.md#set-default-linux-distribution) doc to change your default distribution). +3. To attach the USB device, run the following command. (You no longer need to use an elevated administrator prompt.) Ensure that a WSL command prompt is open in order to keep the WSL 2 lightweight VM active. Note that as long as the USB device is attached to WSL, it cannot be used by Windows. Once attached to WSL, the USB device can be used by any distribution running as WSL 2. Verify that the device is attached using `usbipd list`. From the WSL prompt, run `lsusb` to verify that the USB device is listed and can be interacted with using Linux tools. ```powershell - usbipd wsl attach --busid + usbipd attach --wsl --busid ``` 3. Open Ubuntu (or your preferred WSL command line) and list the attached USB devices using the command: @@ -79,10 +75,10 @@ Before attaching your USB device, ensure that a WSL command line is open. This You should see the device you just attached and be able to interact with it using normal Linux tools. Depending on your application, you may need to configure udev rules to allow non-root users to access the device. -4. Once you are done using the device in WSL, you can either physically disconnect the USB device or run this command from PowerShell in *administrator* mode: +4. Once you are done using the device in WSL, you can either physically disconnect the USB device or run this command from PowerShell: ```powershell - usbipd wsl detach --busid + usbipd detach --busid ``` To learn more about how this works, see the [Windows Command Line Blog](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works) and the [usbipd-win repo on GitHub](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works). diff --git a/WSL/docfx.json b/WSL/docfx.json index 5fb867dd..bacfd9bb 100644 --- a/WSL/docfx.json +++ b/WSL/docfx.json @@ -21,7 +21,8 @@ "files": [ "**/*.png", "**/*.gif", - "**/*.jpg" + "**/*.jpg", + "**/*.svg" ], "exclude": [ "**/obj/**", @@ -35,10 +36,17 @@ "breadcrumb_path": "/windows/wsl/breadcrumb/toc.json", "uhfHeaderId": "MSDocsHeader-Windows", "recommendations" : true, - "feedback_system": "GitHub", - "feedback_github_repo": "MicrosoftDocs/WSL", - "ms.prod": "dev-environment", - "ms.technology": "windows-subsystem-for-linux", + "feedback_product_url": "https://github.com/Microsoft/wsl/issues", + "feedback_system": "OpenSource", + "open_source_feedback_contributorGuideUrl": "https://learn.microsoft.com/contribute/content/how-to-write-quick-edits", + "open_source_feedback_issueTitle": "", + "open_source_feedback_issueLabels": "needs-triage", + "open_source_feedback_issueUrl": "https://github.com/MicrosoftDocs/wsl/issues/new?template=doc-issue.yml", + "open_source_feedback_productLogoLightUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg", + "open_source_feedback_productLogoDarkUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg", + "open_source_feedback_productName": "Windows Subsystem for Linux", + "ms.service": "dev-environment", + "ms.subservice": "windows-subsystem-for-linux", "author": "craigloewen-msft", "ms.author": "crloewen", "searchScope": ["WSL"], diff --git a/WSL/media/wsl-icon.svg b/WSL/media/wsl-icon.svg new file mode 100644 index 00000000..0e7c0d37 --- /dev/null +++ b/WSL/media/wsl-icon.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index 03f5264c..f587b070 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/10/2023 +ms.date: 01/17/2024 ms.topic: article ms.custom: seo-windows-dev adobe-target: true @@ -221,15 +221,10 @@ This file can contain the following options that affect the VM that powers any W | debugConsole | boolean* | `false` | Boolean to turn on an output console Window that shows the contents of `dmesg` upon start of a WSL 2 distro instance. Only available for Windows 11.| | nestedVirtualization | boolean* | `true` | Boolean to turn on or off nested virtualization, enabling other nested VMs to run inside WSL 2. Only available for Windows 11.| | vmIdleTimeout | number* | `60000` | The number of milliseconds that a VM is idle, before it is shut down. Only available for Windows 11.| -|networkingMode**| string | NAT | If the value is `mirrored` then this turns on mirrored networking mode. Default or unrecognized strings result in NAT networking. | -|firewall**| bool | true | Setting this to true allows the Windows Firewall rules, as well as rules specific to Hyper-V traffic, to filter WSL network traffic. | -|dnsTunneling**| bool | false | Changes how DNS requests are proxied from WSL to Windows | -|autoProxy*| bool | false | Enforces WSL to use Windows’ HTTP proxy information | -|useWindowsDnsCache**| bool | false | Only applicable when `experimental.dnsTunneling` is set to true. When this option is set to false, DNS requests tunneled from Linux will bypass cached names within Windows to always put the requests on the wire. | -|bestEffortDnsParsing**| bool | false | Only applicable when `experimental.dnsTunneling` is set to true. When set to true, Windows will extract the question from the DNS request and attempt to resolve it, ignoring the unknown records. | -|initialAutoProxyTimeout*| string | 1000 | Only applicable when `experimental.autoProxy` is set to true. Configures how long (in milliseconds) WSL will wait for retrieving HTTP proxy information when starting a WSL container. If proxy settings are resolved after this time, the WSL instance must be restarted to use the retrieved proxy settings. | -|ignoredPorts**| string | null | Only applicable when `experimental.networkingMode` is set to `mirrored`. Specifies which ports Linux applications can bind to, even if that port is used in Windows. This enables applications to listen on a port for traffic purely within Linux, so those applications are not blocked even when that port is used for other purposes on Windows. For example, WSL will allow binding to port 53 in Linux for Docker Desktop, as it is listening only to requests from within the Linux container. Should be formatted in a comma separated list, e.g: `3000,9000,9090` | -|hostAddressLoopback**| bool | false | Only applicable when `experimental.networkingMode` is set to `mirrored`. When set to True, will allow the Container to connect to the Host, or the Host to connect to the Container, by an IP address that's assigned to the Host. Note that the 127.0.0.1 loopback address can always be used - this option allows for all additionally assigned local IP addresses to be used as well. | +| networkingMode** | string | NAT | If the value is `mirrored` then this turns on mirrored networking mode. Default or unrecognized strings result in NAT networking. | +| firewall** | bool | true | Setting this to true allows the Windows Firewall rules, as well as rules specific to Hyper-V traffic, to filter WSL network traffic. | +| dnsTunneling** | bool | false | Changes how DNS requests are proxied from WSL to Windows | +| autoProxy* | bool | false | Enforces WSL to use Windows’ HTTP proxy information | Entries with the `path` value must be Windows paths with escaped backslashes, e.g: `C:\\Temp\\myCustomKernel` @@ -249,6 +244,15 @@ These settings are opt-in previews of experimental features that we aim to make |:----|:----|:----|:----| |`autoMemoryReclaim`| string | disabled | Automatically releases cached memory after detecting idle CPU usage. Set to `gradual` for slow release, and `dropcache` for instant release of cached memory. | |`sparseVhd`| bool | false | When set to true, any newly created VHD will be set to sparse automatically. | +|`useWindowsDnsCache`**| bool | false | Only applicable when `wsl2.dnsTunneling` is set to true. When this option is set to false, DNS requests tunneled from Linux will bypass cached names within Windows to always put the requests on the wire. | +|`bestEffortDnsParsing`**| bool | false | Only applicable when `wsl2.dnsTunneling` is set to true. When set to true, Windows will extract the question from the DNS request and attempt to resolve it, ignoring the unknown records. | +|`initialAutoProxyTimeout`*| string | 1000 | Only applicable when `wsl2.autoProxy` is set to true. Configures how long (in milliseconds) WSL will wait for retrieving HTTP proxy information when starting a WSL container. If proxy settings are resolved after this time, the WSL instance must be restarted to use the retrieved proxy settings. | +|`ignoredPorts`**| string | null | Only applicable when `wsl2.networkingMode` is set to `mirrored`. Specifies which ports Linux applications can bind to, even if that port is used in Windows. This enables applications to listen on a port for traffic purely within Linux, so those applications are not blocked even when that port is used for other purposes on Windows. For example, WSL will allow binding to port 53 in Linux for Docker Desktop, as it is listening only to requests from within the Linux container. Should be formatted in a comma separated list, e.g: `3000,9000,9090` | +|`hostAddressLoopback`**| bool | false | Only applicable when `wsl2.networkingMode` is set to `mirrored`. When set to True, will allow the Container to connect to the Host, or the Host to connect to the Container, by an IP address that's assigned to the Host. Note that the 127.0.0.1 loopback address can always be used - this option allows for all additionally assigned local IP addresses to be used as well. | + +Entries with an * after the value type are only available on Windows 11. + +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. ## Example .wslconfig file