DISCLAIMER

Code in this repository is without Warranty.

The move script will terminate and unregister your existing WSL instances. This is a destructive operation that could leave you with no WSL instance if the backup failed. The script attempts to catch this but there may be situations where backup failure is not detected.

Purpose

The scripts in this directory manipulate WSL2.

move-distribution.ps1 will move a WSL instance from one location to a new one using the wsl export function.

    flowchart
    subgraph WSL
    end
    subgraph Distributions[Registered Distributions]
        Ubuntu-20.04
        kali-linux
        docker-desktop
        docker-desktop-data
    end
    subgraph Vhds[Virtual Disk Files]
        Ubuntu-20.04.vhd[Ubuntu-20.04 vhdx]
        kali-linux.vhd[Kali Linux vhdx]
        docker-desktop.vhd[docker desktop vhdx]
        docker-desktop-data.vhd[docker desktop data vhdx]
    end
    WSL -.-> Ubuntu-20.04
    WSL -.-> kali-linux
    WSL -.-> docker-desktop
    WSL -.-> docker-desktop-data

    Ubuntu-20.04 -.-> Ubuntu-20.04.vhd
    kali-linux -.-> kali-linux.vhd
    docker-desktop -.-> docker-desktop.vhd
    docker-desktop-data -.-> docker-desktop-data.vhd

Moving a WSL2 distribution

The move operation is comprised of main steps

    flowchart
    subgraph move-distribution[move-distribution.ps1]
        CreateDirs[Create directories for backup files and vhd destination directories]
        CreateDirs -.-> Terminate[Terminate distribution]
        Terminate --> Backup[Create tar backup of the vhd];
        Backup --> Unregister[Unregister: Removes registration and vhd];
        Unregister --> Import[Import: Create vhd from backup and register the distribution]
        Import --> SetDefaultRegistration[Set imported as default if requested]
    end
    subgraph manual-steps
        SetDefaultRegistration -.-> SetDefaultUser[Add default user to wsl.conf]
    end

Using this script

Edit this section of move-distribution.ps1 and change the parameters to fit your needs.

Pay special attention to the $ExecuteUnregisterImport parameter.
Leave $ExecuteUnregisterImport set to false for your first test run.
Make sure you have enough disk space for the .tar file and the vhdx in the places you locate them. Ex:
- Fresh Kali is a 500k tar file
- Fresh Kali with Kex is a 3GB tar file
- Full Kali is an 18GB tar file.
- Fresh Ubuntu is 1.6GB

The latest and most correct param list is in move-distribution.ps1. The param shown here may be out of date.

param (
    # the originating WSL distribution name
    [String]$WslSourceName = "kali-linux",

    # the target locaton for the distribution backup
    [String]$ExportDir = "I:\wsl-export",
    # the filename of the backup - no overwrite
    [String]$WslExportName =
    "$WslSourceName-$(get-date -f yyyyMMdd-HHmmss).tar",

    # the target location for the new distribution vhdx file
    [String]$DestDir = "I:\wsl",
    # the destination WSL distribution name defaults to src
    [String]$WslDestName = $WslSourceName,
    # make this new distribution the default distribution
    [boolean]$WslDestAsDefault = $true,

    # execute all steps but just log unregister and import if false
    [boolean]$ExecuteUnregisterImport = $false
)

Things that are lost when moving a registration location

The distribution.exe file no longer exists.

The WSL installation process creates a <distribution>.exe file for each distribution. You can use that command similarly to the wsl command. Regaining that .exe file involves thinking and registry works.

The default user selection is lost

The default user when opening a connection becomes root. You can reset the default user for Linux Distributions. The import operation will lose the default user resulting in all shells opening as root. That binding is actually stored in a windows registry entry.

Simple fix

Edit the file /etc/wsl.conf in each imported system and add the following section. Some distributions like Ubuntu will already have sections in the file. In that case, just append this content.

[user]
default=<your_username>

This change has the added benefit that all later moves will have the write default user because /etc/wsl.conf becomes part of the migration backup.

Steps

Add the content to /etc/wsl.conf as root
Terminate the wsl distribution with wsl --terminate <distribution-name>
Wait 8 seconds
Open a new terminal into that distribution.

Explanation - Windows registry link was broken

The default UID is 0 which you can see with the output of

Get-ChildItem HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\

Ref: https://askubuntu.com/questions/1427355/why-has-my-ubuntu-started-defaulting-to-root-user-on-startup-duel-running-wind

Explanation - can't fix with instance command

You cannot run <instance>.exe config --default-user <username> because the .exe link isn't made with an import

Todo Items

Add a backup only script for snapshoting wsl instances or make flags easier to use. Currently supported via $ExecuteUnregisterImport=$false
Add ability to remove the backup tar file when done. Currently leaves in place
Add ability to create a backup and unregister without a following import.
Add ability to update the default user from UID=0 / root to something else using wsl.exe edit to /etc/wsl.conffile
Move Powershell param docs into doc block so that help command works.

Completed Todo Items

Added wsl --update to upgrade WSL runtime to the latest
Added return codes on all early exit paths
Add a $ExecuteUnregisterImport parameter that doesn't execute the destructive commands complete 2023/06
Add set as default complete 2023/06

Adding GUI to Distributions

Update kali-linux
Install kali-win-hex for remote desktop support
Install any other wanted kali-linux components

Upgrade WSL to support GUIs

Update your WSL to make sure the latest WSLg support is installed. This code exists in move-distribution.ps1

wsl --update

Install kali-win-kex for remote dekstop.

Kali Linux has a package kali-win-kex that adds remote desktop access to the Linux GUI with a single updated component.

# install kex
sudo apt update
sudo apt upgrade
sudo apt install -y kali-win-kex
# Jack up the install to everything
sudo apt install -y kali-linux-large

Launch

Launch the WSL2 Kali desktop from a terminal window. It will run full screen on the current monitor. Execute as you from a Linux command line to bring up the Linux GUI

kex --win -s

Execute this as you from Windows to bring up the Linux GUI

wsl -d kali-linux kex --win -s

Ref: https://www.kali.org/docs/wsl/win-kex/

Ubuntu

Just use Kali if you want a linux desktop

Install and execute as you

# install kex
sudo apt-get update
sudo apt-get upgrade
# ????
# sudo apt install -y ??
# Start it up
# ????

WSL cheat sheet

wsl ~ -d <distribution> starts the distribution and connects as default user Ex:wsl ~ -d kali-linux
wsl ~ -d <distribution> -u root starts the distribution and connects as root Ex:wsl ~ -d kali-linux -u root
wsl -d <distribution> -u root <command> starts the distribution and runs command as root Ex:wsl -d kali-linux -u root cat /etc/wsl.conf
wsl --setdefault <distribution> sets the default distribution name Ex: wsl --setdefault kali-linux

freemansoft/wsl2-utils