[PATCH] meta: Generate WSL image for Windows Subsystem for Linux

[Clara Kowalsky]

This allows to generate a wsl file for Windows Subsystem for Linux.
The wsl image class adapts the rootfs for WSL: It creates /dev/pts/ptmx
because WSL needs that node before devpts is mounted. Without it, early
boot fails with forkpty errors. The class also removes /etc/resolv.conf,
as WSL manages it itself.
See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#configuration-file-recommendations

The wsl-config recipe ships the configuration files /etc/wsl.conf and
/etc/wsl-distribution.conf as templates.
See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#create-wsl-configuration-files

The variables in the configuration files can be overwritten in
downstream layers:
- WSL_DEFAULT_USER specifies which user runs when the WSL distro is
launched. Default: "root"
- WSL_DEFAULT_UID specifies the default UID used during first-run/OOBE
installation. Default: "0"
- WSL_DEFAULT_NAME specifies the name that the distro is registered
under. Default: "${DISTRO}-${MACHINE}"
Whole configuration files can be replaced or added by bbappending the
wsl-config recipe.

This was tested with WSL2, in plain Isar and in downstream layer.

Signed-off-by: Clara Kowalsky <clara.k...@siemens.com>
---
doc/user_manual.md | 1 +
kas/machine/Kconfig | 8 ++++
kas/machine/wsl.yaml | 7 +++
meta-isar/conf/machine/wsl.conf | 16 +++++++
meta-isar/conf/mc.conf | 2 +
meta-isar/conf/multiconfig/wsl-bookworm.conf | 7 +++
meta-isar/conf/multiconfig/wsl-trixie.conf | 7 +++
meta/classes-recipe/image.bbclass | 2 +-
meta/classes-recipe/imagetypes_wsl.bbclass | 48 +++++++++++++++++++
.../wsl-config/files/etc/oobe.sh | 4 ++
.../files/etc/wsl-distribution.conf.tmpl | 6 +++
.../wsl-config/files/etc/wsl.conf.tmpl | 5 ++
.../wsl-config/wsl-config_0.1.bb | 37 ++++++++++++++
testsuite/citest.py | 2 +
14 files changed, 151 insertions(+), 1 deletion(-)
create mode 100644 kas/machine/wsl.yaml
create mode 100644 meta-isar/conf/machine/wsl.conf
create mode 100644 meta-isar/conf/multiconfig/wsl-bookworm.conf
create mode 100644 meta-isar/conf/multiconfig/wsl-trixie.conf
create mode 100644 meta/classes-recipe/imagetypes_wsl.bbclass
create mode 100644 meta/recipes-support/wsl-config/files/etc/oobe.sh
create mode 100644 meta/recipes-support/wsl-config/files/etc/wsl-distribution.conf.tmpl
create mode 100644 meta/recipes-support/wsl-config/files/etc/wsl.conf.tmpl
create mode 100644 meta/recipes-support/wsl-config/wsl-config_0.1.bb

diff --git a/doc/user_manual.md b/doc/user_manual.md
index dcc3f560..f3b1acb9 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -514,6 +514,7 @@ Currently, the following image types are provided:
- `ubi` - image for use on mtd nand partitions employing UBI
- `ubifs` - raw UBI filesystem image, normally used together with UBI partitions
- `ova` - Open Virtual Appliance: image for use on VirtualBox or VMware
+ - `wsl` - tar file for Windows Subsystem for Linux
- `squashfs` - raw squashfs filesystem image
- `fit` - FIT image as used by U-Boot
- `oci-archive`, `docker-archive`, `docker-daemon`, `containers-storage` - see [generating container images](#generate-container-image-with-root-filesystem)
diff --git a/kas/machine/Kconfig b/kas/machine/Kconfig
index 1e360be6..2895368c 100644
--- a/kas/machine/Kconfig
+++ b/kas/machine/Kconfig
@@ -253,6 +253,13 @@ config MACHINE_HYPER_V
select CODENAME_TRIXIE
select ARCH_AMD64

+config MACHINE_WSL
+ bool "wsl"
+ select DISTRO_DEBIAN
+ select CODENAME_BOOKWORM
+ select CODENAME_TRIXIE
+ select ARCH_AMD64
+
config MACHINE_X86_PC
bool "x86 PC"
select DISTRO_DEBIAN
@@ -297,6 +304,7 @@ config KAS_INCLUDE_MACHINE
default "kas/machine/virtualbox.yaml" if MACHINE_VIRTUALBOX
default "kas/machine/vmware.yaml" if MACHINE_VMWARE
default "kas/machine/hyper-v-amd64.yaml" if MACHINE_HYPER_V
+ default "kas/machine/wsl.yaml" if MACHINE_WSL
default "kas/machine/x86-pc.yaml" if MACHINE_X86_PC

endmenu
diff --git a/kas/machine/wsl.yaml b/kas/machine/wsl.yaml
new file mode 100644
index 00000000..f043b02a
--- /dev/null
+++ b/kas/machine/wsl.yaml
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (c) Siemens AG, 2026
+
+header:
+ version: 14
+
+machine: wsl
diff --git a/meta-isar/conf/machine/wsl.conf b/meta-isar/conf/machine/wsl.conf
new file mode 100644
index 00000000..086b0fe1
--- /dev/null
+++ b/meta-isar/conf/machine/wsl.conf
@@ -0,0 +1,16 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+DISTRO_ARCH ?= "amd64"
+
+# WSL uses the Windows-provided kernel
+KERNEL_NAME = ""
+
+IMAGE_FSTYPES ?= "wsl"
+
+# Configure rootfs for WSL boot
+IMAGE_INSTALL:append = " wsl-config"
+# Enable systemd-user session model
+IMAGE_PREINSTALL:append = " dbus dbus-user-session"
diff --git a/meta-isar/conf/mc.conf b/meta-isar/conf/mc.conf
index 649430a2..df3a38b0 100644
--- a/meta-isar/conf/mc.conf
+++ b/meta-isar/conf/mc.conf
@@ -89,4 +89,6 @@ BBMULTICONFIG = " \
qemuamd64-sid \
qemuarm64-sid \
qemuriscv64-resolute \
+ wsl-bookworm \
+ wsl-trixie \
"
diff --git a/meta-isar/conf/multiconfig/wsl-bookworm.conf b/meta-isar/conf/multiconfig/wsl-bookworm.conf
new file mode 100644
index 00000000..5e9f3697
--- /dev/null
+++ b/meta-isar/conf/multiconfig/wsl-bookworm.conf
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+MACHINE ?= "wsl"
+DISTRO ?= "debian-bookworm"
diff --git a/meta-isar/conf/multiconfig/wsl-trixie.conf b/meta-isar/conf/multiconfig/wsl-trixie.conf
new file mode 100644
index 00000000..8ef796e4
--- /dev/null
+++ b/meta-isar/conf/multiconfig/wsl-trixie.conf
@@ -0,0 +1,7 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+MACHINE ?= "wsl"
+DISTRO ?= "debian-trixie"
diff --git a/meta/classes-recipe/image.bbclass b/meta/classes-recipe/image.bbclass
index d02f99da..0329c3f8 100644
--- a/meta/classes-recipe/image.bbclass
+++ b/meta/classes-recipe/image.bbclass
@@ -174,7 +174,7 @@ IMAGE_BASETYPES = "${@get_image_basetypes(d)}"

# image types
IMAGE_CLASSES ??= ""
-IMGCLASSES = "imagetypes imagetypes_wic imagetypes_vm imagetypes_container squashfs \
+IMGCLASSES = "imagetypes imagetypes_wic imagetypes_vm imagetypes_wsl imagetypes_container squashfs \
imagetypes_ddi"
IMGCLASSES += "${IMAGE_CLASSES}"
inherit ${IMGCLASSES}
diff --git a/meta/classes-recipe/imagetypes_wsl.bbclass b/meta/classes-recipe/imagetypes_wsl.bbclass
new file mode 100644
index 00000000..413c6a2d
--- /dev/null
+++ b/meta/classes-recipe/imagetypes_wsl.bbclass
@@ -0,0 +1,48 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+# This class allows to generate WSL import artifacts.
+#
+
+USING_WSL = "${@bb.utils.contains('IMAGE_BASETYPES', 'wsl', '1', '0', d)}"
+
+# WSL requires a static /dev/pts/ptmx during early boot
+ROOTFS_CONFIGURE_COMMAND += "${@bb.utils.contains('USING_WSL', '1', 'image_configure_wsl_ptmx', '', d)}"
+
+# The rootfs should not contain a /etc/resolv.conf
+# See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#configuration-file-recommendations
+ROOTFS_POSTPROCESS_COMMAND += "${@bb.utils.contains('USING_WSL', '1', 'image_postprocess_wsl_cleanup', '', d)}"
+image_postprocess_wsl_cleanup[vardeps] += "WSL_CLEANUP_FILES"
+
+WSL_CLEANUP_FILES ?= " \
+ /etc/resolv.conf \
+"
+
+IMAGE_TYPEDEP:wsl = "tar.gz"
+
+IMAGE_CMD:wsl() {
+ cp -f "${DEPLOY_DIR_IMAGE}/${IMAGE_FULLNAME}.tar.gz" "${IMAGE_FILE_HOST}"
+}
+
+image_configure_wsl_ptmx() {
+ run_privileged_heredoc <<'EOSUDO'
+ set -e
+
+ mkdir -p "${ROOTFSDIR}/dev/pts"
+ if [ ! -e "${ROOTFSDIR}/dev/pts/ptmx" ]; then
+ mknod -m 000 "${ROOTFSDIR}/dev/pts/ptmx" c 5 2
+ fi
+EOSUDO
+}
+
+image_postprocess_wsl_cleanup() {
+ run_privileged_heredoc <<'EOSUDO'
+ set -e
+
+ for path in ${WSL_CLEANUP_FILES}; do
+ rm -f "${ROOTFSDIR}${path}"
+ done
+EOSUDO
+}
diff --git a/meta/recipes-support/wsl-config/files/etc/oobe.sh b/meta/recipes-support/wsl-config/files/etc/oobe.sh
new file mode 100644
index 00000000..e9ddfd16
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/etc/oobe.sh
@@ -0,0 +1,4 @@
+#! /usr/bin/bash
+
+# Generic OOBE hook for Isar-generated WSL images
+exit 0
diff --git a/meta/recipes-support/wsl-config/files/etc/wsl-distribution.conf.tmpl b/meta/recipes-support/wsl-config/files/etc/wsl-distribution.conf.tmpl
new file mode 100644
index 00000000..4f83314b
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/etc/wsl-distribution.conf.tmpl
@@ -0,0 +1,6 @@
+# See https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#add-the-wsl-distribution-configuration-file
+
+[oobe]
+command = /etc/oobe.sh
+defaultUid = ${WSL_DEFAULT_UID}
+defaultName = ${WSL_DEFAULT_NAME}
diff --git a/meta/recipes-support/wsl-config/files/etc/wsl.conf.tmpl b/meta/recipes-support/wsl-config/files/etc/wsl.conf.tmpl
new file mode 100644
index 00000000..862ca252
--- /dev/null
+++ b/meta/recipes-support/wsl-config/files/etc/wsl.conf.tmpl
@@ -0,0 +1,5 @@
+[boot]
+systemd=true
+
+[user]
+default=${WSL_DEFAULT_USER}
diff --git a/meta/recipes-support/wsl-config/wsl-config_0.1.bb b/meta/recipes-support/wsl-config/wsl-config_0.1.bb
new file mode 100644
index 00000000..2144c01b
--- /dev/null
+++ b/meta/recipes-support/wsl-config/wsl-config_0.1.bb
@@ -0,0 +1,37 @@
+# This software is a part of Isar.
+# Copyright (C) Siemens AG, 2026
+#
+# SPDX-License-Identifier: MIT
+
+inherit dpkg-raw
+
+DESCRIPTION = "WSL configuration files"
+MAINTAINER = "Clara Kowalsky <clara.k...@siemens.com>"
+
+WSL_DEFAULT_USER ?= "root"
+WSL_DEFAULT_UID ?= "0"
+WSL_DEFAULT_NAME ?= "${DISTRO}-${MACHINE}"
+
+SRC_URI = " \
+ file://etc/oobe.sh \
+ file://etc/wsl.conf.tmpl \
+ file://etc/wsl-distribution.conf.tmpl \
+"
+
+TEMPLATE_FILES = " \
+ etc/wsl.conf.tmpl \
+ etc/wsl-distribution.conf.tmpl \
+"
+TEMPLATE_VARS += " \
+ WSL_DEFAULT_USER \
+ WSL_DEFAULT_UID \
+ WSL_DEFAULT_NAME \
+"
+
+do_install[cleandirs] += "${D}/etc"
+
+do_install() {
+ install -m 0644 "${WORKDIR}/etc/wsl.conf" "${D}/etc"
+ install -m 0644 "${WORKDIR}/etc/wsl-distribution.conf" "${D}/etc"
+ install -m 0755 "${WORKDIR}/etc/oobe.sh" "${D}/etc"
+}
diff --git a/testsuite/citest.py b/testsuite/citest.py
index a4f15d04..b13e27ed 100644
--- a/testsuite/citest.py
+++ b/testsuite/citest.py
@@ -904,6 +904,8 @@ class NoCrossTest(CIBaseTest):
'mc:qemuamd64-jammy:isar-image-base',
'mc:qemuarm64-jammy:isar-image-base',
'mc:x86-pc-bookworm:isar-image-base',
+ 'mc:wsl-bookworm:isar-image-base',
+ 'mc:wsl-trixie:isar-image-base',
]

self.init()
--
2.54.0

[MOESSBAUER, Felix]

On Thu, 2026-08-06 at 09:07 +0200, 'Clara Kowalsky' via isar-users
wrote:

Hi,

this file is already in ROOTFS_CLEAN_FILES. By that, it should be
cleaned (but I'm wondering if rootfs_install_clean_files is running too
early). Please fix the existing logic (if needed) instead of
introducing a new one.

Apart from that, the image type must not alter the rootfs itself, but
instead create a new (modified) copy.

> +
> +IMAGE_TYPEDEP:wsl = "tar.gz"

Depend on the tar instead of tar.gz, then you can easily apply the
modifications while repacking

> +
> +IMAGE_CMD:wsl() {
> + cp -f "${DEPLOY_DIR_IMAGE}/${IMAGE_FULLNAME}.tar.gz" "${IMAGE_FILE_HOST}"

Here you could apply the filter by doing something like (untested)

cat ${DEPLOY_DIR_IMAGE}/${IMAGE_FULLNAME}.tar.gz | tar --delete
/etc/resolv.conf | gz > ${IMAGE_FILE_HOST}

> +}
> +
> +image_configure_wsl_ptmx() {
> + run_privileged_heredoc <<'EOSUDO'
> + set -e
> +
> + mkdir -p "${ROOTFSDIR}/dev/pts"
> + if [ ! -e "${ROOTFSDIR}/dev/pts/ptmx" ]; then
> + mknod -m 000 "${ROOTFSDIR}/dev/pts/ptmx" c 5 2
> + fi
> +EOSUDO
> +}
> +
> +image_postprocess_wsl_cleanup() {
> + run_privileged_heredoc <<'EOSUDO'
> + set -e
> +
> + for path in ${WSL_CLEANUP_FILES}; do
> + rm -f "${ROOTFSDIR}${path}"
> + done
> +EOSUDO
>
>
> +}

This does not work, as the final image is deployed with an empty /dev
(since "image: delete entries below /dev"). But it also should not be
needed, as systemd mounts a devpts on /dev/pts and sets up the
symlinks.

Felix

> --
> You received this message because you are subscribed to the Google Groups "isar-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260806070758.799362-1-clara.kowalsky%40siemens.com.