docs: document the Windows host SSH toolchain by jandubois · Pull Request #5341 · lima-vm/lima

jandubois · 2026-07-26T23:17:35Z

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. Also replaces the Known Issues bullet that claimed Windows ships no ssh.exe, since only xz, bzip2, and zstd rootfs archives still need an external binary.

This describes the state after #5299 and #5300 land, so it should merge after them. Merging it first would publish toolchain behaviour that master does not yet have.

paths-ignore in test.yml keeps the test workflow off this PR, but lint-quick.yml has no such filter and does run.

jandubois · 2026-07-28T05:00:09Z

AI review: https://jandubois.github.io/lima/20260727-195856-pr-5341.html

It claims it still has important issues, but they are kind of silly now; I think it is ready to merge.

AkihiroSuda · 2026-07-29T07:54:31Z

 - v6.2.0 or later (Linux)

+On a Windows host, "qemu" needs an OpenSSH installation for its own `ssh`,
+`scp`, and `ssh-keygen`. Mounts there must be reverse-sshfs, because QEMU


Do we have a functional support for reverse-sshfs?
Needs some Dokan (FUSE) to be manually set up?

It works, but for Ubuntu we need to add the AppArmor rule for the home directory format. I noticed reverse-sshfs doesn't even work on macOS anymore with Ubuntu because /Users/jan does not match any rule.

I'll create a PR for this tomorrow.

I've created #5375 to fix the AppArmor rules to allow access to all mounted directories. I have tested it locally on macOS, but am waiting for the QEMU on Windows integration test to see if it works on Windows too.

Note that we don't have any integration test to make sure reverse-sshfs keeps working on macOS with Ubuntu. It was broken for a long time, and nobody noticed, so maybe nobody cares.

waiting for the QEMU on Windows integration test to see if it works on Windows too

The AppAmor change does work, but now reverse-sshfs on Windows is still broken for yet another reason. Will try to figure it out.

The fix belongs into #5300. So #5375 will belong in the whole series any time after 5300. Will recreate the integration branch with these changes to prove (hopefully) that it all works.

AkihiroSuda · 2026-07-29T07:54:57Z

   docker build -o type=tar,dest=custom-rootfs.tar .
   ```

+### Windows toolchain


Ok, will cut it down.

I've shorted the doc; let me know if you think it is still too long.

Still "TLDR".
What are the required steps, for typical users?

Lima now supports native Windows OpenSSH alongside the Cygwin-based toolchains, and the two differ in which binaries they ship, which path form they produce, and where their sftp-server lives. Document what to install, how Lima picks between them, and what changes for reverse-sshfs mounts. Also replace the Known Issues bullet that claimed Windows ships no ssh.exe. Lima unpacks a .tar.gz rootfs itself, so only xz, bzip2, and zstd archives still need an external binary. These pages describe the state after the copytool and reverse-sshfs support lands, so this should merge after those. Signed-off-by: Jan Dubois <jan.dubois@suse.com>

AkihiroSuda · 2026-08-01T18:17:15Z

+Windows 10 and 11 ship an OpenSSH client in `C:\Windows\System32\OpenSSH\`, and
+that's all the WSL2 driver needs.
+
+The QEMU driver's reverse-sshfs mounts also want `sftp-server.exe`, which


QEMU seems off-topic in wsl2.md

AkihiroSuda · 2026-08-01T18:18:26Z

 - v8.2.1 or later (macOS)
 - v6.2.0 or later (Linux)

+On a Windows host, "qemu" needs an OpenSSH installation for its own `ssh`,


Suggested change

On a Windows host, "qemu" needs an OpenSSH installation for its own `ssh`,

On a Windows host, "qemu" needs an [OpenSSH installation](URL GOES HERE) for its own `ssh`,

AkihiroSuda · 2026-08-01T18:18:45Z


+### Windows toolchain
+
+Windows 10 and 11 ship an OpenSSH client in `C:\Windows\System32\OpenSSH\`, and


Windows 10 has reached EOL

AkihiroSuda · 2026-08-01T18:20:45Z


 Prerequisite:
 - QEMU (Required, only if [QEMU]({{< ref "/docs/config/vmtype#qemu" >}}) driver is used)
+- An OpenSSH client on Windows hosts (Windows 10 and 11 ship one); see


Windows 10 has reached EOL

AkihiroSuda · 2026-08-01T18:21:22Z

+belongs to OpenSSH Server, an [optional Feature on Demand](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse).
+Install it from an elevated PowerShell with
+`Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0`. Without it
+`sshocker` serves the mount in-process, so the mount still works. But pinning


What is the problem of using in-process SFTP server?

AkihiroSuda · 2026-08-01T18:23:09Z

+`sftpDriver: openssh-sftp-server` under a mount's [`sshfs`]({{< ref "/docs/config/mount#reverse-sshfs" >}})
+drops that fallback, and then the mount fails.
+
+[Git for Windows](https://gitforwindows.org/) (`winget install -e --id Git.Git`)


Any reason to install it?

AkihiroSuda · 2026-08-01T18:23:58Z

+`System32\OpenSSH`. Lima then takes the `sftp-server` from that toolchain, and
+writes the key and socket paths it hands `ssh` in the form that toolchain
+expects. MSYS2 and Git for Windows get `cygpath`'s `/c/Users/USER`, stock
+Cygwin `/cygdrive/c/Users/USER`, and the native client `C:/Users/USER`.


These details could be moved to https://lima-vm.io/docs/dev/internals/

AkihiroSuda · 2026-08-01T18:24:02Z

+
+A mount without an explicit `mountPoint` derives its guest path from `cygpath`
+on every load, so adding stock Cygwin to `PATH` can move an existing instance's
+mount inside the guest. Set `mountPoint` to pin it.


These details could be moved to https://lima-vm.io/docs/dev/internals/

AkihiroSuda

Thanks, but I still think we should prioritize readability over amount of the documentation.

Details can be still documented in <details> or in https://lima-vm.io/docs/dev/internals/

jandubois force-pushed the docs-plain-windows-wsl2 branch from 8b32f74 to 2c07ada Compare July 26, 2026 23:31

This was referenced Jul 27, 2026

copytool: support native Windows OpenSSH #5299

Open

CI: factor Windows setup into composite actions; add plain-Windows jobs #5342

Open

jandubois changed the title ~~docs: document plain Windows support in wsl2.md~~ docs: document the Windows host SSH toolchain Jul 28, 2026

jandubois force-pushed the docs-plain-windows-wsl2 branch 2 times, most recently from f452a60 to df1997c Compare July 28, 2026 02:51

jandubois marked this pull request as ready for review July 28, 2026 05:00

jandubois mentioned this pull request Jul 29, 2026

DO NOT MERGE: plain-Windows integration check #5343

Draft

AkihiroSuda reviewed Jul 29, 2026

View reviewed changes

AkihiroSuda added this to the v2.3.0 milestone Jul 29, 2026

AkihiroSuda added documentation Improvements or additions to documentation host/Windows labels Jul 29, 2026

jandubois force-pushed the docs-plain-windows-wsl2 branch from df1997c to b1245ee Compare July 31, 2026 05:30

jandubois force-pushed the docs-plain-windows-wsl2 branch from b1245ee to 19dc338 Compare July 31, 2026 05:53

AkihiroSuda reviewed Aug 1, 2026

View reviewed changes

AkihiroSuda requested changes Aug 1, 2026

View reviewed changes

	On a Windows host, "qemu" needs an OpenSSH installation for its own `ssh`,
	On a Windows host, "qemu" needs an [OpenSSH installation](URL GOES HERE) for its own `ssh`,


		### Windows toolchain

		Windows 10 and 11 ship an OpenSSH client in `C:\Windows\System32\OpenSSH\`, and

Uh oh!

Conversation

jandubois commented Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jandubois commented Jul 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jandubois Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jandubois commented Jul 26, 2026 •

edited

Loading

jandubois Jul 31, 2026 •

edited

Loading