Clean up and remove unneeded pages (#916)

* Update kernel-release-notes.md

* Update install with step #s and kernel download (#912)

* Update install with step #s and kernel download

* fix anchor link

* Clean up and reorganize

* Add Windows Terminal section

* Update install with step #s and kernel download

* fix anchor link

* Clean up and reorganize

* Add Windows Terminal section

* Add redirects, update toc to remove whats new wsl2

* remove version specific link

* Fix redirects missing file type

* Add anchor link to kernel redirect

* Feedback update on wording

* Change compare topic type, remove links, reorg

Co-authored-by: Craig Loewen <[email protected]>

Author: mattwojo

.openpublishing.redirection.json

@@ -29,6 +29,21 @@
       "source_path": "wsl/wsl2-install.md",
       "redirect_url": "install-win10",
       "redirect_document_id": false
+    },
+    {
+      "source_path": "wsl/wsl2-about.md",
+      "redirect_url": "compare-versions#whats-new-in-wsl-2",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "wsl/wsl2-kernel.md",
+      "redirect_url": "install-win10#step-4---download-the-linux-kernel-update-package",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "wsl/wsl2-index.md",
+      "redirect_url": "compare-versions#whats-new-in-wsl-2",
+      "redirect_document_id": false
     }
   ]
 }

WSL/build-custom-distro.md

@@ -2,39 +2,43 @@
 title: Build a Custom Linux Distro for WSL
 description: Learn how to create a custom Linux distribution for Windows Subsystem for Linux.
 keywords: BashOnWindows, bash, wsl, windows, windows subsystem, distro, custom
-ms.date: 03/27/2018
+ms.date: 09/15/2020
 ms.topic: article
-ms.assetid: a5095219-0c82-4ce5-9a6d-5c2fc00835a3
-ms.custom: seodec18
 ---
 
-# Creating a Custom Linux Distro for WSL
+# Creating a Custom Linux Distribution for WSL
 
 Use our open source WSL sample to build WSL distro packages for the Microsoft Store and/or to create custom Linux distro packages for sideloading. You can find the [distro launcher repo](https://github.com/Microsoft/WSL-DistroLauncher) on GitHub.
 
 This project enables:
-* Linux distribution maintainers to package and submit a Linux distribution as an appx that runs on WSL
-* Developers to create custom Linux distributions that can be sideloaded onto their dev machine
+
+- Linux distribution maintainers to package and submit a Linux distribution as an appx that runs on WSL
+- Developers to create custom Linux distributions that can be sideloaded onto their dev machine
 
 ## Background
+
 We distribute Linux distros for WSL as UWP applications through the Microsoft Store. You can install those applications that will then run on WSL - the subsystem that sits in the Windows kernel. This delivery mechanism has many benefits as discussed in an [earlier blog post](https://blogs.msdn.microsoft.com/commandline/2017/07/10/ubuntu-now-available-from-the-windows-store/).
 
 ## Sideloading a Custom Linux Distro Package
+
 You can create a custom Linux distro package as an application to sideload on your personal machine. Please note that your custom package would not be distributed through the Microsoft Store unless you submit as a distribution maintainer.
 To set up your machine to sideload apps, you will need to enable this in the system settings under “For Developers”.  Be sure to either have developer mode, or sideload apps selected
 
 ## For Linux Distro Maintainers
+
 To submit to the Store, you will need to work with us to receive publishing approval. If you are a Linux distribution owner interested in adding your distribution to the Microsoft Store, please contact [email protected].
 
 ## Getting Started
+
 Follow the instructions on the [Distro Launcher GitHub repo](https://github.com/Microsoft/WSL-DistroLauncher) to create a custom Linux distro package.
 
- 
 ## Team Blogs
-*  [Open Sourcing a WSL Sample for Linux Distribution Maintainers and Sideloading Custom Linux Distributions](https://blogs.msdn.microsoft.com/commandline/2018/03/26/wsl-distro-launcher/)
-* [Command-Line blog](https://blogs.msdn.microsoft.com/commandline/)
+
+-  [Open Sourcing a WSL Sample for Linux Distribution Maintainers and Sideloading Custom Linux Distributions](https://blogs.msdn.microsoft.com/commandline/2018/03/26/wsl-distro-launcher/)
+- [Command-Line blog](https://blogs.msdn.microsoft.com/commandline/)
 
 ## Provide Feedback
-* [Distro Launcher GitHub repo](https://github.com/Microsoft/WSL-DistroLauncher)
-* [GitHub issue tracker for WSL](https://github.com/Microsoft/BashOnWindows/issues)
-* [Command-line UserVoice portal](https://wpdev.uservoice.com/forums/266908-command-prompt-console-bash-on-ubuntu-on-windo/category/161892-bash)
+
+- [Distro Launcher GitHub repo](https://github.com/Microsoft/WSL-DistroLauncher)
+- [GitHub issue tracker for WSL](https://github.com/Microsoft/BashOnWindows/issues)
+- [Command-line UserVoice portal](https://wpdev.uservoice.com/forums/266908-command-prompt-console-bash-on-ubuntu-on-windo/category/161892-bash)

WSL/compare-versions.md

@@ -1,17 +1,20 @@
 ---
 title: Comparing WSL 2 and WSL 1
-description: Compare version 1 and version 2 of the Windows Subsystem for Linux. WSL 2 runs an actual Linux kernel, increasing speed and full system call compatibility. WSL 1 works better if your working across BOTH Windows and Linux file systems.
+description: Compare version 1 and version 2 of the Windows Subsystem for Linux. Learn whats new in WSL 2 - actual Linux kernel, faster speed, full system call compatibility. WSL 1 works better if your storing files across operating file systems. You can expand the size of your WSL 2 Virtual Hardware Disk (VHD).
 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: 07/22/2020
-ms.topic: article
+ms.date: 09/15/2020
+ms.topic: conceptual
 ms.localizationpriority: high
 ---
 
 # Comparing WSL 1 and WSL 2
 
-The primary goals of updating the Windows Subsystem for Linux to a new version are to **increase file system performance** and support **full system call compatibility**. 
+The primary difference and reasons for updating the Windows Subsystem for Linux from WSL 1 to WSL 2 are to:
 
-WSL 2 uses the latest and greatest in virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). However, WSL 2 is not a traditional VM experience. [Learn more about the WSL 2 architecture](#wsl-2-architecture).
+- **increase file system performance**,
+- **support full system call compatibility**.
+
+WSL 2 uses the latest and greatest in virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). However, WSL 2 is not a traditional VM experience.
 
 ## Comparing features
 
@@ -26,41 +29,35 @@ Feature | WSL 1 | WSL 2
  Full system call compatibility| ❌ | ✅
  Performance across OS file systems| ✅ | ❌
 
-Already using WSL 1 and want to upgrade to WSL 2? Follow the instructions to [update to WSL 2](./install-win10.md#update-to-wsl-2)!
-
-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.
-
-> [!NOTE]
-> WSL 2 will work with [VMWare 15.5.5+](https://blogs.vmware.com/workstation/2020/05/vmware-workstation-now-supports-hyper-v-mode.html) and [VirtualBox 6+](https://www.virtualbox.org/wiki/Changelog-6.0).
+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.
 
-## Use the Linux file system for faster performance
+## Performance across OS file systems
 
-In order to optimize for the fastest performance speed, be sure to store your project files in the Linux file system (not the Windows file system).
+We recommend against working across operating systems with your files, unless you have a specific reason for doing so. For the fastest performance speed, store your files in the WSL file system if you are working in a Linux command line (Ubuntu, OpenSUSE, etc). If your working in a Windows command line (PowerShell, Command Prompt), store your files in the Windows file system.
 
 For example, when storing your WSL project files:
 
-* Use the Linux file system root directory: `\\wsl$\Ubuntu-18.04\home\<user name>\Project`
-* Not the Windows file system root directory: `C:\Users\<user name>\Project`
-
-Project files that you are working with using a WSL distribution (like Ubuntu) must be in the Linux root file system to take advantage of faster file system access.
+- Use the Linux file system root directory: `\\wsl$\Ubuntu-18.04\home\<user name>\Project`
+- Not the Windows file system root directory: `C:\Users\<user name>\Project`
 
 You can access your Linux root file system with Windows apps and tools like File Explorer. Try opening a Linux distribution (like Ubuntu), be sure that you are in the Linux home directory by entering this command: `cd ~`. Then open your Linux file system in File Explorer by entering *(don't forget the period at the end)*: `explorer.exe .`
 
-## Exceptions for using WSL 1 rather than WSL 2
+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.
 
-We recommend that you use WSL 2 as it offers faster performance and 100% system call compatibility. However, there are a few specific scenarios where you might prefer using WSL 1. Consider using WSL 1 if:
+> [!NOTE]
+> WSL 2 will work with [VMWare 15.5.5+](https://blogs.vmware.com/workstation/2020/05/vmware-workstation-now-supports-hyper-v-mode.html) and [VirtualBox 6+](https://www.virtualbox.org/wiki/Changelog-6.0).
 
-* Your project files must be stored in the Windows file system.
-  * If you will be using your WSL Linux distribution to access project files on the Windows file system, and these files cannot be stored on the Linux file system, you will achieve faster performance across the OS files systems by using WSL 1.
-* A project which requires cross-compilation using both Windows and Linux tools on the same files.
-  * File performance across the Windows and Linux operating systems is faster in WSL 1 than WSL 2, so if you are using Windows applications to access Linux files, you will currently achieve faster performance with WSL 1.
+## Whats new in WSL 2
 
-> [!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](https://code.visualstudio.com/docs/remote/wsl).
+WSL 2 is a major overhaul of the underlying architecture and uses virtualization technology and a Linux kernel to enable new features. The primary goals of this update are to increase file system performance and add full system call compatibility.
+
+- [WSL 2 system requirements](./install-win10.md#step-2---update-to-wsl-2)
+- [Update from WSL 1 to WSL 2](./install-win10.md#step-2---update-to-wsl-2)
+- [Frequently Asked Questions about WSL 2](./wsl2-faq.md)
 
-## WSL 2 architecture
+### WSL 2 architecture
 
-A traditional VM experience can be slow to boot up, is isolated, consumes lots of resources, and requires your time to manage it. WSL 2 does not have these attributes.
+A traditional VM experience can be slow to boot up, is isolated, consumes a lot of resources, and requires your time to manage it. WSL 2 does not have these attributes.
 
 WSL 2 provides the benefits of WSL 1, including seamless integration between Windows and Linux, fast boot times, a small resource footprint, and requires no VM configuration or management. While WSL 2 does use a VM, it is managed and run behind the scenes, leaving you with the same user experience as WSL 1.
 
@@ -80,14 +77,26 @@ The actual speed increase will depend on which app you're running and how it is
 
 Linux binaries use system calls to perform functions such as accessing files, requesting memory, creating processes, and more. Whereas WSL 1 used a translation layer that was built by the WSL team, WSL 2 includes its own Linux kernel with full system call compatibility. Benefits include:
 
-* A whole new set of apps that you can run inside of WSL, such as **[Docker](https://code.visualstudio.com/blogs/2020/03/02/docker-in-wsl2)** and more.
+- A whole new set of apps that you can run inside of WSL, such as **[Docker](tutorials/wsl-containers.md)** and more.
 
-* Any updates to the Linux kernel are immediately ready for use. (You don't have to wait for the WSL team to implement updates and add the changes).
+- Any updates to the Linux kernel are immediately ready for use. (You don't have to wait for the WSL team to implement updates and add the changes).
 
 ### WSL 2 uses a smaller amount of memory on startup
 
 WSL 2 uses a lightweight utility VM on a real Linux kernel with a small memory footprint. The utility will allocate Virtual Address backed memory on startup. It is configured to start with a smaller proportion of your total memory that what was required for WSL 1.
 
+## Exceptions for using WSL 1 rather than WSL 2
+
+We recommend that you use WSL 2 as it offers faster performance and 100% system call compatibility. However, there are a few specific scenarios where you might prefer using WSL 1. Consider using WSL 1 if:
+
+- Your project files must be stored in the Windows file system. WSL 1 offers faster access to files mounted from Windows.
+  - If you will be using your WSL Linux distribution to access project files on the Windows file system, and these files cannot be stored on the Linux file system, you will achieve faster performance across the OS files systems by using WSL 1.
+- A project which requires cross-compilation using both Windows and Linux tools on the same files.
+  - File performance across the Windows and Linux operating systems is faster in WSL 1 than WSL 2, so if you are using Windows applications to access Linux files, you will currently achieve faster performance with WSL 1.
+
+> [!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).
+
 ## Accessing network applications
 
 ### Accessing Linux networking apps from Windows (localhost)
@@ -98,14 +107,14 @@ However, if you are running an older version of Windows (Build 18945 or less), y
 
 To find the IP address of the virtual machine powering your Linux distribution:
 
-* From your WSL distribution (ie Ubuntu), run the command: `ip addr`
-* Find and copy the address under the `inet` value of the `eth0` interface.
-* If you have the grep tool installed, find this more easily by filtering the output with the command: `ip addr | grep eth0`
-* Connect to your Linux server using this IP address.
+- From your WSL distribution (ie Ubuntu), run the command: `ip addr`
+- Find and copy the address under the `inet` value of the `eth0` interface.
+- If you have the grep tool installed, find this more easily by filtering the output with the command: `ip addr | grep eth0`
+- Connect to your Linux server using this IP address.
 
 The picture below shows an example of this by connecting to a Node.js server using the Edge browser.
 
-![Accessing Linux network applications from Windows](media/wsl2-network-w2l.jpg)
+![Connect to NodeJS server with Edge](media/wsl2-network-w2l.jpg)
 
 ### Accessing Windows networking apps from Linux (host IP)
 
@@ -116,7 +125,7 @@ If you want to access a networking app running on Windows (for example an app ru
 
 The picture below shows an example of this by connecting to a Node.js server running in Windows via curl.
 
-![Accessing Linux network applications from Windows](media/wsl2-network-l2w.png)
+![Connect to NodeJS server in Windows via Curl](media/wsl2-network-l2w.png)
 
 ### Additional networking considerations
 
@@ -133,6 +142,7 @@ When using a WSL 1 distribution, if your computer was set up to be accessed by y
 This isn't the default case in WSL 2. WSL 2 has a virtualized ethernet adapter with its own unique IP address. Currently, to enable this workflow you will need to go through the same steps as you would for a regular virtual machine. (We are looking into ways to improve this experience.)
 
 Here's an example PowerShell command to add a port proxy that listens on port 4000 on the host and connects it to port 4000 to the WSL 2 VM with IP address 192.168.101.100.
+
 ```powershell
 netsh interface portproxy add v4tov4 listenport=4000 listenaddress=0.0.0.0 connectport=4000 connectaddress=192.168.101.100
 ```
@@ -152,26 +162,26 @@ To expand your maximum VHD size beyond 256GB:
 1. Terminate all WSL instances using the command: `wsl --shutdown`
 
 2. Find your distribution installation package name ('PackageFamilyName')
-    * Using PowerShell (where 'distro' is your distribution name) enter the command:
-    * `Get-AppxPackage -Name "*<distro>*" | Select PackageFamilyName`
+    - Using PowerShell (where 'distro' is your distribution name) enter the command:
+    - `Get-AppxPackage -Name "*<distro>*" | Select PackageFamilyName`
 
 3. Locate the VHD file `fullpath` used by your WSL 2 installation, this will be your `pathToVHD`:
-     * `%LOCALAPPDATA%\Packages\<PackageFamilyName>\LocalState\<disk>.vhdx`
+     - `%LOCALAPPDATA%\Packages\<PackageFamilyName>\LocalState\<disk>.vhdx`
 
 4. Resize your WSL 2 VHD by completing the following commands:
-   * Open Windows Command Prompt with admin privileges and enter:
-      * `diskpart`
-      * `Select vdisk file="<pathToVHD>"`
-      * `expand vdisk maximum="<sizeInMegaBytes>"`
+   - Open Windows Command Prompt with admin privileges and enter:
+      - `diskpart`
+      - `Select vdisk file="<pathToVHD>"`
+      - `expand vdisk maximum="<sizeInMegaBytes>"`
 
 5. Launch your WSL distribution (Ubuntu, for example).
 
 6. Make WSL aware that it can expand its file system's size by running these commands from your Linux distribution command line:
-    * `sudo mount -t devtmpfs none /dev`
-    * `mount | grep ext4`
-    * Copy the name of this entry, which will look like: `/dev/sdXX` (with the X representing any other character)
-    * `sudo resize2fs /dev/sdXX`
-    * Use the value you copied earlier. You may also need to install resize2fs: `apt install resize2fs`
+    - `sudo mount -t devtmpfs none /dev`
+    - `mount | grep ext4`
+    - Copy the name of this entry, which will look like: `/dev/sdXX` (with the X representing any other character)
+    - `sudo resize2fs /dev/sdXX`
+    - Use the value you copied earlier. You may also need to install resize2fs: `apt install resize2fs`
 
 > [!NOTE]
 > In general do not modify, move, or access the WSL related files located inside of your AppData folder using Windows tools or editors. Doing so could cause your Linux distribution to become corrupted.