Issue resolutions from Nov23 (#1857)

* Resolve issues Nov 23 (#1848) * Reorganize, reword config doc * fix hostname command * Clarify to resolve #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 #1675 * Add note about VM architecture for WSL 2 Resolves #1573 * Update WSL 2 explainer * Add PS command Resolves #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 <jacob@wortmann.dk> Co-authored-by: Zhaoqiu Sheng <51221150+zhaoqiu-china@users.noreply.github.com>
MicrosoftDocs · Nov 28, 2023 · efd3429 · efd3429
1 parent e1b82b2
commit efd3429
Show file tree

Hide file tree

Showing 10 changed files with 35 additions and 31 deletions.
diff --git 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). 
 
-<br>
+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
@@ -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 <distribution name> <versionNumber>
 
 To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace `<distribution name>` with the name of the distribution and replace `<versionNumber>` 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 <Distribution Name> <InstallLocation> <FileName>
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <Version#>`, replacing `<Version#>` with either 1 or 2.
 
-To set the default Linux distribution used with the `wsl` command, enter: `wsl -s <DistributionName>` or `wsl --setdefault <DistributionName>`, replacing `<DistributionName>` 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 <DistributionName>` or `wsl --set-default <DistributionName>`, replacing `<DistributionName>` 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 <DistributionName>`, replacing `<DistributionName>` 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.