From c0759e6c976184552e578487ec98637067ca45bc Mon Sep 17 00:00:00 2001 From: Andrea Reale Date: Mon, 3 Feb 2025 14:37:15 +0100 Subject: [PATCH 1/2] wsl2: cover custom WSL2 kernels --- .../manuals/desktop/features/wsl/_index.md | 1 + .../desktop/features/wsl/custom-kernels.md | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 content/manuals/desktop/features/wsl/custom-kernels.md diff --git a/content/manuals/desktop/features/wsl/_index.md b/content/manuals/desktop/features/wsl/_index.md index 74a5eae3e9d4..d0eadf5526d0 100644 --- a/content/manuals/desktop/features/wsl/_index.md +++ b/content/manuals/desktop/features/wsl/_index.md @@ -109,3 +109,4 @@ Docker Desktop does not require any particular Linux distributions to be install - [Explore best practices](best-practices.md) - [Understand how to develop with Docker and WSL 2](use-wsl.md) - [Learn about GPU support with WSL 2](/manuals/desktop/features/gpu.md) +- [Custom kernels on WSL](custom-kernels.md) diff --git a/content/manuals/desktop/features/wsl/custom-kernels.md b/content/manuals/desktop/features/wsl/custom-kernels.md new file mode 100644 index 000000000000..911a5a072ef2 --- /dev/null +++ b/content/manuals/desktop/features/wsl/custom-kernels.md @@ -0,0 +1,34 @@ +--- +title: Custom kernels on WSL +description: Using custom kernels with Docker Desktop on WSL 2 +keywords: wsl, docker desktop, custom kernel +tags: [Best practices, troubleshooting] +aliases: +- /desktop/wsl/custom-kernels/ +--- + +Docker Desktop depends on several kernel features built into the default +WSL 2 Linux kernel distributed by Microsoft. Because of that, **using a +custom kernel with Docker Desktop on WSL 2 is not officially supported** +and may cause issues with Docker Desktop startup or operation. + +At the same time, we understand that in some cases it may be necessary +to run custom kernels; Docker Desktop does not block their use, and +some users have reported success using them. + +If you choose to use a custom kernel, we suggest starting +from the kernel tree distributed by Microsoft at their [official +repository](https://github.com/microsoft/WSL2-Linux-Kernel) and adding +the features you need on top of that. + +We suggest to: +- Use the same kernel version as the one distributed by the latest WSL2 +release (you can find the version by running `wsl.exe --system uname -r` +in a terminal). +- Start from the default kernel configuration as provided by Microsoft +in their [repository](https://github.com/microsoft/WSL2-Linux-Kernel) +and add the features you need on top of that. +- Make sure that your kernel build environment includes `pahole` and +its version is properly reflected in the corresponding kernel config +(`CONFIG_PAHOLE_VERSION`). + From 8d044da6bfe99a7988e392c88172104c8bd8838c Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 4 Feb 2025 09:43:47 +0000 Subject: [PATCH 2/2] Apply suggestions from code review --- .../desktop/features/wsl/custom-kernels.md | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/content/manuals/desktop/features/wsl/custom-kernels.md b/content/manuals/desktop/features/wsl/custom-kernels.md index 911a5a072ef2..0fd8fcf01867 100644 --- a/content/manuals/desktop/features/wsl/custom-kernels.md +++ b/content/manuals/desktop/features/wsl/custom-kernels.md @@ -3,30 +3,28 @@ title: Custom kernels on WSL description: Using custom kernels with Docker Desktop on WSL 2 keywords: wsl, docker desktop, custom kernel tags: [Best practices, troubleshooting] -aliases: -- /desktop/wsl/custom-kernels/ --- Docker Desktop depends on several kernel features built into the default -WSL 2 Linux kernel distributed by Microsoft. Because of that, **using a -custom kernel with Docker Desktop on WSL 2 is not officially supported** +WSL 2 Linux kernel distributed by Microsoft. Consequently, using a +custom kernel with Docker Desktop on WSL 2 is not officially supported and may cause issues with Docker Desktop startup or operation. -At the same time, we understand that in some cases it may be necessary +However, in some cases it may be necessary to run custom kernels; Docker Desktop does not block their use, and some users have reported success using them. -If you choose to use a custom kernel, we suggest starting -from the kernel tree distributed by Microsoft at their [official -repository](https://github.com/microsoft/WSL2-Linux-Kernel) and adding +If you choose to use a custom kernel, it is recommended you start +from the kernel tree distributed by Microsoft from their [official +repository](https://github.com/microsoft/WSL2-Linux-Kernel) and then add the features you need on top of that. -We suggest to: +It's also recommended that you: - Use the same kernel version as the one distributed by the latest WSL2 -release (you can find the version by running `wsl.exe --system uname -r` -in a terminal). +release. You can find the version by running `wsl.exe --system uname -r` +in a terminal. - Start from the default kernel configuration as provided by Microsoft -in their [repository](https://github.com/microsoft/WSL2-Linux-Kernel) +from their [repository](https://github.com/microsoft/WSL2-Linux-Kernel) and add the features you need on top of that. - Make sure that your kernel build environment includes `pahole` and its version is properly reflected in the corresponding kernel config