dotfiles: give git the ssh.exe that pushes at line rate

[dotfiles] / README.md

diff --git a/README.md b/README.md
index e10d872a599b87930611d76d599e4a8fb69e255b..dfe024e6efa0f2594889dcfe22b7e2875302e414 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,9 +14,9 @@ throwaway VM reachable from a Linux host.
 
 | File | Purpose |
 | --- | --- |
 
 | File | Purpose |
 | --- | --- |

-| `setup-windows.bat` | Entry point. Runs the winget installs, then the non-elevated script, then launches the elevated half and prints its log. |
+| `setup-windows.bat` | Entry point. Runs the winget installs, then launches the elevated half and prints its log, then runs the non-elevated script. |

 | `setup-windows-no-uac.ps1` | The non-elevated, per-user half: WinMerge and BinSkim on the user `PATH`, and the global git config (identity, plus `core.sshCommand`). Can also be run directly from an ordinary prompt. |
 | `setup-windows-no-uac.ps1` | The non-elevated, per-user half: WinMerge and BinSkim on the user `PATH`, and the global git config (identity, plus `core.sshCommand`). Can also be run directly from an ordinary prompt. |

-| `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, installs and starts OpenSSH Server, installs `rsync.exe` to the machine `PATH`, then installs Visual Studio 2022 Community with the required components, the WDK, and the Windows Performance Toolkit. Can also be run directly from an Administrator prompt. |
+| `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, installs the OpenSSH Client and Server capabilities and starts `sshd`, unpacks the `rsync-windows` release zip for this architecture (`rsync.exe` plus the `ssh.exe` it runs) into `C:\Tools\rsync` on the machine `PATH`, then installs Visual Studio 2022 Community with the required components, the WDK, and the Windows Performance Toolkit. Can also be run directly from an Administrator prompt. |

 
 ## Usage
 
 
 ## Usage
 


@@ -50,15 +50,27 @@ throwaway VM reachable from a Linux host.
 - The elevated half writes a transcript to `setup-windows-uac.log` next to the
   script; the batch file prints it when the elevated window closes. The log is
   gitignored, as it contains local paths.
 - The elevated half writes a transcript to `setup-windows-uac.log` next to the
   script; the batch file prints it when the elevated window closes. The log is
   gitignored, as it contains local paths.

-- **git uses the Windows SSH client.** `setup-windows-no-uac.ps1` sets
-  `core.sshCommand` to `%WINDIR%/System32/OpenSSH/ssh.exe`. Git for Windows
-  otherwise prefers its own bundled MSYS2 `ssh.exe`, which cannot reach the
-  Windows `ssh-agent` service that the elevated half enables - Win32-OpenSSH
-  publishes the agent on a named pipe the MSYS2 build does not speak. Without
-  this, keys loaded with `ssh-add` from PowerShell are invisible to `git`, and a
-  push falls back to hunting for a key file and prompting for its passphrase.
-  The value uses forward slashes on purpose: git parses `core.sshCommand` with
-  shell quoting rules, in which a backslash is an escape character.
+- **git uses a Win32-OpenSSH client.** `setup-windows-no-uac.ps1` sets
+  `core.sshCommand`. Git for Windows otherwise prefers its own bundled MSYS2
+  `ssh.exe`, which cannot reach the Windows `ssh-agent` service that the elevated
+  half enables - Win32-OpenSSH publishes the agent on a named pipe the MSYS2
+  build does not speak. Without this, keys loaded with `ssh-add` from PowerShell
+  are invisible to `git`, and a push falls back to hunting for a key file and
+  prompting for its passphrase. The value uses forward slashes on purpose: git
+  parses `core.sshCommand` with shell quoting rules, in which a backslash is an
+  escape character.
+- **Which `ssh.exe` git gets.** `C:\Tools\rsync\ssh.exe` — the fast build the
+  elevated half unpacks — if it is there, `%WINDIR%/System32/OpenSSH/ssh.exe`
+  otherwise. It is the same client with the same `~/.ssh`, agent and
+  `known_hosts`; the difference is the stdin pump, and without it anything git
+  *pushes* is capped at ~17 MB/s. Candidates are tried by **running** them
+  (`ssh -V`), not by `Test-Path`: the fast build needs a `libcrypto.dll` that an
+  image without the OpenSSH Client capability does not have, and a client that
+  will not start should be found here rather than on the next `git push`.
+  This is also why `setup-windows.bat` now runs the elevated half **first** — the
+  fast `ssh.exe` has to exist before the git config step can prefer it. The
+  non-elevated half still runs even when the elevated one failed; it just falls
+  back. Re-run `setup-windows-no-uac.ps1` on its own at any time to re-pick.

 - All three scripts are idempotent — re-running skips anything already installed.
   BinSkim in particular checks NuGet for the newest stable version *before*
   downloading: the package is a self-contained .NET build well over 100 MB, and
 - All three scripts are idempotent — re-running skips anything already installed.
   BinSkim in particular checks NuGet for the newest stable version *before*
   downloading: the package is a self-contained .NET build well over 100 MB, and


@@ -83,6 +95,26 @@ throwaway VM reachable from a Linux host.
   a profile. Key auth needs `~/.ssh/authorized_keys` ACL'd to just you and
   `SYSTEM`; accounts in the Administrators group use
   `C:\ProgramData\ssh\administrators_authorized_keys` instead.
   a profile. Key auth needs `~/.ssh/authorized_keys` ACL'd to just you and
   `SYSTEM`; accounts in the Administrators group use
   `C:\ProgramData\ssh\administrators_authorized_keys` instead.

+- **rsync brings its own `ssh.exe`.** That release ships as one zip per
+  architecture — `rsync-windows-x64.zip` / `rsync-windows-x86.zip`, each holding
+  `rsync.exe`, an `ssh.exe`, `COPYING.txt` and `NOTICE-ssh.txt` — and the
+  elevated half picks the zip for the OS bitness, verifies it against the
+  published `.sha256`, and unpacks the pair together. Together is the point:
+  `rsync.exe` prefers an `ssh.exe` sitting in its own directory, and the release
+  builds one because the client Windows ships reads its stdin 3 KB at a time,
+  which holds a transfer *from* the box at ~17 MB/s however fast the link is.
+  Nothing else about it differs — same `~/.ssh`, same `ssh-agent`, same
+  `known_hosts` — and a bare `ssh` still resolves to the in-box client, which
+  sits ahead of `C:\Tools\rsync` on the `PATH`. It links against the
+  `libcrypto.dll` the **OpenSSH Client** capability puts in `System32` (Windows'
+  own LibreSSL, which uses AES-NI) and ships no copy of its own, so the elevated
+  half installs that capability first and falls back to `rsync.exe` alone,
+  warning, on an image that will not offer it.
+- The `rsync` download follows the `releases/latest/download/` redirect rather
+  than the GitHub API: unauthenticated API calls are rate-limited to 60/hour per
+  IP, which a provisioning run behind a shared NAT can genuinely exhaust. To hold
+  a box on a known build, pin the tag in `$RsyncUrl`
+  (`.../releases/download/<tag>/<asset>`) instead.

 - Visual Studio is installed in three labelled passes (base workload, Clang/LLVM,
   XP toolset) so a failure identifies which component group is responsible.
 - The scripts were extracted from a native Windows project, so the component
 - Visual Studio is installed in three labelled passes (base workload, Clang/LLVM,
   XP toolset) so a failure identifies which component group is responsible.
 - The scripts were extracted from a native Windows project, so the component