==================================

 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