4

wsl.exe help (shown by wsl.exe --help) talks about "the system distribution":

Options:
...
    --system
        Launches a shell for the system distribution.

What is it? Searching in WSL docs for "system distribution" gave me only the following hit in the section How to manage WSL disk space:

Information about the block device includes: NAME: The name assigned to the device will be sd[a-z], referring to the SCSI Disk with a letter designation for each disk being used. sda is always the system distribution.

0

2 Answers 2

5

After launching this shell, check /etc/os-release to get more information about the installed distro.

In my WSL, this appears to be Common Base Linux Mariner, and is documented here: https://aka.ms/cbl-mariner

CBL-Mariner is an internal Linux distribution for Microsoft’s cloud infrastructure and edge products and services. CBL-Mariner is designed to provide a consistent platform for these devices and services and will enhance Microsoft’s ability to stay current on Linux updates. [...]

Example output from system shell

PS C:\Users\testuser> wsl --system
wslg [ /mnt/c/Users/testuser ]$ cat /etc/os-release
NAME="Common Base Linux Mariner"
VERSION="2.0.20230630"
ID=mariner
VERSION_ID="2.0"
PRETTY_NAME="CBL-Mariner/Linux"
ANSI_COLOR="1;34"
HOME_URL="https://aka.ms/cbl-mariner"
BUG_REPORT_URL="https://aka.ms/cbl-mariner"
SUPPORT_URL="https://aka.ms/cbl-mariner"

Example output from a regular user shell

PS C:\Users\testuser> wsl
testuser@testhost:/mnt/c/Users/testuser$ cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04.3 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.3 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy
4

The (or "a", depending on the context) "system distribution" in WSL is a bit oddly named, but probably meant to be the converse of a "user distribution". It's also a bit difficult to explain. There's an overview in the original WSLg Architecture devblog post from about 2 years ago.

For most users, there's really no need to understand or use the system distribution, other than curiosity. However, it can be useful for:

  • Debugging WSLg/GUI issues in WSL
  • If desired, modifying or replacing WSLg functionality.
  • Understanding what that weird --system argument is for in the WSL help ;-)

First, some additional "terminology". To understand what the "system distribution" is, we first need to really understand what a "distribution" is in WSL. Short summary - A distribution is a namespace isolated environment (container) running inside the WSL2 VM. See this answer for more detail.

There are actually multiple system distributions:

  • A template, root filesystem (based on CBL Mariner, as noted in @Panki's answer) which is provided with WSL itself. This root filesystem is then used to create ...

  • A system distribution (namespace container) for each of your other running user distributions (e.g. Ubuntu, Alpine, Kali, Arch, etc.). This system distribution is where Wayland (with RDP/RAILS), Xwayland, Weston, and PulseAudio run. The sockets for these services are then mounted, bind-mounted and/or symlinked (the techniques have changed over time) into the user distribution when it is started. This system distribution has the same lifecycle as the sibling user distribution.

A default WSL installation uses Ubuntu (currently 20.04) as the distribution. In this case, when you start WSL/Ubuntu, a corresponding system distribution is started, the services are started, and the symlinks/mounts are created from the system distribution back to Ubuntu. The architecture is common to all Linux distributions that run under WSL. Some distributions (I'm looking at you, GNU Guix ;-)), however, may deviate too far from the "norm" and require additional work in order to use WSLg to run GUI applications.

The main mount is /mnt/wslg (which, as you mentioned, should be /dev/sda -- I'd never actually noticed that before). The /tmp/.X11 directory where the X11 socket(s) live is (now) a read-only, bind-mount back to /mnt/wslg/.X11-unix.

Similar bind-mounts or symlinks are created for Wayland and PulseAudio, although I haven't fully explored all the nooks and crannies of the architecture.

So, when you start WSL, you can then separately start:

wsl --system

You'll see that your default user is wslg there. You could, however, access it as wsl --system -u root as well.

You could also start with wsl --system and you would find (with wsl -l -v) that your default distribution had also been started.

Because the "per-distribution" system distribution is created "on demand" each time a WSL distribution starts, it is ephemeral. Any changes you make while in wsl --system (or wsl --system -d <user_distro_name>) will be lost when the user distribution is stopped.

To make the changes permanent, you can build your own system distro using the WSLg repository on Github and replace the one that WSLg uses with a .wslconfig file. I'm honestly not aware of anyone outside of Microsoft finding the need to do this in the almost two years since WSLg has been available, but it's certainly an interesting capability. At the least, it allows you to upgrade (or even rollback) a component like Weston without having to wait for Microsoft to make the change.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .