Moving a WSL virtual disk to another drive with automation

I have a couple disk drives in my experimental box and I want to move the WSL disks to one of the secondary, non-boot, drives. I want to use the bandwidth that exists on multiple drives on multiple buses and get better performance for my WSL instances. I do the same thing for VMS that I run in VMware Workstation or Fusion.

All the text on this page came from the video transcript of  Moving a WSL virtual disk to another drive

WSL Distributions

WSL is managed as registered distributions. Each one of those distributions has an associated vhdx. Those are located on the C:\ drive so also I tend to run out of C:\ space because I do all kinds of other things there. We're going to need to do a couple tweaks to move them and make this work. There's no way to edit this easier to do what we want or make the change with just a config file change.

Migration Discussion

We're going to destroy the existing registration and recreate the registration with the vhd somewhere else.

1. Terminate whatever distributions are running.
2. Create a backup of the vhd and other info which results in a .tar file
3. Unregister the instance which will wipe out this entire stack
4. Import the .tar backup into WSL. 

I created some automation for this. It creates the directories for the backup and the new home for the WSL-registered VHD.  We create a backup of each VHD into tar files.  Those go in the backups directory. We're also going to need a directory we're actually going to put the VHD once we rehydrated it.

You can do all this by hand. There are plenty of sites out there to do this. Or you can look at my automation script and figure out what the script's doing.  The script steps are 

1. Update WSL
2. Terminate the distribution 
3. Create a tar backup of the vhd 
4. Unregister this with a WSL. That removes the registration and deletes the vhd. 
1. You got to create this backup before you do this unregistering thing.
5. Run wsl.exe  import. It creates a vhd from the backup and registers it with esl
6. The last thing we can do is we can set the imported distribution as the default WSL if you want to so every time you can have a default distribution. I don't tend to worry about the default distribution because I target the WSL on the CLI with pretty much every command or every session.

We may have some cleanup to do. 

We may need to restore the default Linux user to WSL if we don't want to default to root, UID 0. The default user which one you shell into by default is actually a registry entry that is lost in the move. The import doesn't let you set a non-root user.  That's a defect in my opinion I'm sure there's an outstanding bug request for it

We have this set of scripts in https://github.com/freemansoft/wsl2-utils The README.md walks you through usage and gives examples of the sizing of the backups. I had Ubuntu and Kali on my machine. There are three backups for Kali Linux

The 5 backups in the snip:

1. Fresh install 500KB default install
2. Windows display integration installed, with one command, 3GB
3. Full Kali max install 18GB
4. Fresh Ubuntu default install 1.3GB
5. Updated Ubuntu base install 1.5GB

I have plenty of space on my I. It is 800GB 800 so it was no big deal for me to back up these pretty big files. I have plenty of space so I just leave the tar files there in case I want to roll back to one of those versions

Script Discussion

This walkthrough assumes I'm moving a Kali Linux WSL instance to my I:\ drive. Here is a sample output from a test run.

Export kali-linux to file I:\wsl-export\kali-linux-20230619-070558.tar

Export in progress, this may take a few minutes.

The operation completed successfully.

Unregistering existing instance of kali-linux

    Non destructive mode

Importing kali-linux to location I:\wsl\kali-linux from export file I:\wsl-export\kali-linux-20230619-070558.tar    

    Non destructive mode

Setting default wsl distribution to kali-linux

    Non destructive mode

  NAME                   STATE           VERSION

* kali-linux             Stopped         2

  docker-desktop-data    Stopped         2

  Ubuntu-20.04           Stopped         2

  docker-desktop         Stopped         2

The first thing it does is it checks to see if Kali Linux exists and terminates the program if not. Then it stops/terminates that running instance. It exports it to the tar file and it tells you the status of the export. It unregistered the existing instance of Kali Linux, logging that.  Then it imports Kali Linux from the tar file and registers with the same distribution name. You can set the default. In my case the logs say non-destructive. There is a mode in the script that defines the last three steps as non-destructive so you can verify your settings prior to doing the actual move.

You don't have to use my program right. I think it's cool because automation is repeatable. The code is at  http://github.com/freemansoft/wsl2-utils The only script in there at the time of this blog is move-distribution.ps1.

There are a bunch of parameters at the top of the file. (6/2023 sample) 

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 - default adds timestame to avoid 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

)

The big things are

• The source distribution name, its WSL registration name
• The backup file location
• The backup file name.  This one includes a date so you can take repeated backups without overwriting previous ones.
• Future todo: Create a backup recovery script that doesn't do an export
• The new location for the WSL vhd after the import
• The WSL registration name to use for the import.  It defaults to the same name but could be something different.
• A flag that tells us if the imported WSL distribution should be set as the default.
• A test flag that runs creates the backup and then logs the destructive operations it would have taken, un-registration, import and setting the default distribution
• This flag is set to false, non-destructive.  You have to change it to true to actually cause the unregister/import actions.

WSLg and Kali

It's super easy here to make Kali Linux run WSLg with graphics. It is a single command see the README.md in the repo. See this article https://joe.blog.freemansoft.com/2023/06/run-kali-linux-gui-in-wsl2-with-only.html

Final Comments.

I hope that was useful it was longer than I expected considering a lot of blogs are already out there about it.  Have a great day and if you need to move your WSL instance... Look at the docs in other places Look at the docs here. Or, try this script but test it first

Video

Revision History

Created 2023 06