Skip to content

Ship WSL 2 Linux Kernel

Jump to bottom
Canhua Li edited this page Jun 22, 2020 · 5 revisions

Ship WSL 2 Linux Kernel

Background

WSL 2 distributions use a full Linux kernel. This Linux kernel is open source, with its source code available at the WSL2-Linux-Kernel repository. 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 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 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. 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

  2. Windows Subsystem for Linux is not enabled. Please follow Windows Subsystem for Linux Installation Guide

  3. After you enabled 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

Design of Kernel update

Note: this is not public API and implementation is subject to change

Kernel is delivered by Microsoft Update, and two version of kernels are kept in tools: kernel and kernel.rollback. You are able to rollback to previous version by wsl --update --rollback, but wsl.exe doesn't provide public interface to revert the rollback. It's by design.

When rollback happens, it's assumed that this version is bad and user should not pickup this version again. Assume Microsoft shipped three versions of version:

A(.104) -> B(.121) -> C(.1xy)

User hits problem on version B(.121), then user rolled back to A(.104). So no public interface is provided for you to revert the rollback. Here is the status of kernel:

kernel kernel.rollback
B(.121) A(.104)

When bug fix for B is ready and C is shipped, user picks up C automatically by Windows Update. Since B is assumed bad and A is good, user is not allowed to rollback to B too but A. Here is the actual mapping after user updates to C:

kernel kernel.rollback
C(.1xy) A(.104)

version B(.121) is dropped because it's assumed bad and it's only allowed to rollback from C to A(.104)

Troubleshooting and How to

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

How to rollback kernel

MSI installer keeps two version of kernel, if you find kernel.rollback in tools, then you are able to rollback to an old version of kernel. dir %SystemRoot%\system32\lxss\tools\kernel*

You can rollback the kernel with below command which requires admin permission.

wsl.exe --update --rollback
wsl --shutdown

Please note that --shutdown stops both WSL 1 and WSL 2 instances.

After wsl --update --rollback, the running instance doesn't pick up the kernel immediately, you have to save your work, then shutdown and restart the Linux.

How to revert the kernel rollback

Note: this is not public API and implementation is subject to change

wsl doesn't provides public interface for you to revert the rollback, but you still be able to do it manually:

deleting RollbackKernel in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss
wsl --shutdown
Clone this wiki locally