How to Build and Register a Custom WSL Distribution from a Root Filesystem

WSL can import a Linux root file system without a Microsoft Store launcher. This is useful for internal build environments, CI replicas, appliances, and distributions not otherwise packaged. The rootfs becomes an operating-system supply-chain artifact: every binary, repository key, account, capability, and service in it needs provenance and an update path.

Build a minimal rootfs from trusted inputs

Use the distribution’s supported bootstrap tool, an official base container/rootfs, or a reproducible package manifest. Record release, architecture, repository snapshot, signing keys, package versions, bootstrap command, tool versions, and output hash. Do not download an anonymous rootfs archive or convert a running server without removing machine-specific secrets.

Build as root in a disposable Linux environment so ownership and special metadata are correct. A Windows archiver can flatten UIDs, modes, symlinks, capabilities, and case-sensitive names. Exclude pseudo file systems and runtime mounts such as /proc, /sys, /dev, /run, host /mnt, temporary sockets, and build caches. Provide empty mount points rather than archived live kernel state.

Before packing, remove SSH host keys if clones should generate unique keys, reset machine identity according to the distro’s documented image process, clear package caches and logs deliberately, lock/delete bootstrap accounts, and verify no API tokens, shell histories, cloud credentials, or resolvers from the build environment remain.

Create the tar with numeric ownership and a deterministic ordering/timestamp policy where the tool supports it. Then inventory and hash:

tar --numeric-owner -cpf custom-rootfs.tar -C rootfs .
sha256sum custom-rootfs.tar

GNU tar options are not universal; pin the build environment rather than promising one command works everywhere.

Import under a disposable name first

From PowerShell:

wsl --import Acme-Lab D:\WSL\Acme-Lab .\custom-rootfs.tar --version 2
wsl -d Acme-Lab -u root -- cat /etc/os-release

Choose a dedicated NTFS location with sufficient capacity and approved backup. Importing registers a new distribution; it does not create a Store package or automatic vendor update channel. Never reuse a production distro name for an untested archive.

Inside as root, configure package repositories/keys, locale, timezone policy, CA trust, resolver behavior only through supported WSL configuration, and an ordinary user. Use the distro’s user tool, set appropriate groups, and configure the default user in /etc/wsl.conf:

[user]
default=developer

[boot]
systemd=true

Enable systemd only when the distro includes a compatible systemd and the current WSL supports it. After changing wsl.conf, terminate the distro and restart it. Do not enable every packaged service; mask/remove hardware daemons and network managers that conflict with WSL’s environment according to distro guidance.

Test the WSL boundary

Verify default user/UID, sudo policy, package updates and signature validation, file permissions/capabilities, /mnt behavior, case sensitivity, DNS, NAT/mirrored networking, localhost, Windows executable interop, environment-path import, systemd services, shutdown, clock, proxy/VPN behavior, and IDE/container workflows.

Scan installed packages and licenses, create an SBOM, and run vulnerability policy appropriate to the environment. The rootfs needs a documented cadence for rebuilding from fresh packages; indefinite in-place mutation makes replicas drift.

Finally export the configured result, import it under a second temporary name, and repeat acceptance. Separate personal home data and credentials from the reusable base. A custom distribution is ready when its rootfs can be rebuilt, verified, imported, updated, and removed without hidden dependence on the original builder.

Related:

Sources:

Build a minimal rootfs from trusted inputs

Import under a disposable name first

Test the WSL boundary

Comments