WSL/doc/docs/technical-documentation/boot-process.md

The WSL2 boot process

This page describes the steps in the WSL2 process, from the user invoking wsl.exe to the user's Linux shell (bash in this example), in the WSL2 distribution.

Overview

The below diagram shows the sequence of event to start bash within a WSL2 distribution. See WSL architecture for details about what each process does.

sequenceDiagram
    wsl.exe->>wslservice.exe: CreateInstance(<distro>)
    wslservice.exe->>wsl.exe: S_OK
    wsl.exe->>wslservice.exe: CreateLxProcess(<distro>, <command line>, <env>, ...)
    create participant mini_init
    wslservice.exe->>mini_init: LxMiniInitMessageEarlyConfig
    create participant gns
    mini_init-->>gns: fork(), exec("/gns")
    wslservice.exe->>gns: LxGnsMessageInterfaceConfiguration
    gns->>wslservice.exe: LxGnsMessageResult
    wslservice.exe->>mini_init: LxMiniInitMessageInitialConfig
    wslservice.exe->>mini_init: LxMiniInitMessageLaunchInit
    create participant init
    mini_init-->>init: fork(), exec("/init")
    init->>wslservice.exe: LxMiniInitMessageCreateInstanceResult
    wslservice.exe->>init: LxInitMessageCreateSession
    create participant session leader
    init-->>session leader: fork()
    session leader->>wslservice.exe: LxInitMessageCreateSessionResponse
    wslservice.exe->>session leader: InitCreateProcessUtilityVm
    create participant relay
    session leader-->>relay: fork()
    relay->>wslservice.exe: LxMessageResultUint32 (hvsocket connect port)
    wslservice.exe->>relay: connect hvsockets for STDIN, STDOUT, STDERR
    create participant bash
    relay-->>bash: fork(), exec("/bin/bash")
    relay<<-->>bash: relay STDIN, STDOUT, STDERR
    wslservice.exe-->>wsl.exe: S_OK + hvsockets for STDIN, STDOUT, STDERR
    wsl.exe<<->>relay: Relay STDIN, STDOUT, STDERR
    destroy bash
    relay-->>bash: waitpid()
    relay->>wsl.exe: LxInitMessageExitStatus (process exit code)

CreateInstance()

When wslservice.exe receives the CreateInstance() call via COM, it will:

1. Identify which distribution the user wants to create. This is done by looking up the DistributionRegistration (see src/windows/service/exe/DistributionRegistration.cpp) in the Windows registry, matching either on the distribution ID, or using the default if none is provided.

2. Based on the type of distribution (WSL1 or WSL2), either create a WSL1 instance, or start up a WSL2 virtual machine.

3. Associate the newly creating distribution to the calling process (see src/windows/service/exe/Lifetime.cpp)

Starting the WSL2 virtual machine

To start a WSL2 distribution, wslservice.exe needs a virtual machine. If the virtual machine isn't already running, it will be created as part of the CreateInstance() call.

The WSL2 virtual machine is created via the Host Compute System (HCS) service (see src/windows/service/exe/WslCoreVm.cpp).

To create a new virtual machine, wslservice.exe generates a JSON string, which describes the virtual machine configuration. This JSON is then passed to HcsCreateComputeSystem() to create a new virtual machine.

See src/windows/common/hcs_schema.h for more details on the HCS JSON schema.

Part of the JSON configuration includes:

• The kernel: WSL will use its built-in kernel, usually installed C:/Program Files/WSL/tools/kernel, or a custom kernel if overridden via .wslconfig
• The initramfs: WSL uses its own initramfs (usually installed in C:\Program Files\WSL\tools\initrd.img). It's an image that only contains the mini_init binary
• The resources accessible to the virtual machine such as CPU, RAM, GPU, etc

When started, the virtual machine will boot into the provided kernel, and then execute mini_init.

The Linux boot process

mini_init is the process that performs usermode initialization inside the virtual machine. After performing various configurations, mini_init receives a LxMiniInitMessageEarlyConfig message from the wslservice.exe which contains the following information:

• Identifiers for the system VHD, swap VHD and kernel modules VHD if any
• The machine's hostname
• The configured memory reclaim mode and page reporting order

mini_init then creates the gns process, which is responsible for networking configuration and then receives a LxMiniInitMessageInitialConfig message, which contains:

• An entropy buffer, to seed the virtual machine's entropy
• Information about the GPU drivers shares to mount, if any
• Wether wslg is enabled

After applying all the configuration requested by wslservice.exe, the virtual machine is ready to start Linux distributions.

Starting a Linux distribution

To start a new distribution, wslservice.exe sends a LxMiniInitMessageLaunchInit message to mini_init, which then mounts the distribution vhd and starts init. See (init for more details on WSL2 distributions configuration)

Once running, wslservice.exe can then send a LxInitMessageCreateSession message to start a new session leader inside that distribution, which can be used to launch linux processes

Relaying the linux process's input and output to Windows

Once the user's linux process has been created, wslservice.exe can return from CreateLxProcess() back to wsl.exe. In the case of WSL2, wsl.exe receives the following HANDLES:

• STDIN
• STDOUT
• STDERR
• Control channel
• Interop channel

The STDIN, STDOUT and STDERR handles are used to relay input and output from the Linux process to the Windows terminal. Depending on the type of handle (terminal, pipe, file, ...), wsl.exe will apply different relaying logics (see src/windows/common/relay.cpp) to achieve the best compatibility between Windows & Linux.

The Control channel is used to notify the linux process of a change in the terminal (for instance when wsl.exe's terminal window is resized) so these changes can be applied to the Linux process as well.

The Interop channel has two usages:

• Create Windows processes from Linux (see interop)
• Notify wsl.exe when the Linux process has exited (see LxInitMessageExitStatus)

Once the Linux process has exited, wsl.exe flushes all remaining IO, and exits with the same exit code as the Linux process.

If wsl.exe is terminated before the Linux process exits, wslhost.exe will take over the Interop channel and continue to handle requests to execute Windows processes.