Using Multiple Distros on WSL2

Image courtesy of Microsoft

As a Windows user, I often found myself facing limitations when it came to developing web applications or machine learning applications outside of the Linux environment. Microsoft, apparently recognizes the needs of developers, introduced a game-changing solution: WSL (Windows Subsystem for Linux) and its upgraded version, WSL2. In this post, I would like to share some notes on how I use WSL2 to streamline my development workflow.

What is WSL2?

For developers, Windows Subsystem for Linux 2, or WSL2, is an invaluable feature on Windows. It runs lightweight virtual machines with a fully functional Linux kernel, providing a seamless Linux experience right on your Windows machine. It also integrates with Visual Studio Code, enabling you to effortlessly launch tests, set up development environments, and even debug Linux projects. No more hassles of dual booting or virtual machines!

(base) user@Ubuntu:~$ cowsay "hello from WSL2"
 _________________
< hello from WSL2 >
 -----------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Getting Started with WSL2

If you don’t have WSL2 installed, you can follow the installation instructions from Microsoft. As a TLDR, you may use the following commands to get WSL2 up and running.

# To install WSL2 on systems without WSL
wsl --install

# To install WSL2 on systems with WSL1
wsl --set-default-version 2

Creating And Managing Isolated Development Environments

For me, one of the most valuable features of WSL2 is its ability to create multiple isolated development environments, ensuring clean separation of dependencies and avoiding conflicts. With isolated environments, you can experiment freely, test different configurations, and maintain project-specific setups. To set up multiple development environments, we leverage WSL2’s support for multiple Linux distributions, and register each environment as a different Linux distribution under WSL2.

Here’s how you can create a new development environment

Start by listing the existing WSL distributions using the command wsl --list. You'll see a list similar to this:

PS> wsl — list
Windows Subsystem for Linux Distributions:
Ubuntu (Default)

1. Choose a distribution to serve as the base for your new environment. In our example, let’s use “Ubuntu” as it’s the only distro available.
2. Export the base image by running wsl.exe --export <OriginalDistributionName> <FileName>. For instance, wsl.exe --export Ubuntu ubuntu.tar. This step creates a base image that you'll need only once.
3. Create a directory to store the new distribution. For example, you can use mkdir UbuntuNodeJS, where "NodeJS" is the name of your new distribution.
4. Import the base image under a different name with the following command: wsl.exe --import <ClonedDistributionName> <InstallLocation FileName>. For our example, it would be wsl.exe --import UbuntuNodeJS ./UbuntuNodeJS ubuntu.tar.
5. Start the new distribution using wsl --distribution <ClonedDistributionName>. In our case, it would be wsl --distribution UbuntuNodeJS.

If you need to move the distribution to a different location on your disk, follow these additional steps:

1. Export the distribution by using the command mentioned in step 1 above.
2. Ensure the distribution is not running by executing wsl.exe -l -v. If it's running, shut down WSL with wsl.exe --shutdown, and recheck its status with wsl.exe -l -v to confirm it's not running anymore.
3. Unregister the distribution using wsl --unregister <DistributionName>.
4. Proceed with steps 2 and 3 again, creating a new directory to store the distribution and importing it into WSL.

Other useful configurations of WSL2 distributions

When working with WSL2 distributions, you might come across some quirks that require customization. I’ve encountered a couple of situations where I needed to tweak my own WSL2 distros, and I want to share some of these notes here.

Changing a distribution’s hostname

One common customization is changing the hostname of a WSL2 distribution. You may want to do this to easily identify the distribution you’re using or to have unique hostnames for machines on the same network.

1. Open the configuration file using the command: sudo vim /etc/wsl.conf.
2. Add or edit the file to include the following section:
   [network]
hostname = MyHostName
generateHosts = false
3. To reflect the updated hostname, edit the hosts file by running: sudo vim /etc/hosts. Replace all instances of the old hostname with the new one.
4. Exit the distribution and wait for approximately 8 seconds. Then, list the running distributions using the command: wsl --list --running. Make sure the instance is no longer running. It's generally recommended to force a shutdown of WSL with wsl --shutdown for reliability.
5. Restart the WSL distribution, and you should see the hostname has been changed.

By following these steps, you can easily customize the hostname of your WSL2 distribution to suit your preferences and needs.

Changing DNS Resolver in WSL2 Distribution

Sometimes, you may encounter DNS resolution issues in your WSL2 distribution, for example, when using a firewall or VPN with no split tunnelling. If you don’t require DNS resolution to local resources, you can configure your WSL2 distribution to use public DNS resolvers instead. Here’s how you can do it:

1. Add the following setting to the /etc/wsl.conf file:
   [network]
generateResolvConf = false
2. Exit the WSL distribution and wait for approximately 8 seconds to ensure it has stopped running. You can verify this by running the command: wsl --list --running.
3. Shutdown WSL completely by executing: wsl --shutdown.
4. Edit or create the /etc/resolv.conf file and add the following configuration to use Google's DNS servers (use any DNS servers of your choice):
   nameserver 8.8.8.8
nameserver 8.8.4.4
5. Repeat steps 2 and 3 to restart the distribution.

By following these steps, you can configure your WSL2 distribution to use public DNS resolvers like Google’s servers, which can help resolve DNS issues and ensure smoother connectivity within your development environment.

Changing the default user of a WSL2 distribution

Instead of using the default root user, you may want to change the default user in your WSL2 distribution. Here’s how you can do it:

1. Create a new user in the distribution by running the command: adduser <newuser>. Replace <newuser> with the desired username.
2. Inside the WSL instance, switch to the root user and create or edit the /etc/wsl.conf file. You can use a text editor like nano or vim to do this.
3. Add the following lines to the /etc/wsl.conf file:
   [user]
default=<newuser>
Remember to replace <newuser> with the name of the user you want to set as default.
4. Save and close the /etc/wsl.conf file.
5. In PowerShell, run the command: wsl --terminate <distro name>. Replace <distro name> with the name of your WSL distribution.
6. Restart the WSL distribution, and the newly specified user will be set as the default user.

Hope you find these short notes useful! Feel free to drop me a note if you have any questions or recommendations on the above!

References

https://learn.microsoft.com/en-us/windows/wsl/
https://superuser.com/questions/1589877/how-do-you-clone-a-wsl-distro
https://github.com/MicrosoftDocs/WSL/issues/412#issuecomment-575923176
https://gist.github.com/coltenkrauter/608cfe02319ce60facd76373249b8ca6
https://askubuntu.com/a/1300672
https://learn.microsoft.com/en-us/windows/wsl/wsl-config
https://www.srccodes.com/change-hostname-ubuntu-microsoft-windows-subsystem-for-linux-wsl-wsl2-wsl-conf-unable-resolve-hosts-name-service-not-known-list-running-shutdown-vm-srccodes/
https://thenewstack.io/windows-subsystem-for-linux-brings-the-full-4-19-kernel-to-windows/