Skip to content

Commit 8b32f74

Browse files
committed
docs: document plain Windows support in wsl2.md
Document the host SSH toolchain now that Lima supports native Windows OpenSSH: which binaries ship by default, why to prefer full Git for Windows over MinGit, and how the Cygwin-vs-native path form is chosen. Signed-off-by: Jan Dubois <jan.dubois@suse.com>
1 parent f7b1c4f commit 8b32f74

1 file changed

Lines changed: 41 additions & 1 deletion

File tree

  • website/content/en/docs/config/vmtype

website/content/en/docs/config/vmtype/wsl2.md

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@ containerd:
4242
- "wsl2" currently doesn't support many of Lima's options. See [this file](https://github.com/lima-vm/lima/blob/master/pkg/wsl2/wsl_driver_windows.go#L19) for the latest supported options.
4343
- When running lima using "wsl2", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
4444
- WSL2 requires a `tar` formatted rootfs archive instead of a VM image. Standard VM disk images (like `.qcow2`, `.raw`, etc.) or `.squashfs` images cannot be natively imported by WSL2.
45-
- Windows doesn't ship with ssh.exe, gzip.exe, etc. which are used by Lima at various points. The easiest way around this is to run `winget install -e --id Git.MinGit` (winget is now built in to Windows as well), and add the resulting `C:\Program Files\Git\usr\bin\` directory to your path.
4645

4746
### Rootfs Image Requirements & Building Custom Images
4847

@@ -76,3 +75,44 @@ If you want to build and use your own custom rootfs, you can build it from a sta
7675
docker build -o type=tar,dest=custom-rootfs.tar .
7776
```
7877

78+
### Windows toolchain
79+
80+
Lima uses an OpenSSH installation on the host. On a default Windows
81+
install that is the native binaries in `C:\Windows\System32\OpenSSH\`:
82+
83+
- **OpenSSH Client** (`ssh.exe`, `scp.exe`, `ssh-keygen.exe`) ships by default
84+
on Windows 10 build 1803 and later, and covers the WSL2 driver.
85+
- **`sftp-server.exe`** is part of OpenSSH Server, an [optional Feature on Demand](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse).
86+
Only the QEMU driver's reverse-sshfs mounts need it. Install via
87+
`Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0` from an
88+
elevated PowerShell, or via Settings → Apps → Optional features.
89+
90+
Installing [Git for Windows](https://gitforwindows.org/)
91+
(`winget install -e --id Git.Git`) remains supported as an alternative
92+
to the native binaries. Use the full Git for Windows installer, not
93+
MinGit — MinGit omits `scp.exe`, `ssh-keygen.exe`, and `cygpath.exe`,
94+
all of which Lima needs.
95+
96+
Lima detects which ssh toolchain is in use on each `limactl start` and
97+
picks both the path form and the matching `sftp-server` binary so both
98+
sides consume the same shape:
99+
100+
- **Cygwin-based ssh** (Git for Windows, MSYS2): paths are converted by
101+
`cygpath` to a POSIX form like `/c/Users/USER`, respecting any custom
102+
MSYS2 fstab the user has configured. `sftp-server` is resolved from
103+
the same toolchain.
104+
- **Native Windows OpenSSH**: paths are returned with forward slashes,
105+
like `C:/Users/USER` — native `ssh`, `ssh-keygen`, and `scp` accept
106+
this form directly. `sftp-server.exe` is picked from the sibling
107+
directory of `ssh.exe`.
108+
109+
When no matching `sftp-server` is found, the hostagent logs a warning at
110+
start and lets `sshocker` auto-detect from `PATH`; a missing
111+
OpenSSH.Server install on a native-only host typically shows up there.
112+
113+
Note: a custom MSYS2 `fstab` that remaps drive prefixes (rare) makes
114+
Cygwin's `/c/...` and native's `C:/...` resolve to different directories
115+
on disk. On such a host, do not swap toolchains between `limactl create`
116+
and `limactl start` on a QEMU instance with a reverse-sshfs mount —
117+
the mount would point at a different directory across the swap. Default
118+
installs without `fstab` overrides are unaffected.

0 commit comments

Comments
 (0)