Installing the Windows Subsystem for Linux (WSL)

The Windows Subsystem for Linux allows you to run a Linux session from within your Windows environment. You can then connect to other machines (like Cannon) from this Linux session.

Prerequisites

• Windows 11 (or later)
• Windows 10 version 2004 (build #19041) and later

Installation instructions

1. Open Windows Powershell:

   • Click on the Windows menu (or hit the Windows key)
   • Type Powershell in the search bar
   • Click on Run as administrator

   On some versions of Windows 11, you may see a Terminal (Admin) option when you right click on the Start button. This will also launch a PowerShell in administrator mode.

2. Install WSL with Ubuntu Linux.

   • NOTE: your-windows-username in the PowerShell prompt will be replaced by your Windows login name.

   PS C:\Users\your-windows-username> wsl --install -d ubuntu

   Upon successful completion, you will see these messages:

   Installing: Virtual Machine Platform
   Virtual Machine Platform has been installed.
   Installing: Windows Subsystem for Linux
   Windows Subsystem for Linux has been installed.
   Installing: Ubuntu
   Ubuntu has been installed.
   The requested operation is successful. Changes will not be effective until the system is rebooted.
   

3. Make sure you are running WSL version 2:

   PS C:\Users\your-windows-username> wsl --set-default-version 2

   Upon successful completion, you will see these messages:

   For information on key differences with WSL 2 please visit https://aka.ms/wsl2
   The operation completed successfully.
   

4. Apply all recent updates to WSL:

   PS C:\Users\your-windows-username> wsl --update

   If there are no updates, you will see this message:

   The most recent version of Windows Subsystem for Linux is already installed.
   

5. Reboot your system so that the changes will take effect. When you log back in, you may see an Ubuntu window pop up with the message:

   Ubuntu is already installed.
   Launching Ubuntu...
   Installing, this may take a few minutes.
   

   Let Ubuntu finish initializing before proceeding.

6. Open a Windows PowerShell window (Run as administrator) as in step 1.

7. Activate WSL. You will be prompted to answer some questions (i.e. specify your Linux username and password.

   PS C:\Users\you> wsl
   your-linux-username@localhost~#

   • NOTE: You should notice that the prompt will change from the PowerShell prompt to the Linux prompt.
   • NOTE: your-linux-username will be replaced by what you specified for your Linux username. See the [WSL best practices guide]

8. Now that you are in a local Ubuntu Linux session, you will want to install some software. You will do this with the apt package manager. Type the following commands at the Linux prompt.

   • NOTE: For clarity, we have omitted the Linux prompts below.
   • NOTE: Comments beginning with # after each command are listed, but you don't have to type these.

    sudo apt update -y && sudo apt upgrade -y     # Get the latest packages from Ubuntu
    sudo apt install -y git-gui                   # Git GUI (NOTE: Git is installed by default)
    sudo apt install -y gitk                      # GitK browser
    sudo apt install -y xserver-xorg              # X11 server
    sudo apt install -y xserver-xorg-core         # X11 server core files
    sudo apt install -y x11-apps                  # Basic X11 applications (e.g. xeyes)
    sudo apt install -y xfonts-base               # Fonts for X11
    sudo apt install -y xfonts-75dpi              # Fonts for X11
    sudo apt install -y xfonts-100dpi             # Fonts for X11
    sudo apt install -y xorg-x11-fonts            # Fonts for X11
    sudo apt install -y fonts-dejavu              # DejaVu fonts (used by several apps)
    sudo apt install -y gnu-emacs                 # Emacs editor (useful for editing configuration files)

7. Try opening the xeyes program to test if the X11 server is working. If successful, you will see a pair of eyes on the screen. (Don't laugh, this is the standard tool used to test if X11 forwarding is happening.)

   xeyes

8. Copy your private keys to the ~/.ssh folder.

9. Shutdown WSL so that all of the settings can be saved. This will return you to the PowerShell prompt.

wsl --shutdown

Additional setup steps

1. Define the LANG environment variable in your C:\Linux\Ubuntu\home\YOUR-LINUX-USERNAME\.bash_profile system startup file. For example, if you are in the US, you would use:

    # Also set the language to be persistent
    export LANG=en_US

See https://www.tecmint.com/set-system-locales-in-linux/ for more examples.

2. Tell Windows that it should do the graphical rendering locally. Otherwise the rendering will be done on the remote machine, which will incur a noticeable latency. Add these lines to your .bash_profile file:

    # Tell X11 programs to render on Windows, not linux, side
    # (cf https://docs.mesa3d.org/envvars.html)
    export LIBGL_ALWAYS_INDIRECT=1

3. Add an exception to your antivirus software for WSL. Otherwise, your antivirus software will attempt to continually scan data packets flowing into and out of your Linux session, which can cause heavy latency. See this post for more information.

Connection instructions

1. If WSL is not running then open a Windows PowerShell (see above) and type:

PS C:\Users\you> wsl

2. To log in to Cannon, type:

ssh your-Cannon-username@login.rc.fas.harvard.edu

3. Once you have logged into Cannon you can load your software modules as you normally would.