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.