SEO updates to improve discoverability (MicrosoftDocs#1365)

* Add VS Code to gitignore

* SEO updates 1

* config updates and remove unused images

* Reformat, add more detailed sample

* Finish config samples

* Update WSL/wsl-config.md

Thank you!

Co-authored-by: Biswapriyo Nath <nathbappai@gmail.com>

* Fix image link

* SEO updates, remove config previews, add W11 notes, set redirect for user setup

* Anchor fixes and feedback updates

Co-authored-by: Biswapriyo Nath <nathbappai@gmail.com>

.openpublishing.redirection.json

@@ -52,7 +52,12 @@
     },
     {
       "source_path": "wsl/user_support.md",
-      "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-user-info",
+      "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "wsl/user-support.md",
+      "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password",
       "redirect_document_id": false
     }
   ]

WSL/basic-commands.md

@@ -1,155 +1,178 @@
 ---
 title: Basic commands for WSL
 description: Reference for the basic commands included with Windows Subsystem for Linux (WSL).
-keywords: wsl, install, BashOnWindows, bash, windows subsystem for linux, install ubuntu on windows, enable WSL2, linux on windows
-ms.date: 09/27/2021
+ms.date: 11/23/2021
 ms.topic: article
 ms.localizationpriority: high
 ---
 
-# Command reference for WSL
+# Basic commands for WSL
 
-The basic WSL commands below are listed in a format supported by PowerShell or Windows Command Prompt. To run these commands from a Bash / Linux distribution command line, you must replace `wsl` with `wsl.exe`.
+The WSL commands below are listed in a format supported by PowerShell or Windows Command Prompt. To run these commands from a Bash / Linux distribution command line, you must replace `wsl` with `wsl.exe`.
 
-## Basic commands
-
-The following basic commands are supported after [installing WSL](./install.md).
-
-### Install
+## Install
 
 ```powershell
 wsl --install
 ```
 
 Install WSL and the Ubuntu distribution of Linux. [Learn more](./install.md).
 
-### Install a specific Linux distribution
+## Install a specific Linux distribution
 
 ```powershell
 wsl --install --distribution <Distribution Name>
 ```
 
 Designate a distribution of Linux for installation besides the default (Ubuntu) by replacing `<Distribution Name>` with the name of the distribution. This command can also be entered as: `wsl -d <Distribution Name>`.
 
-### List available Linux distributions
+## List available Linux distributions
 
 ```powershell
 wsl --list --online
 ```
 
 See a list of the Linux distributions available through the online store. This command can also be entered as: `wsl -l -o`.
 
-### List installed Linux distributions
+## List installed Linux distributions
 
 ```powershell
 wsl --list --verbose
 ```
 
 See a list of the Linux distributions installed on your Windows machine, including the state (whether the distribution is running or stopped) and the version of WSL running the distribution (WSL 1 or WSL 2). [Comparing WSL 1 and WSL 2](./compare-versions.md). This command can also be entered as: `wsl -l -v`. Additional options that can be used with the list command include: `--all` to list all distributions, `--running` to list only distributions that are currently running, or `--quite` to only show distribution names.
 
-### Set WSL version to 1 or 2
+## Set WSL version to 1 or 2
 
 ```powershell
 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).
 
-### Set default WSL version
+## Set default WSL version
 
 ```powershell
 wsl --set-default-version <Version>
 ```
 
 To set a default version of WSL 1 or WSL 2, replacing `<Version>` 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).
 
-### Set default Linux distribution
+## Set default Linux distribution
 
 ```powershell
 wsl --set-default <Distribution Name>
 ```
 
 To set the default Linux distribution that WSL commands will use to run, replace `<Distribution Name>` with the name of your preferred Linux distribution.
 
-### Run a specific Linux distribution from PowerShell or CMD
+## Change directory to home
+
+```powershell
+wsl ~
+```
+
+The `~` can be used with wsl to start in the user's home directory. To jump from any directory back to home from within a WSL command prompt, you can use the command: `cd ~`.
+
+## Run a specific Linux distribution from PowerShell or CMD
 
 ```powershell
 wsl --distribution <Distribution Name> --user <User Name>
 ```
 
 To run a specific Linux distribution with a specific user, replace `<Distribution Name>` with the name of your preferred Linux distribution (ie. Debian) and `<User Name>` with the name of an existing user (ie. root). If the user doesn't exist in the WSL distribution, you will receive an error. To print the current user name, use the command `whoami`.
 
-### Update WSL
+## Update WSL
 
 ```powershell
 wsl --update
 ```
 
 Manually update the version of your WSL Linux kernel. You can also use the command: `wsl --update rollback` to rollback to a previous version of the WSL Linux kernel.
 
-### Check WSL status
+## Check WSL status
 
 ```powershell
 wsl --status
 ```
 
 See general information about your WSL configuration, such as default distribution type, default distribution, and kernel version.
 
-### Help command
+## Help command
 
 ```powershell
 wsl --help
 ```
 
 See a list of options and commands available with WSL.
 
-### Home directory
+## Run as a specific user
 
 ```powershell
-wsl ~
+wsl -u <Username>`, `wsl --user <Username>
 ```
 
-The `~` can be used with wsl to start in the user's home directory. To jump from any directory back to home from within a WSL command prompt, you can use the command: `cd ~`.
+To run WSL as a specified user, replace `<Username>` with the name of a user that exists in the WSL distribution.
 
-### Shutdown
+## Change the default user for a distribution
+
+```powershell
+<DistributionName> config --default-user <Username>
+```
+
+Change the default user for your distribution log-in. The user has to already exist inside the distribution in order to become the default user.
+
+For example:
+`ubuntu config --default-user johndoe` would change the default user for the Ubuntu distribution to the "johndoe" user.
+
+> [!NOTE]
+> If you are having trouble figuring out the name of your distribution, use the command `wsl -l`.
+
+## Shutdown
 
 ```powershell
 wsl --shutdown
 ```
 
 Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. This command may be necessary in instances that require you to restart the WSL 2 virtual machine environment, such as [changing memory usage limits](./vhd-size.md) or making a change to your [.wslconfig file](./manage.md#).
 
-### Terminate
+## Terminate
 
 ```powershell
 wsl --terminate <Distribution Name>
 ```
 
 To terminate the specified distribution, or stop it from running, replace `<Distribution Name>` with the name of the targeted distribution.
 
-### Export a distribution to a TAR file
+## Export a distribution to a TAR file
 
 ```powershell
 wsl --export <Distribution Name> <FileName>
 ```
 
 Exports the distribution to a tar file. The filename can be - for standard output.
 
-### Import a new distribution
+## Import a new distribution
 
 ```powershell
 wsl --import <Distribution Name> <InstallLocation> <FileName>
 ```
 
 Imports the specified tar file as a new distribution. The filename can be - for standard input. The `--version` option can also be used with this command to designate whether the imported distribution will run on WSL 1 or WSL 2.
 
-### Unregister or uninstall a Linux distribution
+## Unregister or uninstall a Linux distribution
+
+While Linux distributions can be installed through the Microsoft Store, they can't be uninstalled through the store.
+
+To unregister and uninstall a WSL distribution:
 
 ```powershell
-wsl --unregister <Distribution Name>
+wsl --unregister <DistributionName>
 ```
 
-Unregister or uninstall the specific distribution by replacing `<Distribution Name>` with the name of the targeted distribution. This will remove the distribution from WSL and delete all of the associated data. You can also uninstall the Linux distribution app on your Windows machine just like any other store application.
+Replacing `<DistributionName>` with the name of your targeted Linux distribution will unregister that distribution from WSL so it can be reinstalled or cleaned up. **Caution:** Once unregistered, all data, settings, and software associated with that distribution will be permanently lost.  Reinstalling from the store will install a clean copy of the distribution. For example, `wsl --unregister Ubuntu` would remove Ubuntu from the distributions available in WSL.  Running `wsl --list` will reveal that it is no longer listed.
+
+You can also uninstall the Linux distribution app on your Windows machine just like any other store application. To reinstall, find the distribution in the Microsoft Store and select "Launch".
 
 ## Mount a disk or device
 

WSL/compare-versions.md

@@ -1,15 +1,15 @@
 ---
 title: Comparing WSL 1 and WSL 2
-description: Compare version 1 and version 2 of the Windows Subsystem for Linux. Learn whats new in WSL 2.
-keywords: BashOnWindows, bash, wsl, windows, windowssubsystem, gnu, linux, ubuntu, debian, suse, windows 10, UX changes, WSL 2, linux kernel, network applications, localhost, IPv6, Virtual Hardware Disk, VHD, VHD limitations, VHD error
-ms.date: 09/27/2021
+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/22/2021
 ms.topic: conceptual
+ms.custom: seo-windows-dev
 ms.localizationpriority: high
 ---
 
 # Comparing WSL 1 and WSL 2
 
-The primary difference and reasons for updating the Windows Subsystem for Linux from WSL 1 to WSL 2 are to:
+The primary reasons to [update from WSL 1 to WSL 2](./install.md#upgrade-version-from-wsl-1-to-wsl-2) are to:
 
 - **increase file system performance**,
 - **support full system call compatibility**.
@@ -19,6 +19,8 @@ WSL 2 uses the latest and greatest in virtualization technology to run a Linux k
 > [!div class="nextstepaction"]
 > [Install WSL](install.md)
 
+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.
+
 ## Comparing features
 
 Feature | WSL 1 | WSL 2
@@ -32,7 +34,7 @@ Feature | WSL 1 | WSL 2
  Full system call compatibility| ❌ | ✅
  Performance across OS file systems| ✅ | ❌
 
-As you can tell from the comparison table above, the WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems.
+As you can tell from the comparison table above, the WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems, which can be addressed by storing your project files on the same operating system as the tools you are running to work on the project.
 
 WSL 2 is only available in Windows 10, Version 1903, Build 18362 or higher. Check your Windows version by selecting the **Windows logo key + R**, type **winver**, select **OK**. (Or enter the `ver` command in Windows Command Prompt). You may need to [update to the latest Windows version](ms-settings:windowsupdate). For builds lower than 18362, WSL is not supported at all.
 
@@ -59,6 +61,8 @@ The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, b
 
 The [WSL 2 Linux kernel is open source](https://github.com/microsoft/WSL2-Linux-Kernel). If you'd like to learn more, check out the blog post [Shipping a Linux Kernel with Windows](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/) written by the team that built it.
 
+Learn more in the [Release Notes for Windows Subsystem for Linux kernel](./kernel-release-notes.md).
+
 ### Increased file IO performance
 
 File intensive operations like git clone, npm install, apt update, apt upgrade, and more are all noticeably faster with WSL 2.
@@ -85,6 +89,8 @@ 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 will with WSL 2, but that other versions may experience issues.)
+- 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 it's 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]
 > Consider trying the VS Code [Remote WSL Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) to enable you to store your project files on the Linux file system, using Linux command line tools, but also using VS Code on Windows to author, edit, debug, or run your project in an internet browser without any of the performance slow-downs associated with working across the Linux and Windows file systems. [Learn more](tutorials/wsl-vscode.md).

WSL/index.md

@@ -1,30 +1,32 @@
 ---
 title: Windows Subsystem for Linux Documentation
-description: Explore the Windows Subsystem for Linux documentation.
-keywords: wsl docs, BashOnWindows, bash, wsl, windows, windowssubsystem, gnu, linux
-ms.topic: article
-ms.date: 09/27/2021
+description: Overview of the Windows Subsystem for Linux documentation.
+ms.topic: overview
+ms.date: 12/06/2021
 ms.localizationpriority: high
+ms.custom: seo-windows-dev
 ---
 
 # Windows Subsystem for Linux Documentation
 
-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 dual-boot setup.
+Windows Subsystem for Linux (WSL) 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 dual-boot setup.
 
 > [!div class="nextstepaction"]
 > [Install WSL](install.md)
 
 ## Learn more
 
-* [What is the Windows Subsystem for Linux?](about.md)
+* [What is the Windows Subsystem for Linux (WSL)?](about.md)
 * [What's new with WSL 2?](compare-versions.md#whats-new-in-wsl-2)
-* [Compare WSL 2 and WSL 1](compare-versions.md)
-* [Read frequently asked questions](faq.yml)
+* [Comparing WSL 1 and WSL 2](compare-versions.md)
+* [Frequently Asked Questions](faq.yml)
 
 ## Get started
 
 * [Install WSL](install.md)
 * [Install Linux on Windows Server](install-on-server.md)
+* [Manual install steps](install-manual.md)
+* [Best practices for setting up a WSL development environment](./setup/environment.md)
 
 ## Try WSL preview features by joining the Windows Insiders Program
 
@@ -40,12 +42,7 @@ To try the most recent features or updates to WSL, join the [Windows Insiders Pr
 * [Command-Line blog](https://blogs.msdn.microsoft.com/commandline/) (Active)
 * [Windows Subsystem for Linux Blog](/archive/blogs/wsl/) (Historical)
 
-## Posts and articles
-
-* [Run Bash on Ubuntu on Windows](https://blogs.windows.com/buildingapps/2016/03/30/run-bash-on-ubuntu-on-windows/)
-* [Developers Can Run Bash And Usermode Ubuntu Linux Binaries On Windows 10](https://www.hanselman.com/blog/DevelopersCanRunBashShellAndUsermodeUbuntuLinuxBinariesOnWindows10.aspx)
-* [Ubuntu on Windows – The Ubuntu Userspace for Windows Developers](https://insights.ubuntu.com/2016/03/30/ubuntu-on-windows-the-ubuntu-userspace-for-windows-developers/)
-
 ## Provide feedback
 
-* [GitHub issue tracker](https://github.com/Microsoft/BashOnWindows/issues)
+* [GitHub issue tracker: WSL](https://github.com/microsoft/WSL/issues)
+* [GitHub issue tracker: WSL documentation](https://github.com/MicrosoftDocs/WSL/issues)

WSL/install-manual.md

@@ -98,7 +98,7 @@ wsl --set-default-version 2
 
 The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for a minute or two for files to de-compress and be stored on your PC. All future launches should take less than a second.
 
-You will then need to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info).
+You will then need to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password).
 
 ![Ubuntu unpacking in the Windows console](media/UbuntuInstall.png)
 
@@ -153,7 +153,7 @@ Add-AppxPackage .\app_name.appx
 
 If you are using Windows server, or run into problems running the command above you can find the alternate install instructions on the [Windows Server](install-on-server.md) documentation page to install the `.appx` file by changing it to a zip file.
 
-Once your distribution is installed, follow the instructions to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info).
+Once your distribution is installed, follow the instructions to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password).
 
 ## Install Windows Terminal (optional)
 

WSL/install-on-server.md

@@ -52,4 +52,4 @@ $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User")
 
 You can now launch your distribution from any path by typing `<DistributionName>.exe`. For example: `ubuntu.exe`.
 
-Once installation is complete, you can [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info).
+Once installation is complete, you can [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password).