WSL2 How-to: Prepare and Attach Virtual Drives (VHD)

The WSL Preview Edition (available via the Microsoft Store) introduces an additional argument for directly working with virtual disks.

WSL from the Microsoft Store introduces a new argument to directly mount a VHD:

wsl — mount — vhd <pathToVHD>

This post describes the procedure for adding a VHD to an existing WSL Ubuntu distribution.

Prerequisites

• Install the Windows Subsystem for Linux Preview edition from Microsoft Store:

• Once installation completes, note down the WSL version number:

• Perform quick verification from a PowerShell prompt to ensure the correct version is effective:

Create and Attach VHD to WSL2 Distro

Create Virtual Drive

The following command uses the PowerShell New-VHD cmdlet to create a dynamic (expandable) virtual disk with 10GB capacity at path C:\Users\<username>\wsl2-shared.vhdx:

PS C:\> New-VHD -Path $env:USERPROFILE\wsl2-shared.vhdx -Dynamic -SizeBytes 10GB

Attach Raw Disk to WSL 2 Distro

To attach the new disk to an existing WSL2 distro named Ubuntu-20.04, run the following, specifying option --bare:

PS C:\> wsl -d Ubuntu-20.04 --mount --vhd $env:USERPROFILE\wsl2-shared.vhdx --bare
...
The operation completed successfully.

Verify New Disk Details

To verify the disk has been attached to distribution named Ubuntu-20.04:

• Login

PS C:\> wsl -d Ubuntu-20.04

• Run lsblk and examine the output

$ lsblk
​
NAME MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
...
...
sdd    8:48   0    10G  0 disk
...

• The above displays the 10GB drive with name sdd
• parted can also be used to verify

$ sudo parted /dev/sdd print

Initialise Disk

To intialise the disk, the following will need to be performed:

1. Create partition table
2. Create partition
3. Format with ext4 and label partition

Create Partition table

• An msdos partition table can be created using parted:

~ $ sudo parted /dev/sdd mklabel msdos

Create Partition

• Create an ext4 partition, using all unallocated disk space:

~ $ sudo parted -a optimal /dev/sdd mkpart primary ext4 0% 100%

• Verify the partition details using lsblk:

~ $ lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT /dev/sdd
NAME   FSTYPE SIZE MOUNTPOINT
sdd            10G
└─sdd1         10G

The above shows new partition with name sdd1.

Format and Label Partition

• Format partition with ext4 filesystem using mkfs.

~ $ sudo mkfs.ext4 /dev/sdd1

Sample output from mkfs is shown below.

• Note down the partition UUID value as listed in your output. It will be required for testing and establishing appropriate entry in /etc/fstab
• In this example, the UUID is e9999b9b-5a8e-41e1-9881-a2f766838798

• Assign a partition label (for this example, label name is vhd-part1):

~ $ sudo e2label /dev/sdd1 vhd-part1

• Confirm the filesystem and partition details

~ $ lsblk -o NAME,LABEL,FSTYPE,SIZE,MOUNTPOINT /dev/sdd

Test Mount of ext4 Partition

Before setting up an entry in /etc/fstab, a quick test is carried out to ensure there are no issues when attempting to mount the partition.

Finding Partition UUID

• Confirm the disk/partition name by running blkid

~ $ sudo blkid
...
/dev/sdd1: LABEL="vhd-part1" UUID="e9999b9b-5a8e-41e1-9881-a2f766838798" BLOCK_SIZE="4096" TYPE="ext4" ....
...

• Ensure the UUID for the partition in the output above matches the one we noted previously, i.e.
  UUID="e9999b9b-5a8e-41e1-9881-a2f766838798"
• The UUID will be used to perform the mount

Manual Mount using UUID

• Create a mount point for the test:

~ $ mkdir -p /home/<username>/vhd-part1

• Mount using UUID:

~ $ sudo mount UUID=e9999b9b-5a8e-41e1-9881-a2f766838798 /home/<username>/vhd-part1

• Check by listing mounts:

~ $ mount -l | grep vhd-part1
...
/dev/sdd1 on /home/<username>/vhd-part1 type ext4 (rw,relatime) [vhd-part1]

• Create test file at the new mount point:

~ $ sudo touch /home/<username>/vhd-part1/test

• Check the file has been created as expected:

~ $ ls /home/<username>/vhd-part1/test
​
 /home/<username>/vhd-part1/test

• Clean up:

~ $ sudo rm /home/<username>/vhd-part1/test

• Unmount:

~ $ sudo umount /home/<username>/vhd-part1

Add Entry for Mount in /etc/fstab

By default, a WSL distribution automatically processes mounts contained in /etc/fstab. This behaviour can be modified by altering the mountFsTab parameter, which resides in the distribution's /etc/wsl.conf file. Refer to official documentation for further details.

• Append the following single-line entry to the WSL distribution /etc/fstab file

UUID=e9999b9b-5a8e-41e1-9881-a2f766838798       /home/<username>/vhd-part1    ext4    defaults     0       2

• In an environment where multiple WSL distros are installed (e.g. Kali and Ubuntu), the above entry will need to be added to each distribution's /etc/fstab file where the mount is required

Attaching the VHD at Session Start-up

Create/Modify Terminal Session

When logging into our distro via a Terminal session, we need to ensure the disk is attached before the /etc/fstab entry to be processed.

i.e, the equivalent of the following need to sequentially run when launching the session:

PS C:\> wsl -d Ubuntu-20.04 --mount --vhd C:\Users\<username>\wsl2-shared.vhdx --bare | out-null
PS C:\> wsl -d Ubuntu-20.04

The first command attaches the virtual disk to target WSL distro. if the disk is already attached, then this command will return the following error message,

VHD already mounted via wsl.exe --mount, please unmount the disk before launching.

For now, this message can be ignored (and also suppressed by piping to out-null) but at some point this approach should be refined.

Below is a sample Windows Terminal session, which includes the above commands as the value for the session’s Command Line:

pwsh.exe -Command "wsl.exe -d Ubuntu-20.04 --mount --vhd C:\Users\<username>\wsl2-shared.vhdx --bare | out-null; wsl.exe -d Ubuntu-20.04"

Test Terminal Session

• Launch session

• Check mount has been processed by running

$ mount -l | grep vhd-part1

Detaching a VHD

Once the virtual disk is attached using wsl --mount --vhd <path>, it remains attached until the host is rebooted, or WSL is shutdown.

wsl --unmount can be used to manually detach the VHD.

For example, to detach a VHD located at C:\Users\<username>\wsl2-shared.vhdx:

PS C:\> wsl --unmount \\?\C:\Users\<username>\wsl2-shared.vhdx