Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added updates to wsl mount docs #1123

Merged
merged 2 commits into from
Mar 22, 2021
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added WSL/media/wslmountsimple.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added WSL/media/wslmountvhd.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
68 changes: 49 additions & 19 deletions WSL/wsl2-mount-disk.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ This tutorial will cover the steps to identify the disk and partition to attach
> You will need to be on Windows 10 Build 20211 or higher to access this feature. You can join the [Windows Insiders Program](https://insider.windows.com/) to get the latest preview builds.
> Administrator access is required to attach a disk to WSL 2.

## Identify the disk
## Mounting a known formatted disk
craigloewen-msft marked this conversation as resolved.
Show resolved Hide resolved

In this simplest case, if you have a disk that is just used for storage and doesn't have any partitions, you can mount it directly using the `wsl --mount` command. First you need to identify the disk.
craigloewen-msft marked this conversation as resolved.
Show resolved Hide resolved

### Identify the disk

To list the available disks in Windows, run:

Expand All @@ -27,7 +31,31 @@ wmic diskdrive list brief

The disks paths are available under the 'DeviceID' columns. Usually under the `\\.\PHYSICALDRIVE*` format.

## List and select the partitions to mount in WSL 2
### Mount the disk

Then in Powershell you can mount the disk using the Disk path discovered above.

```powershell
wsl --mount <DiskPath>
```

![Mounting a drive in WSL](./media/wslmountsimple.png)

## Mounting a disk with unknown formats

If you have a disk that you aren't sure what file format it is in, or what partitions it has, you can follow the steps below to mount it.

### Identify the disk

To list the available disks in Windows, run:

```powershell
wmic diskdrive list brief
```

The disks paths are available under the 'DeviceID' columns. Usually under the `\\.\PHYSICALDRIVE*` format

### List and select the partitions to mount in WSL 2

Once the disk is identified, run:

Expand All @@ -39,7 +67,7 @@ This will make the disk available in WSL 2.

Once attached, the partition can be listed by running the following command inside WSL 2:

```powershell
```bash
lsblk
```

Expand All @@ -49,7 +77,7 @@ Inside Linux, a block device is identified as `/dev/<Device><Partition>`. For e

Example output:

```powershell
```bash
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sdb 8:16 0 1G 0 disk
├─sdb2 8:18 0 50M 0 part
Expand All @@ -59,7 +87,7 @@ sdc 8:32 0 256G 0 disk /
sda 8:0 0 256G 0 disk
```

## Identifying the filesystem type
### Identifying the filesystem type

If you don't know the type of filesystem of a disk or partition, you can use this command:

Expand All @@ -69,7 +97,7 @@ blkid <BlockDevice>

This will output the detected filesystem type (under the `TYPE="<Filesystem>"` format).

## Mount the selected partitions
### Mount the selected partitions

Once you have identified the partitions you want to mount, run this command on each partition:

Expand All @@ -82,7 +110,7 @@ wsl --mount <DiskPath> --partition <PartitionNumber> --type <Filesystem>
>
> If omitted, the default filesystem type is "ext4".

## Access the disk content
### Access the disk content

Once mounted, the disk can be accessed under the path pointed to by the config value: `automount.root`. The default value is `/mnt/wsl`.

Expand All @@ -96,6 +124,20 @@ If you want to unmount and detach the disk from WSL 2, run:
wsl --unmount <DiskPath>
```

## Mount a VHD in WSL

You can also mount virtual hard disk files (VHD) into WSL using `wsl --mount`. To do this, you first need to mount the VHD into Windows using the [`Mount-VHD`](/powershell/module/hyper-v/mount-vhd) command in Windows. Be sure to run this command in a window with administrator privileges. Below is an example where we use this command, and also output the disk path. Be sure to replace `<pathToVHD>` with your actual VHD path.
craigloewen-msft marked this conversation as resolved.
Show resolved Hide resolved

```powershell
Write-Output "\\.\PhysicalDrive$((Mount-VHD -Path <pathToVHD> -PassThru | Get-Disk).Number)"
```

You can use the output above to obtain the disk path for this VHD and mount that into WSL following the instructions in the previous section.

You can also use this technique to mount and interact with the virtual hard disks of other WSL distros, as each WSL 2 distro is stored via a virtual hard disk file called: `ext4.vhdx`. By default the VHDs for WSL 2 distros are stored in this path: `C:\Users\[user]\AppData\Local\Packages\[distro]\LocalState\[distroPackageName]`, please exercise caution accessing these system files, this is a power user workflow.
craigloewen-msft marked this conversation as resolved.
Show resolved Hide resolved

![Mounting WSL VHD](./media/wslmountvhd.png)
craigloewen-msft marked this conversation as resolved.
Show resolved Hide resolved

## Command line reference

### Mounting a specific filesystem
Expand Down Expand Up @@ -165,18 +207,6 @@ If `Diskpath` is omitted, all attached disks are unmounted and detached.
> [!NOTE]
> If one disk fails to unmount, WSL 2 can be forced to exit by running `wsl --shutdown`, which will detach the disk.

## Mount a VHD in WSL

You can also mount virtual hard disk files (VHD) into WSL using `wsl --mount`. To do this, you first need to mount the VHD into Windows using the [`Mount-VHD`](/powershell/module/hyper-v/mount-vhd) command in Windows. Be sure to run this command in a window with administrator privileges. Below is an example where we use this command, and also output the disk path. Be sure to replace `<pathToVHD>` with your actual VHD path.

```powershell
Write-Output "\\.\PhysicalDrive$((Mount-VHD -Path <pathToVHD> -PassThru | Get-Disk).Number)"
```

You can use the output above to obtain the disk path for this VHD and mount that into WSL following the instructions in the previous section.

You can also use this technique to mount and interact with the virtual hard disks of other WSL distros, as each WSL 2 distro is stored via a virtual hard disk file called: `ext4.vhdx`. By default the VHDs for WSL 2 distros are stored in this path: `C:\Users\[user]\AppData\Local\Packages\[distro]\LocalState\[distroPackageName]`, please exercise caution accessing these system files, this is a power user workflow.

## Limitations

- At this time, only entire disks can be attached to WSL 2, meaning that it's not possible to attach only a partition. Concretely, this means that it's not possible to use `wsl --mount` to read a partition on the boot device, because that device can't be detached from Windows.
Expand Down