feat: custom distro root filesystem type and mount options

[artiga033]

Summary of the Pull Request

#9339 , allows to use custom filesystem and mount options for the / mount point.

Depends on WSLg changes to add the corrosponding filesystem userspace progs microsoft/wslg#1426.

PR Checklist

• Closes: Add support for distro root filesystem other than ext4 #9339
• Communication: The issue has been existing for years but I don't see a core contributor participating the discussion, so I directly open this PR. It's okay to close this if this feature are considered inappropriate by you core team...
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized. I've only changed the files for en-US and zh-CN, because I think there's some external localization workflows. Also, I tried to add more localizations, however in somelanguages after my change the string length exceeds the msvc compiler restriction.
• Dev docs: I think no changes needed.
• Documentation updated: I will do it later if you think is PR is acceptable.

Detailed Description of the Pull Request / Additional comments

Features Included:

• Allows using --fs-type and --fs-mount-options when importing or installing a distro, to change the fs type and mount options for / mountpoint. Supported filesystems are ext4, btrfs and xfs
• For btrfs, when specifying a subvol= mount option, it will be automatically created. This enables customizing the subvolume layout. E.g. using ubuntu layout(@ and @home) for apps like timeshift to work properly. It is auto-created because normally in WSL we don't have a way (for the end user) to create such subvolumes before the distro is imported.
• Reasonable default mount options for the file systems if fs-mount-options is not supplied, as defined in /src/windows/service/inc/wslservice.idl
• Allows --manage --set-fs-mount-options to change the mount options of exsting distro.

Validation Steps Performed

New unit tests has been added and can be run via .\run-tests.ps1 -Fast --% /select:"@Name='UnitTests::UnitTests::ImportDistroWithFsType' OR @Name='UnitTests::UnitTests::ImportDistroWithFsMountOptions' OR @Name='UnitTests::UnitTests::ManageSetFsMountOptions'"

Also there are screenshots I and other community users posted in the related issue #9339 .

Moreover, here are some quick commands to give it a try in realworld

default to ext4 like current behavior:

wsl --install --from-file .\archlinux.wsl

use xfs with default mount options:

wsl --install --from-file .\archlinux.wsl --fs-type xfs

use btrfs with custom mount options:

wsl --install --from-file .\archlinux.wsl --fs-type btrfs --fs-mount-options compress=zstd,subvol=@,ssd,discard

migrate existing ext4 distro:

# NOTE: Prefer to use PowerShell Core (7.0). When using Windows PowerShell(5.0) you may encounter encoding issues with bsdtar.
# If you just like the Windows PowerShell(5.0), consider export to and import from a disk file to avoid pipeline encoding problem.
wsl --export archlinux - | wsl --import arch_btrfs .\arch_btrfs - --fs-type btrfs --fs-mount-options compress=zstd,subvol=@,ssd,discard

[artiga033]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

This PR adds support for custom root filesystem types and mount options when importing or installing WSL2 distributions. It addresses issue #9339, which requested support for filesystems other than ext4 (specifically btrfs and xfs). The feature allows specifying --fs-type and --fs-mount-options on --import and --install commands, plus --manage --set-fs-mount-options for existing distributions.

Changes:

• Adds --fs-type (ext4/btrfs/xfs) and --fs-mount-options arguments to --import and --install, and --set-fs-mount-options to --manage
• Stores fs type and mount options in the distribution registry, and passes them through to the Linux init at startup and during import
• Adds btrfs subvolume auto-creation during import when subvol= is specified in mount options
• Renames the default VHD filename from ext4.vhdx to distro.vhdx

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/windows/service/inc/wslservice.idl	Adds FsType/FsMountOptions parameters to RegisterDistribution/RegisterDistributionPipe, new SetFsMountOptions method, default constants, renames VHD default name
src/windows/service/exe/LxssUserSession.cpp/h	Implements SetFsMountOptions, threads fs type/mount options through registration pipeline
src/windows/service/exe/DistributionRegistration.cpp/h	Persists FsType/FsMountOptions to registry, applies fs-specific default mount options
src/windows/service/exe/LxssCreateProcess.h	Adds FsType/FsMountOptions fields to LXSS_DISTRO_CONFIGURATION
src/windows/service/exe/WslCoreVm.cpp	Passes configuration's FsType/FsMountOptions to init message
src/windows/service/exe/WslCoreInstance.cpp	Removes EINVAL from disk corruption detection
src/windows/common/svccomm.cpp/hpp	Exposes FsType/FsMountOptions on RegisterDistribution, adds SetFsMountOptions
src/windows/common/WslClient.cpp	Parses --fs-type/--fs-mount-options/--set-fs-mount-options CLI args
src/windows/common/WslInstall.cpp/h	Threads fs type/mount options through installation flow
src/windows/inc/wsl.h	Defines CLI argument constants
src/linux/init/main.cpp	Implements FormatDevice for btrfs/xfs, adds CreateBtrfsSubvolumeOnDevice
localization/strings/en-US/Resources.resw	Adds help text for new arguments
localization/strings/zh-CN/Resources.resw	Adds Chinese translations, inadvertently removes UTF-8 BOM
test/windows/UnitTests.cpp	Adds three new test methods; existing tests not updated for VHD rename

[Copilot]

Removing EINVAL (22) from the disk-corruption check is a behavioral regression. Mounting an empty VHD (no filesystem) returns EINVAL, which previously mapped to WSL_E_DISK_CORRUPTED. The existing CorruptedDisk unit test at line 2550 creates a VHD without a filesystem and expects WSL_E_DISK_CORRUPTED; with this change that test will now fail because EINVAL no longer triggers the WSL_E_DISK_CORRUPTED path. Either restore the EINVAL check or update the test to expect the new error message.

[artiga033]

@benhillis I have done the reviews. There's one remaining discussion https://github.com/microsoft/WSL/pull/14377/changes#r2901401367

As support for custom mount options is added, it's hard to distinguish between corrupted vhdx and invalid mount options. So I think maybe we should just give an EINVAL in both condition

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

---

You can also share your feedback on Copilot code review. Take the survey.

[artiga033]

They are auto generated, right?

[artiga033]

@benhillis PTAL. I think it's ready now. Thank you.

@benhillis I have done the reviews. There's one remaining discussion https://github.com/microsoft/WSL/pull/14377/changes#r2901401367

As support for custom mount options is added, it's hard to distinguish between corrupted vhdx and invalid mount options. So I think maybe we should just give an EINVAL in both condition

This is solved by changing the error message to inform the user of many possible reasons, including corrpted vhd, unmatched fstype or fs mount options.