komorebi/docs/linux/dev/wsl2-probe.md

# Probing a NixOS-WSL2 machine

A Plasma guest that runs komorebi can be started on a Windows machine from a
NixOS virtual machine in WSL2: QEMU with KVM boots the guest, and its window is
shown through WSLg. Whether a given machine can do that depends on five things
that nothing but that machine can answer: whether WSL2 passes KVM through,
whether WSLg opens a QEMU window, whether the Windows GPU reaches OpenGL in
WSL, whether Windows can reach a port that the guest listens on, and whether the
guest can mount the host's `/nix/store` by virtiofs. The probe answers them in
about two minutes, and prints what to change for each answer that is not a yes.

It changes nothing on the machine. It reads files and system settings, boots a
tiny guest under QEMU that powers itself off, opens two windows for a few
seconds each, starts `virtiofsd` for a few seconds, and listens on two local
ports until it ends.

## Running it

From a checkout of this repository, in the NixOS-WSL2 shell, with flakes
enabled:

```sh
nix run .#wsl2-probe
```

`just wsl2-probe` runs the same command, and arguments for the script go after
it (`just wsl2-probe --hold 15`). Nix brings QEMU, `virtiofsd`, Mesa's
`eglinfo` and `glxinfo`, `socat` and the guest, about 1.6 GiB in the Nix store
as of 2026-10-28, most of it QEMU's and Mesa's dependencies. The guest is a
kernel and a static busybox from the binary cache, and the two kernel modules
that virtiofs needs, so nothing is compiled; building the module closure also
downloads the kernel's module tree (about 150 MB), which the probe does not keep.

While it runs, look at the Windows desktop: a QEMU window opens twice for 8
seconds (P2, then P3), and after each the script asks whether it appeared. The
answer is one of the things the script cannot find out itself.

| Option | Effect |
|---|---|
| `--only P1,P3` | runs only those probes (P0 always runs: the others read what it found) |
| `--hold SECONDS` | how long a window stays open (default 8) |
| `--yes` | answers yes to "did a window appear?" without asking |
| `--no-prompt` | asks nothing; this is also the case when stdin is not a terminal |
| `--dry-run` | runs P0 and P5, which only read, and prints what the others would start |
| `--report FILE` | where to write the report (default `wsl2-probe-report.txt` in the current directory) |

The exit status is 0 when the probes ran, whatever they found, and 2 for a
mistake in the options.

## Reading the output

Every line that carries a result starts with one of these:

| Tag | Meaning |
|---|---|
| `[PASS]` | the check passed |
| `[WARN]` | it works, but not as it should, or the check cannot say |
| `[FAIL]` | the thing the real guest needs is missing |
| `[SKIP]` | the check did not run, and the line says why |
| `[INFO]` | a value that was read or measured; the summary repeats it |

A `WARN` or a `FAIL` is followed by a `fix:` block with the exact change: the
lines for `%USERPROFILE%\.wslconfig`, an option of the NixOS configuration, or a
command for PowerShell. The checks have numbers (`P1.2`), and the fix of a
check often names another (`see P1.1`).

The output ends with a block between two lines of equals signs, headed
`PASTE THIS`: one verdict per probe, one line per check, and every fact the
probes read or measured. That block is what to send back. The whole output is in
`wsl2-probe-report.txt`, without colors.

## The probes

### P0: the environment

| Check | What it looks at | Verdict |
|---|---|---|
| P0.1 | `WSL_DISTRO_NAME`, `/run/WSL` and `/proc/version` | `PASS` on WSL2; `WARN` on WSL1 or when this is not WSL at all, where the probes can only report what they find |
| P0.2 | `nix config show experimental-features` | `PASS` when flakes are on; `WARN` with the NixOS option when not |
| P0.3 | `trusted-users` against the user and its groups | `PASS` when the user is trusted; `WARN` with the NixOS option when not |

The facts are the kernel, PID 1, `/etc/os-release` and `nixos-version`, the
`nixos-wsl` input of `/etc/nixos/flake.lock` if there is one, memory, the number
of processors, the free disk in `/nix`, the home directory, the directory the
real guest would keep its state in, the current directory and `/mnt/c`, the CPU
vendor, model and virtualization flag, the Nix version and substituters, and,
through interop, the Windows build, `wsl.exe --version` and the `.wslconfig` of
the Windows user. When interop is off, the Windows facts are missing and P4.1
says how to turn it on.

### P1: KVM

| Check | What it looks at | Verdict |
|---|---|---|
| P1.1 | the `svm` (AMD) or `vmx` (Intel) flag of `/proc/cpuinfo` | `FAIL` with the `.wslconfig` lines for nested virtualization when neither is there; `INFO` on a CPU that has neither flag by design |
| P1.2 | `/dev/kvm` exists and the user can open it read-write | `FAIL` when it is missing (nested virtualization) or closed to the user (the `kvm` group, with the exact `extraGroups` line) |
| P1.3 | a guest booted under `-accel kvm -cpu host` and the loop it ran | `PASS` with the loop time and the time of the whole boot; `FAIL` with QEMU's error and a fix chosen from it |
| P1.4 | the same guest under `-accel tcg`, software emulation | `PASS` with the times; `FAIL` means QEMU does not work here at all |
| P1.5 | TCG's loop time divided by KVM's | `PASS` at 3 or more, `WARN` from 1.5, `FAIL` below |

The facts are the nested-virtualization setting of `kvm_amd` or `kvm_intel`, the
QEMU version, the guest's CPU model, memory and flags (whether it sees `svm` or
`vmx` itself, and `hypervisor`, `avx`, `avx2`, `aes`), and the loop timed on the
machine itself with the same busybox.

The loop is 600000 iterations of an `ash` counting loop, timed from
`/proc/uptime` (a resolution of 10 ms, so the loop has to take about a second).
KVM runs the guest's instructions on the CPU, so its time is about that of the
machine itself; TCG translates them, and is several times slower. On a Xeon
6975P with KVM, at time of writing (2026-10-28), the loop took 970 ms on the
machine, 980 ms in a KVM guest and 11370 ms under TCG, 11.6 times as long. A
ratio under 3 means the acceleration is partial or absent, and the figure to
paste is `kvm_vs_tcg`.

### P2: display

| Check | What it looks at | Verdict |
|---|---|---|
| P2.1 | `WAYLAND_DISPLAY`, `DISPLAY`, `XDG_RUNTIME_DIR`, `/mnt/wslg` and the sockets in them | `PASS` when the shell can reach a display; `WARN` when only WSLg's defaults (`/mnt/wslg/runtime-dir/wayland-0`, `:0`) can, which the probe then uses for its windows; `FAIL` on WSL with none (`WARN` elsewhere) |
| P2.2 | `-display gtk -device virtio-vga` for `--hold` seconds, with the guest printing a line a second | `PASS` when QEMU started, the guest ran to its end with the window up, and QEMU exited 0; `FAIL` with QEMU's error otherwise. When the window system the toolkit picked fails and both are available, each is tried by name (`GDK_BACKEND`) |
| P2.3 | your answer to "did a window appear?" | `PASS` for yes; `FAIL` for no; `INFO` when it was not asked (`--no-prompt`, no terminal) or `--yes` answered it |

A line says when the framebuffer's frame rate was not measured: the guest is a
text console, so there is no moving picture to count frames of.

### P3: GPU

| Check | What it looks at | Verdict |
|---|---|---|
| P3.1 | `/dev/dxg`, the device through which WSL2 passes the Windows GPU | `FAIL` on WSL when it is missing: the Windows driver needs WSL support |
| P3.2 | `libd3d12.so`, `libd3d12core.so` and `libdxcore.so` in `/usr/lib/wsl/lib`, where WSL mounts the Windows driver's libraries | `WARN` when they are missing |
| P3.3 | the same libraries linked into `/run/opengl-driver/lib`, which is what `wsl.useWindowsDriver = true` does on NixOS-WSL | `WARN` with the options when they are not |
| P3.4 | the OpenGL renderer that `eglinfo -B` and `glxinfo -B` report on the machine, in four environments: as it is, with `LD_LIBRARY_PATH=/usr/lib/wsl/lib`, with `GALLIUM_DRIVER=d3d12`, and with both | `PASS` when one of them reports a hardware renderer (`d3d12` or other), naming the environment that does; `WARN` when all report `llvmpipe` or none works |
| P3.5 | `qemu -device help` and `-display help` list `virtio-vga-gl` (`virtio-gpu-gl-pci` on aarch64) and `gtk` | `FAIL` when not: the QEMU of nixpkgs lacks it |
| P3.6 | `-display gtk,gl=on -device virtio-vga-gl` for `--hold` seconds | the same as P2.2, with the environment of P3.4's variant tried when the default one fails; QEMU's refusal is printed |
| P3.7 | your answer to "did the VirGL window appear too?" | as P2.3 |

The facts include the contents of `/usr/lib/wsl/lib` and `/usr/lib/wsl/drivers`,
the Windows GPU name and driver version from `Win32_VideoController`, and each
renderer line per variant (`host_gl[default]`, `host_gl[d3d12]`, ...), which names
the renderer that each platform of `eglinfo` (X11, Wayland, GBM, surfaceless)
reports. A renderer string that names `d3d12` is Mesa's Direct3D 12 driver,
which draws on the Windows GPU; `llvmpipe` is Mesa's software rasterizer.

What happens inside the guest is not checked: the guest of this probe has no
graphics stack, so the renderer that a Plasma session in it gets (VirGL on the
host's renderer, or `llvmpipe`) is for the real guest to report.

### P4: the Windows side

| Check | What it looks at | Verdict |
|---|---|---|
| P4.1 | `cmd.exe /c ver` through interop | `FAIL` with the NixOS-WSL interop options when Windows programs do not run from WSL |
| P4.2 | `mstsc.exe`, Windows' RDP client, on `PATH` or in `System32` | `PASS` when found; `WARN` with the `includePath` option when not |
| P4.3 | two `socat` listeners on free ports above 20000, one on `127.0.0.1` and one on `0.0.0.0`, and a TCP connection to each from `powershell.exe`, as `127.0.0.1` and as `localhost` | `PASS` when Windows reaches the loopback listener both ways; `WARN` when only `127.0.0.1` works, or only the `0.0.0.0` listener is reachable; `FAIL` when nothing is, with the `.wslconfig` lines for `localhostForwarding` and `networkingMode` |

The facts are the path of `cmdkey.exe` (which a later step would use to hand
Windows the RDP credentials), the networking mode (`wslinfo --networking-mode`,
or `networkingMode` of `.wslconfig`: NAT by default, or mirrored), the
`localhostForwarding` setting, the WSL machine's addresses, and the four
connection results.

Outside WSL, P4 says so and checks nothing.

### P5: resources

The real guest wants 8 GiB of memory, 4 or more cores, and about 25 GiB of disk,
plus the space the Nix build takes.

| Check | What it looks at | Verdict |
|---|---|---|
| P5.1 | `MemTotal` of the WSL machine | `PASS` from 10 GiB (8 for the guest, 2 for WSL and Nix next to it); `WARN` from 6 GiB, where the guest would run with `--memory 6144`; `FAIL` below, each with the `memory=` and `swap=` lines for `.wslconfig` |
| P5.2 | `nproc` | `PASS` from 4; `WARN` below, with the `processors=` line |
| P5.3 | the free space under `/nix`, or on the Windows drive under the virtual disk when that is less | `PASS` from 40 GiB (25 for the closure and the guest's disk, 10 for the build); `WARN` from 25; `FAIL` below |

On WSL the virtual disk looks like a terabyte; what limits it is the Windows
drive it lives on, so the probe reads `/mnt/c` as well and takes the smaller of
the two.

### P6: virtiofs

The real guest does not copy the host's `/nix/store`: it mounts it. On a Linux
host nixpkgs' QEMU runner starts one `virtiofsd` per shared directory (the
store, the repository, the directory of the credentials), and QEMU joins the
guest's virtio-fs device to each daemon's socket, with the guest's memory in a
shared `memfd`. This probe builds the same chain, with the same options as the
runner, for the host's `/nix/store` (read-only) and a temporary directory
(writable), and a guest whose kernel is the one the real guest boots.

| Check | What it looks at | Verdict |
|---|---|---|
| P6.1 | `/dev/fuse` exists and the user can open it read-write | `PASS`; `WARN` with the NixOS lines when it is missing or closed: `virtiofsd` does not open it (see below), so the guest can still start |
| P6.2 | `virtiofsd` (the one of nixpkgs, as the runner uses) starts as the user, with `--sandbox=none --seccomp=none --translate-uid ...`, and makes its socket, for `/nix/store` read-only and a temporary directory writable | `FAIL` with the daemon's output when a socket does not appear; `SKIP` when the program is not there |
| P6.3 | QEMU boots the guest with `-object memory-backend-memfd,share=on`, `-machine memory-backend=` and two `vhost-user-fs-pci` devices, under KVM when `/dev/kvm` opens and under TCG otherwise | `FAIL` with QEMU's error, or when the guest does not run to its end |
| P6.4 | the guest loads `virtio_pci` and `virtiofs`, mounts `/nix/store` read-only, and its checksum of the busybox it came with equals the host's; a write is refused | `FAIL` with the guest's error and, when the module did not load, that; `WARN` when the share could be written |
| P6.5 | the guest mounts the writable directory, reads a random token the host wrote, and writes a file that the host reads | `FAIL` when any of the three does not work |

The facts are the path and version of `virtiofsd`, the warnings it printed, how
each module loaded in the guest (`built in` for a kernel that has the transport
in its image), the file systems the guest lists, what the guest saw (the
checksum, the owner and mode of the host user's file, of the file it wrote) and
the owner of the file it wrote as the host sees it.

What is known of `virtiofsd` before WSL2 (read at time of writing, 2026-10-28,
from `virtiofsd` 1.14.0 and nixpkgs' runner on Linux machines that are not WSL2):

- it runs as an ordinary user with the runner's options, and prints two
  warnings, that it could not raise the limit of open files above the hard limit,
  and that it cannot use file handles for the root node (`Operation not
  permitted`) and falls back to `O_PATH` descriptors; both are harmless;
- it never opens `/dev/fuse`: a `strace` of its start shows no such open. It
  speaks FUSE to the guest's kernel through the vhost-user socket, so the
  daemon needs the socket, a shared `memfd` in QEMU, and the directory;
- a file that the host user owns appears in the guest owned by the same numeric
  uid and gid (`--translate-uid host:65534:0:1` maps only the host's 65534),
  which is why the guest user of the demo cannot read a directory of a host
  user whose uid is not 1000 when its mode is 0700;
- the kernel configuration of WSL2 (`linux-msft-wsl-6.6.y`, `config-wsl` for
  `x86_64`, read from its repository, not measured on a machine) has
  `CONFIG_FUSE_FS=y`, `CONFIG_MEMFD_CREATE=y`, `CONFIG_USER_NS=y`,
  `CONFIG_UNIX=y`, `CONFIG_DEVTMPFS=y` and `CONFIG_KVM_AMD=m`: nothing the
  chain needs is missing from it. `/dev/fuse` is a device node that the kernel's
  devtmpfs makes closed to ordinary users, and udev's default rules open it, so
  where udev's rules do not apply it can be closed, which `virtiofsd` does not
  mind.

On WSL2 itself the chain is not measured at time of writing: the paste of the
first run is the first fact.

## The NixOS-WSL option names

The fixes name these options of NixOS-WSL: `wsl.useWindowsDriver`,
`wsl.interop.includePath`, `wsl.interop.register` and `wsl.wslConf.interop.enabled`,
and of NixOS itself `users.users.<name>.extraGroups`, `nix.settings.trusted-users`
and `nix.settings.experimental-features`. NixOS-WSL renames options now and then;
when `nixos-rebuild` rejects one, its options page has the current name.

## How the script is checked

The script is `scripts/linux/wsl2-probe.sh` and the flake wraps it
([`nix/linux/dev/wsl2-probe.nix`](../../../nix/linux/dev/wsl2-probe.nix)): `packages.<system>.wsl2-probe`
and the app of the same name, and `wsl2-probe-guest`, the kernel and the initrd
(with the modules of virtio's PCI transport and of virtiofs).
The initrd's init and the loop are `nix/linux/dev/wsl2-probe-init.sh` and
`nix/linux/dev/wsl2-probe-loop.sh`; the same loop file is what the script times on the
machine.

Two checks of the flake keep the script from rotting between the times someone
runs it. `wsl2-probe` builds the wrapper, which runs ShellCheck over the script
and over the guest's init, so neither can have a warning. `wsl2-probe-dry-run`
runs `wsl2-probe --dry-run` in the build sandbox, which has no KVM, no network
and no display, and expects a line for every probe, the paste block, and a
refusal of an unknown option. `just lint` runs ShellCheck on the script as well.

The script was exercised, at time of writing (2026-10-28), on machines that
are not WSL2:

- an `x86_64` NixOS machine with KVM: P1 passes with the ratio above; P2 passes
  under `xvfb-run` and reports "no display" without one; P3 reports the missing
  OpenGL driver and QEMU's refusal of `gl=on`;
- an `aarch64` NixOS machine without KVM: P1 reports the missing `/dev/kvm` and
  boots the guest under TCG alone;
- the `x86_64` machine again with stand-ins for Windows' `cmd.exe`,
  `powershell.exe` (PowerShell 7, running the script's PowerShell), `wsl.exe`
  and `wslpath` on `PATH` and `WSL_DISTRO_NAME` set, for the paths that need
  interop, and with `/dev/kvm`, `/proc/cpuinfo` and `/proc/meminfo` replaced
  inside a user namespace for the failing and short-of-resources verdicts;
- P6 on the `x86_64` machine with KVM (the whole chain passes; the guest boots
  in 1.2 s), on the `aarch64` machine under TCG (passes; 3.7 s), under TCG on
  the `x86_64` machine with `/dev/kvm` closed in a user namespace (passes;
  4 s), with `/dev/fuse` closed in a user namespace (`WARN`, and the rest
  passes), with `virtiofsd` off `PATH` (`SKIP`), with a `virtiofsd` that exits
  (`FAIL` with its output), and with a stand-in for QEMU that refuses the shared
  memory, or prints what a guest would after each way the mounts can fail (the
  verdicts of P6.3 to P6.5 for each).

Nothing in the script has run on WSL2 itself at time of writing, so the paste of
its first run there is the first measurement of any of this on WSL2.