Inside a WSL Distribution Launcher: Registration, Default Users, and First Run
How a Windows WSL launcher registers a rootfs, configures distribution identity and default UID, handles first run, invokes WSL APIs, and updates safely.
A packaged WSL distribution is more than a root-file-system archive. Its Windows launcher gives the distribution a registered name, installs the rootfs on first run, creates/configures an initial Linux user, sets a default UID, and starts commands through the WSL API. The Windows package/launcher and the Linux file system have related but different update and backup lifecycles.
Registration associates a name with Linux storage
Microsoft’s WSL DistroLauncher sample demonstrates native calls such as WslIsDistributionRegistered, WslRegisterDistribution, WslConfigureDistribution, WslGetDistributionConfiguration, and WslLaunchInteractive. A custom launcher substitutes its distribution name and packaged rootfs while retaining the API contract.
On first run, the launcher checks registration, registers/extracts the rootfs, and starts initial configuration. Registration is idempotent only if the launcher distinguishes “already installed” from a partial failed setup. Retrying extraction over live user data can corrupt a distro; error paths should preserve the registered state and give a supported reset/export path.
The registered distribution name is a Windows identity used by wsl -d, Terminal profiles, IDEs, and management commands. Linux’s /etc/os-release and hostname are separate. Renaming a package display name does not safely rename every registration/integration.
First run crosses a trust boundary
The initial root user creates a non-root Linux account, assigns group membership, and the launcher sets the resulting numeric UID as default. Usernames need Linux validation; passing unchecked text into a shell command creates injection. The sample uses carefully controlled invocation, but production launchers should pass arguments through APIs or a fixed helper rather than concatenate shell source.
Password entry must occur inside the Linux tool’s terminal prompt so the launcher never logs or retains it. Do not create a passwordless sudo user silently. Distribution policy should grant only intended groups and explain recovery if initial setup is interrupted.
WslConfigureDistribution can set default UID and distribution flags. Current WSL also reads /etc/wsl.conf for settings such as user, mount, interop, network, and systemd behavior. Define precedence and migration so a launcher update does not fight an administrator’s Linux configuration.
Launches are process invocations, not a persistent VM contract
A launcher can request an interactive shell or execute a command with a working directory and environment behavior defined by WSL APIs. It should propagate exit codes, Ctrl-C/console handling, and errors accurately. Assuming bash exists or hard-coding /home/<name> breaks minimal/custom distributions; consult /etc/passwd and the configured default shell.
The lightweight VM and distro can terminate independently of the launcher process. Background/service expectations must follow WSL/systemd lifecycle, not rely on an invisible console window remaining open.
Package updates must not replace Linux user data
The launcher executable and install-time rootfs asset are Windows package content. Once registered, the distro’s packages and user data live in its WSL storage and normally update through the distribution’s package manager. Replacing the packaged tar on application update must not reinitialize existing installations.
Sign the launcher/package, protect the rootfs supply chain with hashes and a reproducible build, declare licenses, and test upgrades from every supported launcher version. Store submission also requires branding, metadata, and policy beyond API correctness.
Test clean first run, invalid username, interrupted extraction, disk full, existing registration, default-user creation failure, launcher upgrade, distro export/import, unregister warning, multiple Windows users, WSL 1/2 selection where supported, and console signals. A launcher is a small installer and lifecycle client; treating it as a shortcut executable understates the authority it has over a user’s Linux environment.
Related:
- How to Build and Register a Custom WSL Distribution from a Root Filesystem
- WSL Export and Import: What a tar Archive Preserves and What Registration Adds
Sources: