Liminova

Appearance

Last guide you'll ever need: [your distro] on WSL2

Delnegend
 • September 11, 2024
  • fedora
  • wsl
  • wsl2
  • linux
  • windows

They really should've spilled the beans waaay before July 2024! Turning any container image into a WSL2 distro? I'll be using fedora for this post.

Ranting

I've been using Ubuntu on WSL and Ubuntu Server on my server for years. At the time of writing, Canonical has released Ubuntu 24.04 LTS with many updates, especially in the toolchains. However, it feels bloated to me; I prefer something minimal and stable, but this isn't enough reason for me to switch distributions yet. A few days ago, I SSHed into my server and ran a regular sudo apt update, but I encountered a warning about a conflicting update. It suggested I run apt --fix-broken install, which I did, and it broke many system packages.

I still wanted to use Ubuntu Server, so I downloaded the latest installation image, only to find that my server doesn't work with the GRUB bootloader. It works to boot installed Linux, but not when booting the Linux installation image, so I had to use Syslinux. Since Ubuntu 22, they switched to GRUB for the installation image, so I opted for version 20. However, for some reason, it couldn't resolve the IP address for some repositories when installing additional packages, and that was the last straw for me.

Considering my server's use case, where I only need to run containers and want to avoid regular maintenance, I need the host distribution to be as stable as possible, widely adopted, and as "upstream" as possible. My options were Debian, Fedora, and Arch. The latter two were out of the question since Fedora releases a new version every six months, and Arch is a rolling release. Debian, on the other hand, releases every three years, and the previous release has an additional two years of LTS, so I went with Debian. It turns out Debian allows you to choose your desktop environment during the installation process and whether you want an SSH server. I chose not to install a DE and to install the SSH server, and after completion, it worked just like Ubuntu Server did years ago.

As for WSL, even though it still works perfectly fine, version 24 and all the toolchain updates feel bloated, so I decided to switch to another distribution. Debian is on the official support list when I run wsl -l -o, but since this is my development environment, I prefer something more up-to-date and doesn't break when I do an update, so Fedora was my final decision.

Fedora Remix requires me to wait for their fork to upgrade before I can proceed with my own upgrade whenever a new release is available. It turns out that WSL functions similarly to a container, allowing the use of any image as a WSL distro. However, the process was not seamless, which is the reason for the existence of this article.

TL;DR: ​

  1. Install any distro first and Docker Engine

  2. Extract the image

    wsl
    sudo docker run -t --name wsl_export <distro> ls /
sudo docker export wsl_export > /mnt/c/<distro>-rootfs.tar

  3. Import the image, cleanup and set default distro

    powershell
    wsl --import <distro> C:\<distro> C:\<distro>-rootfs.tar
Remove-Item C:\<distro>-rootfs.tar
wsl --unregister <old-distro>
wsl --set-default <distro>

You can skip steps 1 and 2 by asking one of your friends who already uses Linux to export the distro for you.

Install WSL & Docker Engine ​

There are a ton of guides on the internet but here's one to avoid jumping to another article if you haven't installed it yet.

  • Windows + S > type Turn Windows features
  • Open Turn Windows features on or off
  • Enable Virtual Machine Platform and Windows Subsystem for Linux > OK > Restart
  • Windows + X > Terminal or PowerShell
  • wsl --update
  • wsl --install and follow the instructions

Follow this guide to install Docker Engine on Ubuntu. No need for the post-installation steps since we only need them to extract the Fedora image from the Docker image.

Extract distro's rootfs from image ​

Run an empty container using the latest Fedora image

bash
sudo docker run -t --name wsl_export fedora ls /

Export the container using its name to a .tar file

bash
sudo docker export wsl_export > /mnt/c/fedora-rootfs.tar

Import the rootfs & clean up ​

powershell
wsl --import Fedora C:\Fedora C:\fedora-rootfs.tar

Afterwards you can remove the .tar file and the old distro

powershell
Remove-Item C:\fedora-rootfs.tar
wsl --unregister Ubuntu

In Windows Search, search for Ubuntu and uninstall it.

At this point, you should see the Fedora distro in the WSL distro list.

Post-installation ​

  • Set default distro for WSL

    powershell
    wsl --set-default Fedora

  • Path fixes Upon starting using the wsl command, you might see a bunch of ERROR: UtilTranslatePathList messages. This happens because Fedora wasn't shut down "the-wsl-way" in the second step. Just terminate it from Windows and relaunch it.

    powershell
    wsl --terminate Fedora
wsl

    In the future you should avoid shutting down WSL from the inside, use wsl --shutdown instead.

  • Update & install additional packages

    bash
    dnf update
dnf install wget curl sudo git passwd ncurses dnf-plugins-core dnf-utils findutils nano

    You may remove those you know and don't need.

  • Add user & set password

    bash
    useradd -G wheel yourusername
passwd yourusername

  • Set default user in wsl.conf & enable systemd Modify the wsl.conf file using a text editor

    bash
    sudo nano /etc/wsl.conf

    Paste the following contents

    bash
    [boot]
systemd = true

[user]
default = yourusername

    Omit the systemd part if your distro doesn't use systemd.

    then restart WSL

    powershell
    wsl --shutdown
wsl

WSLg ​

We are creating two systemd services to automatically generate two symlink files on startup for the X11 socket.

  1. /tmp/.X11-unix -> /mnt/wslg/.X11-unix First create the service file

    bash
    sudo nano /usr/lib/systemd/system/wslg-tmp-x11.service

    Paste the following contents

    [Unit]
Description=Recreate WSLg X display file link after /tmp mounted
ConditionPathIsDirectory=/mnt/wslg/.X11-unix
Requires=tmp.mount
After=tmp.mount
Before=systemd-tmpfiles-setup.service

[Service]
Type=oneshot
ExecStart=/bin/chmod +t /mnt/wslg/.X11-unix
ExecStart=-/bin/rmdir /tmp/.X11-unix
ExecStart=/bin/ln -sf /mnt/wslg/.X11-unix /tmp/.X11-unix
ExecStart=/bin/mount -m -o bind /mnt/wslg/.X11-unix /tmp/.X11-unix

[Install]
WantedBy=default.target

  2. $XDG_RUNTIME_DIR -> /mnt/wslg/runtime-dir Create the service file

    bash
    sudo nano /usr/lib/systemd/user/wslg-runtime-dir.service

    Paste the following contents

    [Unit]
Description=Recreate WSLg sockets files in $XDG_RUNTIME_DIR
ConditionPathIsDirectory=/mnt/wslg/runtime-dir

[Service]
Type=oneshot
ExecStart=/bin/sh -c "ln -fs /mnt/wslg/runtime-dir/* "%t

[Install]
WantedBy=default.target

Finally, enable the services

bash
sudo systemctl enable wslg-tmp-x11
sudo systemctl --global enable wslg-runtime-dir

Everything else, X11 or Wayland-related, should be included in the dependency list of the GUI application you're installing.

Miscellaneous ​

Taskbar Shortcut ​

If you're using Windows Terminal (btw you should), you can create a shortcut to open the WSL distro in Windows Terminal and pin it to the taskbar.

  • Right-click on desktop > New > Shortcut
  • Paste the following path
    %userprofile%\AppData\Local\Microsoft\WindowsApps\wt.exe -p Fedora
  • Next > enter Fedora > Finish
  • Hold Alt and double click on the shortcut to open its Properties panel
  • Select Change Icon... and use this fedora.ico
  • Drag the shortcut onto the taskbar

Best practices for backup & restore ​

  • Find and remove unnecessary files and directories with ncdu (v2.5 and above)

    sudo /path/to/ncdu -t8 --exclude /mnt /

  • Shrink the WSL2 .vhdx disk

    Identify the ext4.vhdx file from the location you specified during the import process OR in regedit at

    Computer\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\

    the ext4.vhdx should be in the BasePath folder.

    Launch diskpart using Terminal, PowerShell or Command Prompt

    cmd
    diskpart

    and execute the following commands line by line

    cmd
    select vdisk file="path\to\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

  • To backup, copy the whole ext4.vhdx file to another location or use

    PowerShell
    wsl --export --vhd <Distribution Name> <FileName>

  • To restore, use

    PowerShell
    wsl --import --vhd <Distribution Name> <InstallLocation> <FileName>

References ​