Windows Subsystem for Linux: Installing Arbitrary Distributions
As of the latest version of Windows 10 build 16299.19, also known as the “Fall Creator’s Update”, Linux distributions are now available in the Windows Store, and multiple distributions can be installed and run alongside one another. This is great news, but the old way did offer one feature the latest release makes a bit more fragile: the ability to install a custom distribution of one’s own choosing. I’ve seen various ways of doing this with the Fall Creator’s Update published, the most common of which is to install one of the distributions from the App Store and replace its rootfs directory with one of your own. I wanted a more elegant solution. Of particular interest to me are Gentoo and Fedora - note that Fedora will eventually be in the Windows Store officially, but I didn’t want to wait.
The Registry
Linux distributions are now registered in the Windows registry on a per-user basis. This is located at:
\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\
You can register your own distribution by creating a .reg file containing the following:
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{6be8e482-66f8-4475-b570-aa8c2fd35809}]
"State"=dword:00000001
"DistributionName"="Fedora"
"Version"=dword:00000001
"BasePath"="C:\\Linux\\Fedora"
"KernelCommandLine"="BOOT_IMAGE=/kernel init=/init ro"
"DefaultUid"=dword:000003e8
"Flags"=dword:00000007
"DefaultEnvironment"=hex(7):48,00,4f,00,53,00,54,00,54,00,59,00,50,00,45,00,3d,\
00,78,00,38,00,36,00,5f,00,36,00,34,00,00,00,4c,00,41,00,4e,00,47,00,3d,00,\
65,00,6e,00,5f,00,55,00,53,00,2e,00,55,00,54,00,46,00,2d,00,38,00,00,00,50,\
00,41,00,54,00,48,00,3d,00,2f,00,75,00,73,00,72,00,2f,00,6c,00,6f,00,63,00,\
61,00,6c,00,2f,00,73,00,62,00,69,00,6e,00,3a,00,2f,00,75,00,73,00,72,00,2f,\
00,6c,00,6f,00,63,00,61,00,6c,00,2f,00,62,00,69,00,6e,00,3a,00,2f,00,75,00,\
73,00,72,00,2f,00,73,00,62,00,69,00,6e,00,3a,00,2f,00,75,00,73,00,72,00,2f,\
00,62,00,69,00,6e,00,3a,00,2f,00,73,00,62,00,69,00,6e,00,3a,00,2f,00,62,00,\
69,00,6e,00,3a,00,2f,00,75,00,73,00,72,00,2f,00,67,00,61,00,6d,00,65,00,73,\
00,3a,00,2f,00,75,00,73,00,72,00,2f,00,6c,00,6f,00,63,00,61,00,6c,00,2f,00,\
67,00,61,00,6d,00,65,00,73,00,00,00,54,00,45,00,52,00,4d,00,3d,00,78,00,74,\
00,65,00,72,00,6d,00,2d,00,32,00,35,00,36,00,63,00,6f,00,6c,00,6f,00,72,00,\
00,00,00,00
Take note of a few things here:
- The name of the parent key must always be a unique UUID
- DefaultUid is a hexadecimal representation of the UNIX UID that the subsystem will launch with - make sure you have a user created in your custom Linux environment beforehand.
- Also note that this user should be able to become root. Add the user to the wheel group and/or preinstall ‘sudo’
- BasePath is going to be the location of this Linux environment on the host filesystem. This can be placed anywhere as long as it’s specified in this key.
- Flags set the way it is appears to indicate that a WSL environment has been installed and doesn’t require further bootstrapping. Documentation on this is limited, insights welcome.
Import this .reg file into the registry after customizing it appropriately.
Preparing the Linux filesystem
You’ll need to install one of the Linux distributions from the Windows Store in order to get started. It doesn’t matter which one you choose. Once that’s installed (I won’t cover that setup here, as it’s documented thoroughly elsewhere), become root, and fetch a tarball containing a filesystem for your distribution of choice. In my example we’ll use a Fedora docker image, obtained from Red Hat’s Koji build system. Make a new directory and cd into it. Extract the tarball:
root ~ # mkdir fedora
root ~ # cd fedora
root ~/fedora # tar Jxf /mnt/c/Users/brad/Downloads/Fedora-Docker-Base-27-20171105.n.0.x86_64.tar.xz
This Fedora tarball contains another tarball within it. A directory with a long sequence of letters and numbers will be created. Tab completion is your friend here. Under this directory the second tarball, layer.tar, contains the actual Linux filesystem. Note this situation is unique to Fedora’s Koji tarballs - others such as Gentoo stage3 directly extract to filesystem contents. Extract the inner tarball:
root ~/fedora # cd 5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9
root ~/fedora/5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9 # tar xf layer.tar
Since this Fedora image is intended to be used in a docker container, it lacks a few things we’ll need. We’ll want to copy the resolv.conf file from the parent Linux environment into it:
root ~/fedora/5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9 # cp -v /etc/resolv.conf etc/
Then we’ll want to chroot into the new Fedora filesystem to be able to work on it further:
root ~/fedora/5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9 # chroot .
Install the passwd package:
root ~/fedora/5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9 # dnf -y install passwd
Set a password for root:
[root@Odyssey /]# passwd
Changing password for user root.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
Add a user for yourself, and make sure it’s a member of the wheel group. Note here that I’m specifying a UNIX UID matching that expected by the registry entry above, as well as ensuring the user is a member of the wheel group so it’s permitted to become root as well as use sudo:
[root@Odyssey /]# useradd -u 1000 -m brad
[root@Odyssey /]# passwd brad
Changing password for user brad.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
[root@Odyssey /]# usermod -a -G wheel brad
[root@Odyssey /]# exit
root ~/fedora/5a666bb24354de5795820e875e208518e8ea0a249e57929639cd2c1797e447e9 #
Exit the chroot as depicted in the last two lines above. Recall that in the Registry example above I specified C:\Linux\Fedora as the location for this Linux environment. We’ll need to move it there. You’ll need to close all Linux environment Windows or you’ll have trouble with the following steps. Find the location of the Linux environment you installed from the store:
C:\Users\brad>powershell Get-ChildItem HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss
Hive: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss
[ snip ]
32df2d9} DistributionName : openSUSE-42
Version : 1
BasePath :
C:\Users\brad\AppData\Local\Packages\46932SUSE.openSUSELeap42.2_022rs5jcyhyac\LocalState
PackageFamilyName : 46932SUSE.openSUSELeap42.2_022rs5jcyhyac
KernelCommandLine : BOOT_IMAGE=/kernel init=/init ro
DefaultUid : 1000
Flags : 7
DefaultEnvironment : {HOSTTYPE=x86_64, LANG=en_US.UTF-8,
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/
usr/games:/usr/local/games,
TERM=xterm-256color}
Navigate to the directories we’ve been working in - these are under the BasePath corresponding to the distribution you installed, which in my case is:
C:\Users\brad\AppData\Local\Packages\46932SUSE.openSUSELeap42.2_022rs5jcyhyac\LocalState\rootfs\root\fedora
Using Explorer, cut (DO NOT copy!) the subdirectory you’ve been working in. Paste it into C:\Linux\Fedora (the BasePath of the Linux environment we defined ourselves) as rootfs. The resulting directory structure should be:
C:\Linux\Fedora\rootfs
Final Steps
We’ve now defined the custom WSL environment in the registry and preconfigured the Linux filesystem we’ll be using. Optionally, you can now set this WSL environment as default:
C:\ >wslconfig /s Fedora
And enter it:
C:\Users\brad>wsl
[brad@Odyssey brad]$
You can also enter a WSL environment by specifying its UUID as you set it in the registry:
C:\Users\brad>wsl {6be8e482-66f8-4475-b570-aa8c2fd35809}
[brad@Odyssey brad]$
Have fun with your new Linux subsystem environment!