dotfiles: point git at the Windows SSH client, split out the non-elevated half

[dotfiles] / README.md

diff --git a/README.md b/README.md
index 5fd887847a29875a71a1baba5edb5838d9735af8..e10d872a599b87930611d76d599e4a8fb69e255b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,27 +6,32 @@ Windows development-box provisioning scripts.
 development environment: editors and shells, Python, the Visual Studio 2022
 toolchain (including the Clang and Windows XP targeting toolsets), the Windows
 Driver Kit, and a handful of analysis tools (Sysinternals, OpenCppCoverage,
 development environment: editors and shells, Python, the Visual Studio 2022
 toolchain (including the Clang and Windows XP targeting toolsets), the Windows
 Driver Kit, and a handful of analysis tools (Sysinternals, OpenCppCoverage,

-BinSkim, the Windows Performance Toolkit).
+BinSkim, the Windows Performance Toolkit). It also sets the box up to be driven
+remotely: OpenSSH Server plus an rsync build for Windows, which is what makes a
+throwaway VM reachable from a Linux host.

 
 ## Files
 
 | File | Purpose |
 | --- | --- |
 
 ## Files
 
 | File | Purpose |
 | --- | --- |

-| `setup-windows.bat` | Entry point. Runs the non-elevated, per-user half (winget installs, user `PATH` edits, global git config), then launches the elevated half and prints its log. |
-| `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, 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.bat` | Entry point. Runs the winget installs, then the non-elevated script, then launches the elevated half and prints its log. |
+| `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. |

 
 ## Usage
 
 
 ## Usage
 

-1. **Edit `setup-windows.bat` first.** The global git identity near the middle of
-   the file is placeholder text:
+1. **Edit `setup-windows-no-uac.ps1` first.** The global git identity near the
+   top of the file is empty:

 
 

-   ```bat
-   git config --global user.name "PLACEHOLDER_NAME"
-   git config --global user.email "PLACEHOLDER_EMAIL"
+   ```powershell
+   $GitUserName  = ''   # e.g. 'Ada Lovelace'
+   $GitUserEmail = ''   # e.g. 'ada@example.com'

    ```
 
    ```
 

-   Substitute your own name and email, or comment both lines out to keep your
-   identity per-repository.
+   Fill in your own name and email, or leave them empty to keep your identity
+   per-repository - the script skips `user.name` / `user.email` rather than
+   writing a placeholder, and says so. Everything else in that script is set
+   either way.

 
 2. Run it from a normal (non-elevated) prompt:
 
 
 2. Run it from a normal (non-elevated) prompt:
 


@@ -45,7 +50,39 @@ BinSkim, the Windows Performance Toolkit).
 - 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.

-- Both halves are idempotent — re-running skips anything already installed.
+- **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.
+- 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
+  re-provisioning an up-to-date box should not pay for it. The installed version
+  is tracked in `nupkg-version.txt` beside the tool.
+- `setup-windows-no-uac.ps1` runs its steps independently: one failing warns and
+  the rest still run, and it exits 1 if any did. The `.bat` reports that and
+  carries on to the elevated half, which is the part worth the UAC prompt. Use
+  `-Skip` to re-run a subset, e.g. `.\setup-windows-no-uac.ps1 -Skip BinSkim`.
+  Run it **non-elevated**: it writes per-user state (the `HKCU` `PATH`, the
+  `.gitconfig` under `%USERPROFILE%`), so an elevated run would configure the
+  administrator's profile instead. It warns if you do.
+- **Remote access.** OpenSSH Server is installed from the Windows on-demand
+  capability (10/1809+), set to start automatically, and given an inbound TCP 22
+  firewall rule on *all* profiles — a VM's host-only or bridged adapter is
+  routinely classified Public, which is the usual reason a running `sshd` is
+  unreachable. Windows ships no `rsync`, so a build of it
+  ([nuket/rsync-windows](https://github.com/nuket/rsync-windows)) is installed to
+  `C:\Tools\rsync` and added to the **machine** `PATH`. That last detail matters:
+  the remote end of an `rsync` runs non-interactively, with no login shell, and
+  Win32-OpenSSH builds that environment from the registry `PATH` rather than from
+  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.

 - 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