==================================
 WSL, Windows subsystem for Linux
==================================
.. contents::
   :local:

Documentation
=============

https://docs.microsoft.com/en-us/windows/wsl/
  Windows Subsystem for Linux Documentation.
https://github.com/sirredbeard/Awesome-WSL
  Awesome list dedicated to Windows Subsystem for Linux.
https://devblogs.microsoft.com/commandline/automatically-configuring-wsl/
  Automatically Configuring WSL.
https://docs.microsoft.com/en-us/windows/wsl/troubleshooting
  Troubleshooting Windows Subsystem for Linux.

https://github.com/sirredbeard/Awesome-WSL
  Awesome list dedicated to Windows Subsystem for Linux.

wsl utility
===========

Run Linux command from default distro::

  wsl ls
  wsl -e /bin/ls
  wsl --exec /bin/bash

Run Linux command from specific distro::

  wsl -d ubuntu ls
  wsl -d debian -e /bin/ls
  wsl -d debian --exec /bin/bash
  wsl -distribution debian --exec /bin/bash

Run Linux command from specific user::

  wsl -u user ls
  wsl --user root ls

Combining user & distro::

  wsl -u root -d alpine -- ls
  wsl -u root -e sh -c "service apache status || service apache start"

https://docs.microsoft.com/en-us/windows/wsl/wsl-config
  Ways to run WSL.

.. note:: Earlier ``wsl`` utility was limited and some job performed by ``wslconfig`` utility:

   * List distros::

       wslconfig /l
       wslconfig /list

   * Set default distro::

       wslconfig /s debian
       wslconfig /setdefault debian

   * Terminate any running parts of distro::

       wslconfig /t debian
       wslconfig /terminate debian

Installing WSL distor second time
=================================

Microsoft provides certain Linux distros out of the box::

  wsl --list --online
  NAME            FRIENDLY NAME
  Ubuntu          Ubuntu
  Debian          Debian GNU/Linux
  kali-linux      Kali Linux Rolling
  openSUSE-42     openSUSE Leap 42
  SLES-12         SUSE Linux Enterprise Server v12
  Ubuntu-16.04    Ubuntu 16.04 LTS
  Ubuntu-18.04    Ubuntu 18.04 LTS
  Ubuntu-20.04    Ubuntu 20.04 LTS

After the installation you will have an executable ``NAME.exe`` for convenient entering into
distro, compare::

  $ wsl -d NAME CMD
  $ NAME.exe CMD

You install such distros via::

  wsl --install NAME

What if you want 2 Debian distros? Unfortunately you have to deal with rootfs:

* either export existing WSL distro::

    wsl --export Alpine alpine.tar
    wsl --import alpine-copy 'c:\srv\wsl\alpine-copy' alpine.tar

* or use LXC / OCI rootfs (like one from https://alpinelinux.org/downloads/ or
  http://cdimage.ubuntu.com/ubuntu-base/releases/)::

    wget https://dl-cdn.alpinelinux.org/alpine/v3.16/releases/x86_64/alpine-minirootfs-3.16.0-x86_64.tar.gz
    wsl --import alpine-x 'c:\srv\wsl\alpine-x' alpine-minirootfs-3.16.0-x86_64.tar.gz

I'd suggest to use Ubuntu "base" images instead (less bloated than "cloud" images):

* http://cdimage.ubuntu.com/ubuntu-base/releases - base images
* https://cloud-images.ubuntu.com/releases/ - cloud images

You download rootfs and import it::

  wget http://cdimage.ubuntu.com/ubuntu-base/releases/22.04/release/ubuntu-base-22.04-base-amd64.tar.gz
  wsl --import my-ubuntu c:\wsl\my-ubuntu ubuntu-base-22.04-base-amd64.tar.gz --version 2

Mounting Windows file systems
=============================

From January 2018 WSL 1 allows to mount external NTFS file systems as ``drvfs``. ``metadata`` option
allows ``chmod`` operation on NTFS volumes, metadata will be shared across all WSL distros though.

https://devblogs.microsoft.com/commandline/chmod-chown-wsl-improvements/
  Chmod/Chown WSL Improvements.

To preserve customization between WSL reloads update ``/etc/wsl.conf`` with something like::

  [automount]
  enabled = true
  mountFsTab = false
  options = "metadata,noatime,uid=1000,gid=1000,umask=022,fmask=077"

Equivalent CLI call is::

  sudo mount -t drvfs 'C:\' /mnt/c -o metadata,noatime,uid=1000,gid=1000,umask=022,fmask=077

https://devblogs.microsoft.com/commandline/automatically-configuring-wsl/
  Automatically Configuring WSL.

To mount attached USB stick::

  sudo mkdir /mnt/f
  sudo mount -t drvfs f: /mnt/f

https://docs.microsoft.com/en-us/windows/wsl/wsl-config
  ``/etc/wsl.conf`` configuration options.

Switching WSL version
=====================

Set default version for new containers::

  wsl --set-default-version 1

Convert a specific distro to WSL 1 or 2::

  wsl --set-version Debian 1
  wsl --set-version Alpne 2

Debugging WSL
=============

https://github.com/Microsoft/WSL/blob/master/CONTRIBUTING.md
https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/wsl.wprp
https://github.com/Microsoft/WSL/blob/master/diagnostics/collect-wsl-logs.ps1

https://msrc-blog.microsoft.com/2018/12/10/first-steps-in-hyper-v-research/
https://msrc-blog.microsoft.com/2019/09/11/attacking-the-vm-worker-process/

Custom WSL 2 Linux kernel
=========================

Register kernel in ``/etc/wsl.conf``::

  [wsl2]
  kernel=C:\\Users\\<USER>\\vmlinux