The purpose of this project is to let you easily download and install new Linux distributions under Windows Subsystem for Linux and seamlessly switch between them.
The rootfs archives are currently downloaded from Docker Hub's official images' repositories ("source") or published image layers ("prebuilt").
If you want to read about some of the challenges I faced while implementing the scripts, you can check out this blog post. This readme only contains usage information and some troubleshooting.
The scripts provided here are written in Python 3, and they need to be run from Windows, NOT from WSL. You can download a Python 3 installer from their official website, or you can use the one bundled with Cygwin. Since WSL is stored in %LocalAppData% for each user, you don't need admin rights in order to use any of the scripts.
To begin, clone the repository or download a copy of it.
This script can download the tarballs for the official images in Docker Hub.
The first argument of the script is the name of the image, optionally followed by a colon and the desired tag: get-source.py image[:tag]. For example, to get the rootfs tarball for Debian Sid, just run get-source.py debian:sid. If you don't specify a tag, latest will be used, which is generally the stable edition of the distribution.
$ python get-source.py debian:sid
[*] Fetching official-images info for debian:sid...
[*] Fetching Dockerfile from repo tianon/docker-brew-debian/.../sid...
[*] Downloading archive https://raw.githubusercontent.com/.../sid/rootfs.tar.xz...
[*] Rootfs archive for debian:sid saved to rootfs_debian_sid.tar.xz.
For presentation purposes, the following images and tags are available as of August 18th:
- debian – 8.5, 8, jessie, latest | jessie-backports | oldstable | oldstable-backports | sid | stable | stable-backports | stretch | testing | unstable | 7.11, 7, wheezy | wheezy-backports | rc-buggy | experimental
- ubuntu – 12.04.5, 12.04, precise-20160707, precise | 14.04.5, 14.04, trusty-20160802, trusty | 16.04, xenial-20160809, xenial, latest | 16.10, yakkety-20160806.1, yakkety, devel
- fedora – latest, 24 | 23 | 22 | 21 | rawhide | 20, heisenbug
- centos – latest, centos7, 7 | centos6, 6 | centos5, 5 | centos7.2.1511, 7.2.1511 | centos7.1.1503, 7.1.1503 | centos7.0.1406, 7.0.1406 | centos6.8, 6.8 | centos6.7, 6.7 | centos6.6, 6.6 | centos5.11, 5.11
- opensuse – 42.1, leap, latest | 13.2, harlequin | tumbleweed
- mageia – latest, 5
- oraclelinux – latest, 7, 7.2 | 7.1 | 7.0 | 6, 6.8 | 6.7 | 6.6 | 5, 5.11
- alpine – 3.1 | 3.2 | 3.3 | 3.4, latest | edge
- crux – latest, 3.1
- clearlinux – latest, base
This script can download the layers of the prebuilt images published on Docker Hub. This is what Docker downloads when you run docker pull.
The first argument of the script is the name of the image, optionally followed by a colon and the desired tag: get-prebuilt.py image[:tag]. For example, to get the rootfs tarball for Debian Sid, just run get-prebuilt.py debian:sid. If you don't specify a tag, latest will be used, which is generally the stable edition of the distribution.
$ python get-prebuilt.py kalilinux/kali-linux-docker
[*] Requesting authorization token...
[*] Fetching manifest info for kalilinux/kali-linux-docker:latest...
[*] Downloading layer sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4...
[*] Downloading layer sha256:6e61dde25369335dcf17965aa372c086db53c8021e885df0e09f9c4536d3231e...
[*] Downloading layer sha256:45f74187929d366242688b3d32ccb5e86c205214071b99e94c0214e7ff2bc836...
[*] Downloading layer sha256:e5b4b71338633a415ad948734490e368e69605ba508a5fa8ad64775433798fb2...
[*] Downloading layer sha256:3f96326089c0580ebbcbb68d2f49dce1d7b6fe5cd79d211e4c887b0c9cdbeb02...
[*] Downloading layer sha256:d4ecedcfaa73285da5657fd51173fa9955468bf693332c03dce58ded73615c62...
[*] Downloading layer sha256:340395ad18dbbbd79d902342eef997fbd3ecb6679ad5005e5e714e8b0bc11e77...
[*] Downloading layer sha256:b2860afd831e842446489d37f8933c71dbd4f5d5f4b13d35185c4341fcca9a84...
[*] Rootfs archive for kalilinux/kali-linux-docker:latest saved to rootfs_kali....tar.gz.
The install.py script is responsible for installing the tarballs as new rootfs.
The first argument of the script is either the a) name of the file or the b) same image:tag notation used in the get.py script: install.py image[:tag] | tarball | squashfs. You can install tarballs from sources other than the Docker Hub, however, they're not guaranteed to work.
The specified file can be a .tar* archive, or a SquashFS image with .sfs or .squashfs extension. In order to process SquashFS images, the PySquashfsImage Python module nees to be installed, which you can do with pip3 install PySquashfsImage.
To install the freshly downloaded rootfs_debian_sid.tar.xz archive, run install.py debian:sid or install.py rootfs_debian_sid.tar.xz.
$ python install.py debian:sid
[*] Probing the Linux subsystem...
[*] Default user is RoliSoft at /home/RoliSoft.
[*] Switching default user to root...
[*] Reading /etc/{passwd,shadow,group,gshadow} entries for root and RoliSoft...
[*] Removing leftover rootfs-temp...
[*] Copying rootfs_debian_sid.tar.xz to /root/rootfs-temp...
[*] Beginning extraction...
[*] Waiting for the Linux subsystem to exit...
[*] Backing current rootfs to rootfs_ubuntu_trusty...
[*] Switching to new rootfs...
[*] Writing entries of root and RoliSoft to /etc/{passwd,shadow,group,gshadow}...
[*] Switching default user back to RoliSoft...
This operation extracts the tarball into your home directory in WSL, then replaces the current rootfs with the new one.
Earlier version of this script spawned a new WSL shell, and ran the extraction command under the subsystem. For newer versions, the bundled ntfsea library provides functionality to write the NTFS extended attributes required for VoIFS, and as such, extraction now happens without the involvement of WSL. This means that broken rootfs installations can now be repaired to some extent, since the WSL does not have to be able to start beforehand.
Running bash after installation should launch the new distribution:
> bash
$ cat /etc/debian_version
stretch/sid
It's possible to write hook scripts which are copied to WSL and run as root by the installer during the initial installation.
Hooks have the file naming convention hook_<event>_<label>.sh, where:
event– Onlypostinstallis supported currently. Open a ticket if you have suggestions for more.labelall– Runs on all installations. Make sure to have your script check if the current environment is suitable and exit gracefully if not, otherwise you might end up breaking some of your installations.image– Runs on name of the image, which is the first argument before the tag separator. E.g.debianindebian:sid.label– Runs on a specific label. E.g.debian_sidfordebian:sid; see the value in/.switch_label, but it's generally the tag-separator replaced from:to_.
The hook scripts are currently run in the order of least to most specific: all -> image -> label.
The installer will set the REGULARUSER environmental variable to the name of your regular user.
To prevent the invocation of the hook scripts, specify the --no-hooks argument to the installer.
A sample global hook script is provided in hook_postinstall_all.sample.sh. If you would like to run this during all of your installations, remove the .sample from the file name.
The provided script supports Arch Linux, APT-based (such as Debian and Ubuntu) and RPM-based (such as Fedora and CentOS) distributions. For all other distributions, it will gracefully terminate.
As noted above, the REGULARUSER environmental variable will be provided by install.py, which is the name of your regular user. This value will be used to add your user to the corresponding sudo group, e.g. sudo on Debian/Ubuntu and wheel on Fedora/CentOS.
If you would like your user to be added directly to sudoers with NOPASSWD, send SUDONOPASSWD=1 as an environmental variable.
The ROOTPASSWD environmental variable should contain the password to set for the root account. If this is not specified, the root password will not be reset. On most distributions the root account has no password, i.e. it is locked.
Additionally, the WINVER environmental variable allows for feature detection of the LXSS, so patches can be applied accordingly. E.g. chroot became available in 14936, so fakeroot workarounds are not required anymore.
On Arch Linux, the AUR helper pacaur will be installed unless WITHOUTPACAUR=1 is set as an environmental variable.
The script does the following:
- Upgrades the system, installs some critical missing packages. (Such as
apt-utilson Debian.) - Fixes locale warnings with apt/dpkg.
- Resets the root password, if asked.
- Installs
sudoand adds user to correspondingsudogroup or directly tosudoers. - Fixes sudo hostname resolution warning.
- Installs
pacaurand patchedfakerootformakepkgon Arch, and if WSL build is older than 14936,chroot()faker forpacman. - Installs basic dependencies required to install new distributions.
- Installs git, vim, tmux.
The switch.py script is responsible for switching between the installed distributions.
All installed distributions are labelled through a .switch-label file in the root directory. This is created from Windows, so it is not visible from within WSL and is only used by the switcher script.
When switching between distributions, the rootfs folder is renamed: the old one will get the value from the .switch-label file appended to it, e.g. rootfs_debian_sid, while the new one will be renamed from its rootfs_ubuntu_trusty name to rootfs in order to become the active one.
The /home, /root and similar directories are stored separately, and as such switching between distributions can be seamless, as your personal and dotfiles will persist and will never be touched during any operation.
The default installation is Ubuntu Trusty. Any rootfs directory with no switch label inside will automatically be labelled ubuntu:trusty, so this is the argument you'll have to specify if you want to go back to the original installation.
When the script is run without any arguments, the list of installed distributions will be returned:
$ python switch.py
usage: ./switch.py image[:tag]
The following distributions are currently installed:
- debian:sid*
- fedora:rawhide
- ubuntu:trusty
To switch back to the default distribution, specify ubuntu:trusty as the argument.
To switch between the distributions, just run the script with the image:tag you want to switch to:
$ python switch.py fedora:rawhide
[*] Probing the Linux subsystem...
[*] Moving current rootfs to rootfs_ubuntu_trusty...
[*] Moving desired rootfs_fedora_rawhide to rootfs...
$ bash -c 'dnf --version'
1.1.9
Installed: dnf-0:1.1.9-6.fc26.noarch at 2016-08-12 08:30
Built : Fedora Project at 2016-08-09 16:53
...
$ python switch.py debian:sid
[*] Probing the Linux subsystem...
[*] Moving current rootfs to rootfs_fedora_rawhide...
[*] Moving desired rootfs_debian_sid to rootfs...
$ bash -c 'apt-get -v'
apt 1.3~pre2 (amd64)
Supported modules:
*Ver: Standard .deb
...
As mentioned before, switching is just 2 directory rename operations. However, WSL cannot be running while this is happening.
-
Figure out pulling and merging the layers from Docker Hub directly, in order to support all published prebuilt images. The procedure is thoroughly documented on the Docker Registry HTTP API V2 page, however, merging the downloaded layers might present an issue.Done, seeget-prebuilt.py. -
Check whether extracting the SquashFS files from within ISO images to a rootfs works as well as Docker's rootfs tarballs. If so, implement new installer to automate it.Done, installer now supports SquashFS images as the first argument. -
Implement hooks, so patches can be applied to fix WSL issues on a per-image basis, or just user-specific ones, such as preinstalling a few packages.Done, see section "Post-install hook scripts". -
Figure out if it's possible to attach the Linux-specific metadata from outside of WSL, so then tarballs can be extracted and processed without invoking WSL.Done, installation now happens without spawning WSL for extraction. If you wish to use this in your own project, seentfsea.[c|py].
Looks like all the challenges I listed here initially have been solved. Feel free to open a new ticket if you have any suggestions on how the project could be enhanced.
- no root rights / no
sudo/su -lfails withAuthentication failure
The script migrates both your regular user and root's password, however, for some reason I found it to be not working perfectly with all distributions in case of root.
In any case, to fix this, you can switch the default user to root on WSL and then reset the root password with with:
> lxrun /setdefaultuser root
> bash
$ passwd
Logging in with su -l as root should work now. If passwd is not available, you can install it with the package manager of the distribution. Same goes with sudo, just make sure to edit the sudoers with visudo to empower your regular account.
sudofails withno tty present and no askpass program specified
This happens if your WSL is from the AU update. Subsequent Insider builds do not have this issue. A workaround for this issue is to run it with sudo -S, which instructs sudo to read the password from stdin.
You can add an alias for this workaround to your .bash_profile:
alias sudo="sudo -S"
pacmanfails withcould not change the root directory (Function not implemented)
This happens because WSL did not support chroot() before build 14936, and you are running one of them. A workaround for this issue, albeit not a clean solution, is to mock the chroot() function.
To compile a library with a no-op chroot(), run:
echo 'int chroot(const char *path){return 0;}' > chroot.c
gcc chroot.c -shared -fPIC -o libmockchroot.so
You can then inject this via LD_PRELOAD, during each command execution:
LD_PRELOAD=libmockchroot.so pacman ...
If you installed Arch Linux with the provided global hook script and your WSL was detected not to have chroot support, a library was already written to /lib64/libmockchroot.so and added to /etc/ld.so.preload, so you will not need to compile it manually or specify it everytime with LD_PRELOAD.
You can view its source and compilation instructions in the libmockchroot.so gist.
- get-source.py returns "Failed to find a suitable rootfs specification in Dockerfile."
The Dockerfile has no ADD archive.tar / directive. All suitable Linux distributions are packaged similarly and added into root with this directive. Its absence may mean you are trying to download an application based on an OS instead, or the Dockerfile for the operating system is a bit more complex than just "add these files".
FROM directives are not currently processed. Try downloading the image with get-prebuilt.py.
- install.py returns an error after "Beginning extraction..."
Earlier versions of the script invoked WSL for the extraction part, and this proved quite problematic in scenarios where some depedencies were missing in the distribution, it was behaving in a non-standard way, or the current WSL was broken to begin with.
Current versions of the script extract the archives from Windows and write the necessary NTFS extended attributes for WSL at the same time. This is less errorprone, and does not require a working rootfs to be present.
In case you get errors with the newer versions, open %LocalAppData%\lxss from Windows Explorer and try checking if you have permission to write into the /root or /home/username directories. Also check if there are any leftover rootfs-temp directories in them, if so, make sure to delete them.
