Initial Home page

Ship-WSL-2-Linux-Kernel.md

@@ -0,0 +1,65 @@
+# Ship WSL 2 Linux Kernel
+
+## Background
+
+WSL 2 distributions use a [full Linux kernel](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/). This Linux kernel is open source, with its source code available at the [WSL2-Linux-Kernel repository](https://github.com/microsoft/WSL2-Linux-Kernel/releases). At the beginning, Linux kernel is shipped as a Windows component and delivered as part of Windows. To improve the serviceability, The Linux kernel is lifted and removed from Windows, then is going to deliver to your machine via [Microsoft Update](https://devblogs.microsoft.com/commandline/wsl2-will-be-generally-available-in-windows-10-version-2004/) automatically, and follows a separate release schedule to the Windows Subsystem for Linux which is delivered as part of the Windows image.
+
+The whole serving story is divided into three steps:
+1. Create [MSI installer](https://aka.ms/wsl2kernel) to install Linux kernel.
+2. Remove Linux kernel from Windows. When you see `WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel`, that means you are in this step.
+3. Linux kernel update is delivered to your machine automatically by Microsoft Update.
+
+---
+
+## Windows Subsystem for Linux Update (MSI installer)
+To use WSL 2, `kernel` is expected in `%SystemRoot%\system32\lxss\tools\`. In the earlier version of OS, kernel is shipped with OS. Then kernel is lifted and removed from OS image and is packaged into a MSI installer which named `Windows Subsystem for Linux Update`.
+
+### Pre-Check Step
+To install MSI kernel, WSL is required and should be enabled first. How do the installer knows it? It checks `HKEY_LOCAL_MACHINE\System\CurrentControlSet\services\LxssManager\parameters` regkey. If it fails, it pops up the message:
+`This update only applies to machines with the Windows Subsytem for Linux`. 
+
+There are three possible reason you see this message:
+1. You are still in old version of Windows which doesn't support WSL 2. Please check the [WSL 2 requirement](https://docs.microsoft.com/en-us/windows/wsl/install-win10#update-to-wsl-2) 
+2 `Windows Subsystem for Linux` is not enabled. Please follow [Windows Subsystem for Linux Installation Guide](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
+3. After Enable `Windows Subsystem for Linux`, reboot is required to take into effect.
+
+### Install Step
+If Pre-Check step passed, the installer continues:
+
+- Copy kernel to kernel.rollback
+- Install and replace kernel file
+
+---
+
+## Remove Kernel from Windows image
+If Linux kernel is removed from Windows image, you will see this error message:
+`WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel`. Follow above link, and most of the user should be able resolved the problem after install the kernel manually. 
+
+---
+
+## Deliver Kernel by Microsoft Update
+
+TBD
+
+---
+## Troubleshooting 
+#### `This update only applies to machines with the Windows Subsytem for Linux`
+
+see Pre-Check Step
+
+#### `WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel`
+
+Each time kernel is missing in %SystemRoot%\system32\lxss\tools\, you may run into above error. There are many reasons:
+1. User just start to setup WSL 2
+2. WSL 2 is enabled before, and Windows is updated to latest version
+3. MSI is installed, but kernel file is missing. 
+
+Not matter what reason, there is no `%SystemRoot%\system32\lxss\tools\kernel` exists. Here are some possible ways to resolve it:
+
+1. If you didn't install MSI manually before, download and install it from https://aka.ms/wsl2kernel
+2. If there is `%SystemRoot%\system32\lxss\tools\kernel.rollback`, copy it to `%SystemRoot%\system32\lxss\tools\kernel`
+3. Uninstall the MSI from 'Add or Remove Programs', and install it again
+4. Extract kernel from .msi and copy kernel to tools directory
+ - `msiexec /a "wsl_update_x64.msi" /qb TARGETDIR="C:\temp"`
+ - copy the kernel file from C:\temp to `%SystemRoot%\System32\lxss\tools`
+