diff --git a/website/content/en/docs/config/environment-variables.md b/website/content/en/docs/config/environment-variables.md index 373c261e..2a213265 100644 --- a/website/content/en/docs/config/environment-variables.md +++ b/website/content/en/docs/config/environment-variables.md @@ -214,3 +214,27 @@ This page documents the environment variables used in Lima. ```sh export QEMU_SYSTEM_X86_64=/usr/local/bin/qemu-system-x86_64 ``` + +### `SSH` + +- **Description**: Command to run in place of the `ssh` executable. The value is + split into shell tokens, so it can include arguments as well as a path. + `limactl copy` passes none of the `SSH` arguments to `scp`. It finds `scp` + on `$PATH`, except on Windows, where it takes the `scp.exe` next to the + selected `ssh.exe`. Tokenization reads `\` as an escape and splits on + spaces, so a Windows path works only inside single quotes; unquoted, + `C:\Program Files\Git\usr\bin\ssh.exe` arrives as `C:Program`. +- **Default**: unset. Lima then searches `$PATH`; on Windows it takes the first + directory holding `ssh.exe`, `scp.exe`, and `ssh-keygen.exe` together, and + falls back to `%SystemRoot%\System32\OpenSSH`. +- **Usage**: + ```sh + export SSH=/opt/homebrew/bin/ssh + ``` + ```powershell + $env:SSH = "'C:\Program Files\Git\usr\bin\ssh.exe'" + ``` +- **Note**: On Windows some paths still follow `PATH`, among them the guest + mount point and `limactl shell`'s working directory, so point `SSH` at the + install that comes first on `PATH`. `limactl guest-install` ignores this + variable altogether. diff --git a/website/content/en/docs/config/vmtype/qemu.md b/website/content/en/docs/config/vmtype/qemu.md index d1a63836..0ea59882 100644 --- a/website/content/en/docs/config/vmtype/qemu.md +++ b/website/content/en/docs/config/vmtype/qemu.md @@ -11,6 +11,14 @@ Recommended QEMU version: - v8.2.1 or later (macOS) - v6.2.0 or later (Linux) +On a Windows host, "qemu" needs `ssh`, `scp`, and `ssh-keygen`; the +[OpenSSH client](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse) +that Windows installs by default provides all three. Mounts must use +reverse-sshfs, because QEMU for Windows has no 9p support. Pinning +[`sftpDriver: openssh-sftp-server`]({{< ref "/docs/config/mount#reverse-sshfs" >}}) +also requires `sftp-server.exe`, which comes from the optional OpenSSH Server +feature. + An example configuration: {{< tabpane text=true >}} {{% tab header="CLI" %}} diff --git a/website/content/en/docs/config/vmtype/wsl2.md b/website/content/en/docs/config/vmtype/wsl2.md index 8f33fc9c..35f22156 100644 --- a/website/content/en/docs/config/vmtype/wsl2.md +++ b/website/content/en/docs/config/vmtype/wsl2.md @@ -37,12 +37,13 @@ containerd: ### Caveats - "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019) +- Windows installs an OpenSSH client in `C:\Windows\System32\OpenSSH\`, and the WSL2 driver needs no other SSH binaries ### Known Issues - "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. - When running lima using "wsl2", `${LIMA_HOME}//serial.log` will not contain kernel boot logs - 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. -- 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. +- Lima unpacks a `.tar.gz` rootfs on its own, but a `.tar.xz`, `.tar.bz2`, or `.tar.zst` one needs the matching `xz`, `bzip2`, or `zstd` binary on your `PATH`, and Windows ships none of them. ### Rootfs Image Requirements & Building Custom Images