==================================
 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.

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

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 v1::

  wsl --set-version Debian 1

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

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

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

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