sirredbeard / wslinternals

A collection of some nifty WSL-related utilities

wslinternals - A collection of some nifty WSL-related utilities

Status

List of utilities

• list-wsl - Lists detailed info on installed WSL distros
• wsl-update - Update packages in all installed WSL distros, also optionally WSL itself, winget, and Scoop
• wsl-kernel-build - Downloads, builds, and installs the latest kernel from WSL2-Linux-Kernel
• wsl-reset - WSL troubleshooting tool, with soft, hard, and destructive resets
• wslctl - Start WSL distros on Windows startup, like systemctl but for WSL distros
• sysdistro-wt - Add the WSL System Distro to Windows Terminal, supports stable, Beta, and Canary builds of Windows Terminal.

Installation

Scoop:

scoop install wslinternals

winget:

winget install sirredbeard.wslinternals

list-wsl

✅ Refactored to .NET, building, and tested

Provides a list of installed distributions, the official Linux distro name, the Linux distro version, the default user, systemd status, current state, and WSL version.

wsl-update

✅ Refactored to .NET, building, and tested

wsl-update - Update all installed WSL distros.

Options:

--winget - Also run Winget update.

--scoop - Also run Scoop update.

--wsl - Also update Windows Subsystem for Linux.

--wslpr - Also update Windows Subsystem for Linux Pre-Release.

Run package updates on all installed WSL distros. Tested on: Pengwin, Fedora Remix for WSL, Ubuntu, Debian, openSUSE Tumbleweed, ArchWSL, AlmaLinux, Oracle Linux, Alpine, and OpenEuler.

wsl-kernel-build

🛑 Refactored to .NET, still being debugged

Downloads, builds, and installs the latest kernel release from WSL2-Linux-Kernel as a custom kernel in WSL2. This is occasionally newer than the version available through wsl.exe --update. The kernel is built in and exported from the immutable WSL2 System Distro image (powered by CBL-Mariner aka Azure Linux OS) so that no dependencies have to be installed in your WSL distros and the process is the same regardless of what WSL distros you have installed.

wsl-kernel-build - Run wsl-latest-kernel.

wsl-kernel-build --check - Check for an available kernel updates.

wsl-kernel-build --force - Overwrites the existing custom kernel.

wsl-kernel-build --customconfig kernelconfig - Build the kernel with a custom kernel config file. Expects a Windows path.

wsl-kernel-build --revert - Reverts to the default stock WSL2 kernel.

wsl-reset

✅ Refactored to .NET, building, and tested

A troubleshooting utility that resets the WSL 2 stack to various degrees.

wsl-reset --reset - Shuts down WSL and stops WSL services.

wsl-reset --hardreset - Shuts down WSL, stops WSL services, uninstalls WSL, and re-installs WSL.

wsl-reset --destructivereset - Shuts down WSL, restarts the WSL service, unregisters all WSL distros, stops the WSL service, uninstalls WSL, and re-installs WSL.

wslctl

🛑 Refactored to .NET, still being debugged

Allows WSL distros to be started on Windows startup. The syntax follows that of systemctl:

wslctl enable pengwin - Start Pengwin on Windows startup.

wslctl disable pengwin - Disable starting Pengwin on Windows startup.

wslctl restart pengwin - Restart Pengwin running in background.

sysdistro-wt

🛑 Refactored to .NET, still being debugged

Adds the WSL System Distro to the Windows Terminal and/or Windows Terminal Preview profiles, for easier debugging. Note that the WSL System Distro is immutable. Once you close the session, it will revert back to the standard image installed with WSL2, and all changes will be lost.

License

wslinternals is licensed Apache 2.0

WSL Community

Join the WSL community Telegram at WSL.community

wslinternals's Issues

list-wsl gives errors

PS C:\src\wslinternals> .\list-wsl.ps1
You cannot call a method on a null-valued expression.
At C:\src\wslinternals\list-wsl.ps1:19 char:9
+         $distribution["Distro Version"] = ($osRelease | Where-Object  ...
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : InvokeMethodOnNull

id: unknown user 0
cat: /etc/wsl.conf: No such file or directory
Processing fstab with mount -a failed.

<3>WSL (17) ERROR: CreateProcessEntryCommon:370: getpwuid(0) failed 2
<3>WSL (17) ERROR: CreateProcessEntryCommon:374: getpwuid(0) failed 2
<3>WSL (17) ERROR: CreateProcessEntryCommon:577: execvpe /bin/sh failed 2
<3>WSL (17) ERROR: CreateProcessEntryCommon:586: Create process not expected to return
Processing fstab with mount -a failed.

<3>WSL (20) ERROR: CreateProcessEntryCommon:370: getpwuid(0) failed 2
<3>WSL (20) ERROR: CreateProcessEntryCommon:374: getpwuid(0) failed 2
<3>WSL (20) ERROR: CreateProcessEntryCommon:577: execvpe /bin/sh failed 2
<3>WSL (20) ERROR: CreateProcessEntryCommon:586: Create process not expected to return
Processing fstab with mount -a failed.

<3>WSL (23) ERROR: CreateProcessEntryCommon:370: getpwuid(0) failed 2
<3>WSL (23) ERROR: CreateProcessEntryCommon:374: getpwuid(0) failed 2
<3>WSL (23) ERROR: CreateProcessEntryCommon:577: execvpe /bin/sh failed 2
<3>WSL (23) ERROR: CreateProcessEntryCommon:586: Create process not expected to return

Name                Linux Distro       Distro Version            Default User systemd State     WSL
----                ------------       --------------            ------------ ------- -----     ---
docker-desktop      Docker Desktop                                              False Installed   2
Ubuntu*             Ubuntu 20.04.2 LTS 20.04.2 LTS (Focal Fossa) samdark              Installed   2
docker-desktop-data                                                                   Installed   2

Downloading the 0.0.7 release triggers a Windows Defender detection

For me at least, it reports the following detections:

• Trojan:Win32/Wacatac.B!ml
• Trojan:Win32/Wacatac.H!ml

-scoop doesn't seem to be properly updating scoop consistently

WSL may hang because of rogue hcs VM

As documented in this thread by @snickler: https://x.com/sinclairinat0r/status/1723756960930001056?s=20

Added hcs VM killing to -hardreset and -destructivereset here a906540

wsl-reset reports incorrect error message

.\wsl-reset.exe
ERROR: This script must be run with either --reset, --hard-reset, or --destructive-reset.

Needs to be updated to reflect the new option nomenclature.

Export default custom kernel config

Probably wouldn't hurt to have a --exportdefaultconfig counterpart to the --customconfig so you have a working base to start from in modifying the kernel config for customizations.

sysdistrowt failing

sysdistrowt is currently failing with:

PS C:\Users\hayde\Downloads> .\sysdistrowt.ps1
Windows Terminal is installed.
Windows Terminal settings.json found.
Windows Terminal settings.json updated.
Windows Terminal Canary is installed.
Windows Terminal Canary settings.json not found, creating...
Start-Process: C:\Users\hayde\Downloads\sysdistrowt.ps1:72
Line |
  72 |          Start-Process "$wtpExePath\wt.exe"
     |          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | This command cannot be run due to the error: An error occurred trying to start process '\wt.exe' with working
     | directory 'C:\Users\hayde\Downloads'. The system cannot find the file specified.
Get-Content: C:\Users\hayde\Downloads\sysdistrowt.ps1:76
Line |
  76 |  … pSettings = Get-Content "$wtpPath\LocalState\settings.json" -Raw | Co …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Cannot find path 'C:\LocalState\settings.json' because it does not exist.
InvalidOperation: C:\Users\hayde\Downloads\sysdistrowt.ps1:80
Line |
  80 |      $wtpSettings.profiles.list += $wslProfile
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | The property 'list' cannot be found on this object. Verify that the property exists and can be set.
Windows Terminal Preview settings.json updated.

wsl-dist-update spawns new window when packaged in Scoop

wsl-reset does not properly parse options

When run as a ps1 shell script, wsl-reset parses --reset correctly, but when run as a compiled binary, wsl-reset always gives:

Update sysdistrowt to support Windows Terminal Canary

See announcement of Windows Terminal Canary.