Table of Contents

Windows Subsystem for Linux 2 (WSL 2), and Ubuntu

Other Windows 10 related notes

JYP is still working on this page! Some content may be out of date, or still related to WSL 1

The commands on this page have to be typed:

  • either in Windows PowerShell terminals
  • or in bash terminals running in WSL

It should be clear enough which type of terminal you have to use

What is WSL ?

Windows Subsystem for Linux (WSL) lets you run a Linux distribution on your Windows computer, without the overhead of a traditional Virtual Machine (VM) or dual-boot setup

More reading:

Prerequisites

Windows version

The basics before starting

Once you have verified that your Windows is recent enough, you should also:

Computer CPU and memory

Contrary to other virtual machines, WSL is well integrated with the Windows operating system and the hardware drivers and has a low default CPU and memory footprint!

Disk usage

Overview

FIXME The rather technical Disk usage sections below should be moved somewhere else!

How does it work?

WSL+Linux seems to use a combination of actual Windows files/folders and ext4 Linux partitions stored in .vhdx (Dynamic Virtual Hard Disk) files. The Linux disk (of type ext4) is stored in a single some_name.vhdx Windows file that will automatically grow until it reaches a predefined maximum size of 256 Gb (if there is enough space on the Windows disk…)

Disks seen from Linux

The disks and partitions usage, as seen from Linux, can be displayed with df -h 

stdu@sadira034:~$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sdb        251G  1.5G  237G   1% /
tmpfs           6.2G     0  6.2G   0% /mnt/wsl
tools           472G  118G  355G  25% /init
none            6.2G     0  6.2G   0% /dev
none            6.2G  8.0K  6.2G   1% /run
none            6.2G     0  6.2G   0% /run/lock
none            6.2G     0  6.2G   0% /run/shm
none            6.2G     0  6.2G   0% /run/user
tmpfs           6.2G     0  6.2G   0% /sys/fs/cgroup
drivers         472G  118G  355G  25% /usr/lib/wsl/drivers
lib             472G  118G  355G  25% /usr/lib/wsl/lib
C:\             472G  118G  355G  25% /mnt/c
D:\             480G  2.6G  478G   1% /mnt/d

Some important disk locations

Sample disk usage

Hyper-V requirements

You can skip reading this WSL requirement if you are installing WSL for the first time, and are therefore directly installing WSL 2

Come back here later (only) if you have problems

WSL 2 needs the Virtual Machine Platform to be enabled on your computer. If you have never used WSL before, you can probably go directly to the Base installation section and wsl should install everything correctly

If you have problems (e.g. The virtual machine could not be started because a required feature is not installed), or if you are updating WSL 1 to WSL 2, type systeminfo in a PowerShell to check if your machine meets the Hyper-V requirements

If you get a No for one of the Hyper-V requirements, check the virtualization settings in your computer BIOS.
You can have a look at the x86 virtualization wikipedia page if you are wondering what VT-x and VT-d means for Intel processors (AMD-v and AMD IOMMU for AMD)

Example: HP laptop with an Intel CPU, and virtualization not activated in the BIOS

Miscellaneous technical links and information, in case we need this later…

Base installation

After the base installation

After completing the base installation steps, you get a Ubuntu machine with:

Opening a terminal

Having a terminal you can efficiently interact with is the basis of your future work with WSL+Ubuntu!

Optional reading (if you really have time):

The default terminal

The default terminal will be available without installing extra applications like WSLtty or the Windows Terminal. It will work for testing WSL, but it is not recommended if you want to work comfortably

The Default WSL+Ubuntu terminal is basically a bash shell running inside a regular Windows cmd text console. You do not need to have an X server running to use it!

There are several ways to open a default terminal:

Copy/paste in the default terminal

Check this Windows Terminal section

The WSLtty terminal

  • If you can't open a WSLtty terminal after upgrading from WSL to WSL 2, install the latest version of WSLtty !

WSLtty allows you to use the efficient Mintty as a terminal for WSL. You do not need to have an X server running to use it!

The Windows Terminal

The Windows Terminal is really nice and powerful, and will become the recommended (by JYP) option as soon as we can use regular Linux select-copy/paste (Feature request: add xterm-style select/copy/paste options)

Terminals started from Linux

You can install additional graphical terminals in the Linux installation, but you will need to have a running X server if you want to open them. In these terminals, the usual Linux copy/paste rules will apply!

Where are the files?

Accessing Linux files from the Windows Explorer

Accessing Windows files from Linux

When you are in a Windows explorer window, you can directly open a Linux terminal in a specific directory by holding Shift and right-clicking on a directory and selecting Ouvrir l'interpréteur de commandes Linux ici (Open the Linux command line here?) in the context menu.

The Windows partitions are mounted under /mnt in Linux: 

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sdb        251G  1.5G  237G   1% /
[...]
C:\             472G  121G  351G  26% /mnt/c
D:\             480G  4.2G  476G   1% /mnt/d

Read the Mounting disks and network drives section if you want to access remote server disks on your local network, or just want to access USB disks/sticks on your local computer.

Misc

Linux version installed

You can use the following commands to get some information about WSL and the currently installed Linux 

$ date
Tue Sep 13 16:48:10 CEST 2022

$ env | grep WSL
WSL_DISTRO_NAME=Ubuntu_custom
WSL_INTEROP=/run/WSL/12_interop
WSL_GUEST_IP=192.168.113.203
WSLENV=
WSL_HOST_IP=192.168.112.1

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 20.04.5 LTS
Release:        20.04
Codename:       focal

$ cat /proc/version
Linux version 5.10.102.1-microsoft-standard-WSL2 (oe-user@oe-host) (x86_64-msft-linux-gcc (GCC) 9.3.0, GNU ld (GNU Binutils) 2.34.0.20200220) #1 SMP Wed Mar 2 00:30:59 UTC 2022

$ uname -a
Linux sadira034 5.10.102.1-microsoft-standard-WSL2 #1 SMP Wed Mar 2 00:30:59 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux

$ cat /etc/*release*
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=20.04
DISTRIB_CODENAME=focal
DISTRIB_DESCRIPTION="Ubuntu 20.04.5 LTS"
NAME="Ubuntu"
VERSION="20.04.5 LTS (Focal Fossa)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 20.04.5 LTS"
VERSION_ID="20.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

Ubuntu packages installed

$ dpkg --list | head -n 10
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name                           Version                           Architecture Description
+++-==============================-=================================-============-===============================================================================
ii  accountsservice                0.6.55-0ubuntu12~20.04.5          amd64        query and manipulate user account information
ii  adduser                        3.118ubuntu2                      all          add and remove users and groups
ii  alsa-topology-conf             1.2.2-1                           all          ALSA topology configuration files
ii  alsa-ucm-conf                  1.2.2-1ubuntu0.13                 all          ALSA Use Case Manager configuration files
ii  apparmor                       2.13.3-7ubuntu5.1                 amd64        user-space parser utility for AppArmor


$ dpkg --list > /mnt/c/Scratch/your_login/Ubuntu_Installed_List_`date +"%y-%m-%d"`.txt
$ wc -l /mnt/c/Scratch/your_login/Ubuntu_Installed_List_*.txt
642 /mnt/c/Scratch/your_login/Ubuntu_Installed_List_22-08-29.txt

Full (example) list of installed packages: ubuntu_installed_list_22-08-29.txt

Update ubuntu

Use the following to update your ubuntu installation:

$ sudo apt update && sudo apt upgrade

or 

$ sudo -s

$ apt-get update
$ apt-get upgrade

Managing WSL

This is just place to store some technical information, that will probably not be needed by most people

Getting ready for some real work

We often assume below that you are using the root account (with sudo -s, or sudo) when executing the apt* installation commands, and other admin commands

Create a backup before starting

Nothing will go wrong, but it does not hurt to save an image of your full installation, in case you want to try some really different settings later.

Specifying a correct system language

WSL will automatically try to use in the terminals the same language as the one used by the Windows computer, but this could lead later to some difficult to debug side-effects when you connect to remote Linux servers (e.g. the sort command may give different results !).

It is safer to force the Linux installation to use a standard English localization. The update-locale command will change the content of the /etc/default/locale file 

$ sudo update-locale LANG=en_US.UTF8
$ echo $LANG
en_US.UTF8

$ locale -v
LANG=en_US.UTF8
LANGUAGE=
LC_CTYPE="en_US.UTF8"
[...]
LC_ALL=

After updating the system localization (and possibly restarting wsl with wsl --shutdown), open the available terminals and type echo $LANG in order to check that are indeed getting en_US.UTF8

If you are still not getting en_US.UTF8 in some terminals (e.g. you are still getting C.UTF-8), you can check if you can override the localization options in the terminals settings. Check the Text options of the WSLtty terminals

Package management

How does it work ?

What about snap ?

FIXME Snap documentation

Installing extra package managers

Some useful commands

Example

$ dpkg -l | grep -i wsl
ii  ubuntu-wsl                        1.450.2                           amd64        Ubuntu on Windows tools - Windows Subsystem for Linux integration
ii  wslu                              2.3.6-0ubuntu2~20.04.0            all          collection of utilities for the Windows 10 Linux Subsystem

$ dpkg -L wslu
/.
/usr
/usr/bin
/usr/bin/wslfetch
/usr/bin/wslsys
/usr/bin/wslupath
/usr/bin/wslusc
/usr/bin/wslvar
/usr/bin/wslview
[...]

$ apt show wslu
Package: wslu
Version: 2.3.6-0ubuntu2~20.04.0
[...]
Description: collection of utilities for the Windows 10 Linux Subsystem
[...]

Adding useful packages

There is not that much installed by default in Ubuntu, and we use apt insall to get ready for some real work! 

$ sudo apt install gcc libglu1-mesa mesa-utils x11-apps xterm xfce4-terminal emacs evince eog imagemagick nco cdo netcdf-bin ncview

Notes:

Using an X server

You will need to have an X server running locally on your Windows 10 machine if you want to display graphics generated by the Linux running locally, or on a remote server. Applications running in text mode only (e.g. vi) do not require a running X server.

You will get a Can't open display error if no server is running (even if the DISPLAY variable is correctly defined) 

your_login@your_machine:~$ echo $DISPLAY
localhost:0.0
your_login@your_machine:~$ xterm &
xterm: Xt error: Can't open display: localhost:0.0
[Everything is fine after starting a local X server]
jyour_login@your_machine:~$ xterm &
[1] 55

Installing an X server

Read the Installing and configuring an X server page

Configuration (in your local Linux account)

Updating WSL and ubuntu

You don't have to worry about the Upgrade section if you have just installed WSL+Ubuntu, because you are already using the latest Ubuntu stable release!

WSL

Nothing to do! WSL is automatically updated, provided you have enabled the Get updates for other Microsoft products option

WSL command line options

Updating ubuntu

The Ubuntu 16.04.3 LTS that was initially installed from the Windows Store when the test computer was running Win 10 1709 was automatically updated to Ubuntu 18.04.2 LTS when the computer was updated to Win 10 1809. 

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 18.04.2 LTS
Release:        18.04
Codename:       bionic

We also ran the do-release-upgrade command to complete the upgrade (from 16.04 to 18.04) [ More info from WSL team - more info from Ubuntu ]

And we then ran the usual upgrade commands. These commands can be run any time for updating the installed packages 

$ sudo -s
$ apt-get update
$ apt-get upgrade

Full list of the resulting installed packages, generated with 

$ dpkg --list >$ dpkg --list > /mnt/h/Scratch/jyp/pkg_190221.txt
$ wc -l /mnt/h/Scratch/jyp/pkg_190221.txt
578 /mnt/h/Scratch/jyp/pkg_190221.txt

Upgrading Ubuntu

You can skip this section if you have just installed Ubuntu, since you are already running the latest stable release available

The updates are for maintaining the same version of Ubuntu (e.g. you go from version 18.04.2 to 18.04.5), while upgrades are for going from one major version to the next (e.g 16.xx ⇒ 18.xx ⇒ 20.xx). We try to only use the stable major releases, that have an even version number.

We use the LTS versions (Long Time Support) to ensure even more stability, which means that we will get updates of a given major release for quite some time after the next major release is available, so it is not mandatory to upgrade Ubuntu if you are still receiving updates for the (major) release you are using

There should not be any risk, but it may be a good idea to create a backup of your current Ubuntu before upgrading it!

Use sudo for each command below, or just become root by using sudo su -

Cleaning up things

* How to Clear Apt Cache

Advanced configuration

Get Linux configuration files

This assumes that you have already created a private/public ssh key pair and that the private key is available somewhere in the Windows 10 computer

ssh from WSL

Authorizing ssh to use old dsa keys

dsa ssh keys are disabled by default (becoming obsolete). ssh will ask for your password even if you have a ~/.ssh/id_dsa file. ssh -v will print Skipping ssh-dss key /home/<your_login>/.ssh/id_dsa - not in PubkeyAcceptedKeyTypes. The solution is to generate a new couple of public/private keys not based on dsa encryption, or to use the user ssh config file to authorize dsa (source)

Using Putty Pageant as an ssh agent

This assumes that you have installed the full Putty package (with the msi installer), converted your private ssh key with PuTTYgen, and unlocked the converted ssh private key in Pageant.

The converted ssh private key is located in a Windows 10 folder

Note: the other similar solutions are ssh-agent-wsl (the key is stored in the Windows ssh-agent instead of Pageant) or wsl-ssh-pageant

Using Ubuntu as an ssh-agent

The ssh key (and other ssh settings) are in the ~/.ssh directory of your WSL+Ubuntu account

This is the most simple setting, but there will be one running ssh-agent per terminal, and the key will be stored independently for each terminal (which means that you will have to type ssh-add and your pass-phrase for each terminal)

Notes & TODO

ssh to WSL

FIXME Maybe check OpenSSH-Server connection issues

Maybe it could be useful to do a ssh from the Win10 part of the machine to the WSL part, and from outside the machine to the WSL part

It would probably already be enough to enable the ssh server on Win10 (the ssh 1709 release beta features are now officially in Win10)

Google search: wsl ssh

Creating shortcuts to Linux programs on the Windows desktop

Mounting disks and network drives

By default, the local disks and the external USB disks available (and decrypted!) when WSL is started (i.e. when the first WSL terminal is opened) are automatically available (mounted) in /mnt : the content of C:\ is available in /mnt/c, etc… The list of available disks is refreshed when the Windows session is restarted (the user logs out and in, or Windows is rebooted) or when just WSL is restarted.

Extra local disks or network drives (what you can access by opening \\dfshost\dfs\ in the file explorer when you are on the LSCE network) can be either mounted on the fly with the mount command, or automatically by configuring the /etc/fstab file.

You will access the network drives with the access rights you have in the current Windows session (and you may have to access the drives in Windows before you can mount them in WSL)

Warning! In all cases, the owner, groups and permissions displayed may not be accurate (but the actual access rights will apply).

Enabling metadata

Some access rights handling can be slightly improved by automatically enabling the metadata mount option. This will allow you to use chmod/chown on local NTFS disks (disks directly connected to your computer, e.g. /mnt/c/Users/your_login).

  1. become root in a terminal with: sudo -s
  2. create a /etc/wsl.conf with the following content:
    [automount]
options = "metadata"

You need to restart WSL+ubuntu to activate the new content of /etc/wsl.conf. See below an example of the mount -l output:

Optional: more details about wsl.conf in WSL launch settings, How to use wsl.conf and metadata and access rights management

On-the-fly mount

You have to create a mount point in the existing /mnt directory and then use the mount command 

# Must be root for most 'mount' related commands
$ sudo -s

# Create the mount point (once), e.g. for accessing /home/scratch01 on the local LSCE servers
# This works when the Windows 10 computer is on the LSCE network
$ mkdir /mnt/scratch01

# Mount the remote disk
$ mount -t drvfs '\\dfshost\dfs\scratch01' /mnt/scratch01

# List the mounted disks
$ mount -l
[...]
\\dfshost\dfs\scratch01 on /mnt/scratch01 type drvfs (rw,relatime,case=off)

# Unmount the disk, or just shutdown Windows or WSL when you are finished
$ umount /mnt/scratch01

If you connect a USB disk/stick and windows sees it as a new J:\ drive, you can also manually mount it 

$ sudo -s

# Create the mount point (once)
$ mkdir /mnt/j

# Mount the USB disk
$ mount -t drvfs J: /mnt/j

# Unmount the disk, or just shutdown Windows or WSL when you are finished
$ umount /mnt/j

Automatic mount

The disks defined in /etc/fstab will be automatically mounted when you start WSL and if they are actually accessible from your Windows session (e.g. \\dfshost\dfs can only be accessed from the LSCE network)

You need to add 1 line per mount point to /etc/fstab, and create (once) the directories that will be used for mounting the disks 

$ sudo -s

# Create the mount points (once)
# The example below is to access the LSCE /home/users and /home/scrath01 disks
$ mkdir /mnt/users /mnt/scratch01

# Make a backup copy of /etc/fstab before modifying it (for safety reasons!)
$ cp -p /etc/fstab /etc/fstab.bak

# Add lines to /etc/fstab associating mount points and directories
$ cat /etc/fstab
LABEL=cloudimg-rootfs   /        ext4   defaults        0 0
\\dfshost\dfs\users /mnt/users drvfs defaults 0 0
\\dfshost\dfs\scratch01 /mnt/scratch01 drvfs defaults 0 0

# Try to mount all the disks in /etc/fstab
$ mount -a

# Check the result
$ mount -l
[...]
\\dfshost\dfs\users on /mnt/users type drvfs (rw,relatime,case=off)
\\dfshost\dfs\scratch01 on /mnt/scratch01 type drvfs (rw,relatime,case=off)

Accessing remote file systems with sshfs

FIXME

It seems this can be done with a combination of WinFsp and SSHFS-Win (see SSHFS remote directory mounting syntax for details

Extra resources

Useful mount options:

Useful links (used for writing this section):

Rebooting WSL

It is not possible to stop or reboot WSL like a regular Linux computer

Shutting down or rebooting the Windows computer will of course stop WSL but it's useful to be able to just stop/restart WSL in order to:

WSL can be stopped the following way. Warning: ​all the open terminals and running processes ​will be terminated!

Advanced usage

WSL security WARNING!

A regular Linux installation (on a Linux-only computer) is fairly secure,
but a Linux installation on WSL is not secure at all, by design

WSL+Linux is designed to allow you to easily use Linux on Windows, including very easily using the Linux root account without knowing any password of the Linux installation! 

PS C:\Users\your_login> wsl
wsl_default_user@your_machine:/mnt/c/Users/your_login$ whoami
wsl_default_user

PS C:\Users\your_login> wsl -u root
root@your_machine:/mnt/c/Users/your_login# whoami
root

This is a feature and not a security issue, because your installation is protected by your Windows account security

You should be aware (and act accordingly) that:

Creating a backup

Backup of a FULL Linux installation

You can use wsl to save a full Linux installation to a tar file, that can be:

Detailed --export example:

Backup of specific directories

You can also just create backups of specific directories:

Restoring or relocating a Linux installation

When we have the tar file of a FULL backup, we can use --import to install or restore it to a specific location.

Note:

Detailed --import example:

Questions FIXME

Uninstalling WSL or a distribution

Before uninstalling something, you probably want to create a backup, just to be safe…

Removing a specific Linux installation

This process is called unregistering (based on Unregister or uninstall a Linux distribution)

You just need to get the list of the currently installed Linux distributions, stop them and remove/unregister a specific distribution name 

> wsl -l -v
  NAME             STATE           VERSION
* Ubuntu           Stopped         2
  Ubuntu_custom    Running         2

> wsl --terminate Ubuntu_custom

> wsl -l -v
  NAME             STATE           VERSION
* Ubuntu           Stopped         2
  Ubuntu_custom    Stopped         2

> wsl --unregister Ubuntu_custom
Désinscription...

> wsl -l -v
  NAME             STATE           VERSION
* Ubuntu           Stopped         2

Removing the main Linux installation

If you remove the main installation (on C:\):

Removing WSL

wsl is a part of the Windows system and probably can't be removed.

Anyway, when all existing Linux distributions are uninstalled, there should not be any big .vhdx files remaining (i.e. no extra disk space used), and there will not be any Linux processes running (i.e. no extra CPU used).

Miscellaneous

Upgrading WSL 1 to WSL 2

You will be able to run existing WSL 1 installations with WSL 2, so upgrading should not be a problem!

Determining which version of WSL is installed

If you have never used WSL on a computer, WSL 2 will be installed directly when you follow the Base installation steps

You can determine if your installed Linux distributions are running on WSL 1 or WSL 2 by typing wsl -l -v in a PowerShell, but if you are not sure if you are currently using WSL 1 or WSL 2 for running Linux, you can check if Is there an easy (PowerShell?) way to get more information about WSL? has been answered, or make the following checks

Prerequisites

Upgrading WSL

Activate the Virtual Machine Platform (just the Step 3 instructions) and reboot the computer

After rebooting, go back to the Determining which version of WSL is installed section above, and check that you are now using WSL 2

Potentially useful stuff




[ PMIP3 Wiki Home ] - [ Help! ] - [ Wiki syntax ]