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

[Anton Mikanovich <amikan@ilbers.de>]

06.08.2026 10:07, 'Clara Kowalsky' via isar-users wrote:
> 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.kowalsky@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 = ""
We should probably don't set KERNEL_NAME at all, just like container 
machine does.
And this also requires adding some hacks in 
meta-isar/conf/local.conf.sample
> +
> +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 \
>   "
Can you also run testsuite/targets_gen.py to update 
testsuite/data/targets.yml?
> 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.kowalsky@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',
It's better to add a separate test case (just like for containers).
>           ]
>   
>           self.init()

-- 
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+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/925c03a1-c68d-42e6-9587-5a4afb513b93%40ilbers.de.