You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: website/content/en/docs/config/vmtype/wsl2.md
+41-1Lines changed: 41 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,7 +42,6 @@ containerd:
42
42
- "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.
43
43
- When running lima using "wsl2", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
44
44
- 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.
46
45
47
46
### Rootfs Image Requirements & Building Custom Images
48
47
@@ -76,3 +75,44 @@ If you want to build and use your own custom rootfs, you can build it from a sta
76
75
docker build -o type=tar,dest=custom-rootfs.tar .
77
76
```
78
77
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
+
takes both the path form and the `sftp-server` binary from that
98
+
toolchain, so the path and the server that reads it match:
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
+
because the mount would point at a different directory across the
118
+
swap. Default installs without `fstab` overrides are unaffected.
0 commit comments