wsl2-kernel-build

A repository for building WSL2 Linux kernels with Docker compatibility, Android Binder support, and vidtv (virtual DVB test driver). This project provides automated tools and configurations to patch Microsoft's WSL2 kernel source with the necessary kernel options required for these workloads.

Features

• 🐳 Docker Compatibility: Automatically patches WSL2 kernel config with all required options for Docker Engine
• 📱 Android Binder Support: Enables Android Binder IPC and BinderFS kernel options
• 📺 vidtv Support: Enables the virtual DVB test driver (vidtv) for media testing
• 🔧 Automated Scripts: Easy-to-use scripts for fetching and patching kernel configurations
• ☁️ CI/CD Ready: GitHub Actions workflow for automated kernel builds

Overview

The default WSL2 kernel provided by Microsoft may not include all the kernel options required for Docker to function properly. This project addresses that by:

1. Fetching the latest WSL2 kernel configuration from Microsoft's repository
2. Applying patches to enable Docker compatibility options
3. Enabling Android Binder IPC support
4. Enabling vidtv test driver support
5. Providing automated build workflows via GitHub Actions

Prerequisites

For Local Development

• Linux or macOS system
• bash shell
• curl or wget (for fetching configs)
• sed (usually pre-installed)
• Git

For Building Kernels

• Build tools: build-essential, flex, bison, dwarves
• Libraries: libssl-dev, libelf-dev
• Utilities: cpio, qemu-utils
• Access to Microsoft's WSL2-Linux-Kernel repository

Usage

Fetching WSL2 Kernel Config

Download the latest WSL2 kernel configuration from Microsoft's repository:

./scripts/fetch-wsl2-config.sh [output-filename]

Example:

./scripts/fetch-wsl2-config.sh config-wsl2.cfg

This will download the config to config/config-wsl2.cfg (default location).

Patching Kernel Config

Apply Docker, Android Binder, and vidtv compatibility settings to a kernel configuration file:

./scripts/patch-wsl2-kernel-config.sh <config-file-path>

Example:

./scripts/patch-wsl2-kernel-config.sh config/config-wsl2.cfg

The script will:

• Create a backup of the original config file
• Remove existing conflicting configuration entries
• Add all required Docker, Android Binder, and vidtv options

Building with GitHub Actions

1. Go to the Actions tab in your GitHub repository
2. Select the Build workflow
3. Click Run workflow
4. Configure the build parameters:
   • kernelBranch: WSL2-Linux-Kernel branch (default: linux-msft-wsl-6.6.y)
   • build-modules: Whether to build kernel modules (default: false)
   • custom-config: Use custom config from this repository (default: false)
5. Click Run workflow

The workflow will:

• Checkout the specified WSL2 kernel branch
• Optionally apply your custom configuration
• Build the kernel
• Optionally build kernel modules
• Upload the built kernel (bzImage) and modules (modules.vhdx) as artifacts

Installing the Built Kernel

After downloading the artifacts from GitHub Actions:

1. Copy bzImage to your Windows host (e.g., C:\Users\<YourUsername>\)

2. Create or edit .wslconfig in your Windows user directory:

   [wsl2]
   kernel=C:\\Users\\<YourUsername>\\bzImage

3. Restart WSL2:

   wsl --shutdown

Configuration Details

Docker Kernel Compatibility Options

The following kernel options are enabled for Docker compatibility:

# Bridge networking
CONFIG_BRIDGE=y
CONFIG_BRIDGE_NETFILTER=y

# Netfilter and iptables
CONFIG_NFT_COMPAT=y
CONFIG_NETFILTER_XT_NAT=y
CONFIG_NETFILTER_XT_TARGET_MASQUERADE=y
CONFIG_NETFILTER_XT_MATCH_ADDRTYPE=y
CONFIG_NETFILTER_XT_MATCH_CONNTRACK=y
CONFIG_NETFILTER_XT_MARK=y

# IP tables
CONFIG_IP_NF_IPTABLES=y
CONFIG_IP_NF_FILTER=y
CONFIG_IP_NF_NAT=y
CONFIG_IP_NF_TARGET_MASQUERADE=y
CONFIG_IP_NF_MANGLE=y

# IP Virtual Server
CONFIG_IP_VS=y
CONFIG_NETFILTER_XT_MATCH_IPVS=y
CONFIG_IP_VS_RR=y

# IPsec
CONFIG_XFRM_USER=y
CONFIG_XFRM_ALGO=y
CONFIG_INET_ESP=y

# Network classification
CONFIG_NET_CLS_CGROUP=y
CONFIG_IP_NF_TARGET_REDIRECT=y

# Virtual network interfaces
CONFIG_IPVLAN=y
CONFIG_MACVLAN=y
CONFIG_DUMMY=y

# FTP/TFTP NAT helpers
CONFIG_NF_NAT_FTP=y
CONFIG_NF_CONNTRACK_FTP=y
CONFIG_NF_NAT_TFTP=y
CONFIG_NF_CONNTRACK_TFTP=y

# Filesystem support
CONFIG_BTRFS_FS=y

Android Binder Support

Android Binder support is commonly required for Android container/runtime stacks and userspace components that depend on Binder IPC:

CONFIG_ANDROID_BINDER_IPC=y
CONFIG_ANDROID_BINDERFS=y
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder"

vidtv (Virtual DVB Test Driver)

vidtv is a virtual DVB driver used for media pipeline and userspace testing without physical tuner hardware:

CONFIG_DVB_TEST_DRIVERS=y
CONFIG_DVB_VIDTV=m

Project Structure

wsl2-kernel-build/
├── config/
│   ├── config-wsl2.cfg          # Base WSL2 kernel config
│   └── config-wsl2-docker.cfg   # Pre-patched config with Docker support
├── scripts/
│   ├── fetch-wsl2-config.sh     # Script to fetch latest WSL2 config
│   └── patch-wsl2-kernel-config.sh  # Script to patch config with Docker/Android Binder/vidtv options
├── .github/
│   └── workflows/
│       └── build.yml            # GitHub Actions build workflow
└── README.md

Troubleshooting

Docker Issues

If Docker still doesn't work after using a patched kernel:

1. Verify the kernel options are present:

   zcat /proc/config.gz | grep CONFIG_BRIDGE

2. Check Docker's kernel compatibility requirements:

   • Docker Kernel Compatibility Documentation

Build Issues

• Ensure all build dependencies are installed
• Check that you have sufficient disk space (kernel builds require several GB)
• Verify the kernel branch exists in Microsoft's repository

References

• Docker Engine Daemon Troubleshooting - Kernel Compatibility
• WSL2 Docker Issue Discussion
• Microsoft WSL2-Linux-Kernel Repository
• Waydroid Documentation
• vidtv Driver Documentation