diff --git a/TASKS.md b/TASKS.md index 5527721..6af0045 100644 --- a/TASKS.md +++ b/TASKS.md @@ -98,6 +98,7 @@ open until it is run on disposable machines with the required account setups. - [x] Add opt-in scheduled user-context sync with a defined policy for operations requiring elevation. - [x] Add targeted application adapters or registry settings for concrete needs. +- [x] Document key-based remote administration from a Linux workstation. - [ ] Add explicit package removal or managed-file cleanup if requested. ## Requested desktop configuration diff --git a/docs/advanced-remote-access.md b/docs/advanced-remote-access.md new file mode 100644 index 0000000..e186cce --- /dev/null +++ b/docs/advanced-remote-access.md @@ -0,0 +1,245 @@ +# Advanced remote access from CachyOS + +Use Windows OpenSSH Server for routine remote administration. Windows 10 1809, +Windows 11, and current Windows Server releases provide OpenSSH as an optional +component, while CachyOS already uses the standard OpenSSH client tooling. This +gives each desktop a normal `ssh` shell plus `scp` and `sftp` file transfer. + +The Ruby program you may remember is +[Evil-WinRM](https://rubygems.org/gems/evil-winrm). It is primarily presented as +a hacking and penetration-testing WinRM shell. It can connect to an existing +WinRM deployment, but it is unnecessary here: cross-platform WinRM requires +additional listener, authentication, and certificate decisions that OpenSSH +avoids. + +## Network boundary + +Use these instructions on a trusted private LAN. Do not forward TCP port 22 from +the internet to a desktop. When access is needed away from home, connect the +machines through a VPN first and allow SSH only over that private network. + +Give each Windows machine a DHCP reservation or a stable local DNS name. The +examples below use `win-office` and the Windows account `Alice`; replace both. + +## Install the Windows SSH server + +On each Windows desktop, open PowerShell as Administrator and run: + +```powershell +$capability = Get-WindowsCapability -Online -Name 'OpenSSH.Server~~~~0.0.1.0' +if ($capability.State -ne 'Installed') { + Add-WindowsCapability -Online -Name 'OpenSSH.Server~~~~0.0.1.0' +} + +Set-Service -Name sshd -StartupType Automatic +Start-Service -Name sshd + +if (-not (Get-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -ErrorAction SilentlyContinue)) { + New-NetFirewallRule ` + -Name 'OpenSSH-Server-In-TCP' ` + -DisplayName 'OpenSSH Server (sshd)' ` + -Enabled True ` + -Profile Private ` + -Direction Inbound ` + -Protocol TCP ` + -Action Allow ` + -LocalPort 22 ` + -RemoteAddress LocalSubnet +} +else { + Set-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' -Enabled True -Profile Private + Get-NetFirewallRule -Name 'OpenSSH-Server-In-TCP' | + Get-NetFirewallAddressFilter | + Set-NetFirewallAddressFilter -RemoteAddress LocalSubnet +} +``` + +Microsoft documents the optional-component and service setup in +[Get started with OpenSSH Server for Windows](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse). +Confirm that the Windows network is marked **Private**, then test password login +from CachyOS before changing authentication settings: + +```bash +ssh Alice@win-office +``` + +`LocalSubnet` limits the firewall rule to the directly connected network. When +using a VPN subnet instead, replace it with that subnet's CIDR range. + +## Add a dedicated SSH key + +Create a separate key on CachyOS and protect it with a passphrase: + +```bash +ssh-keygen -t ed25519 -a 100 -f ~/.ssh/config-central +cat ~/.ssh/config-central.pub +``` + +Copy the single printed `ssh-ed25519 ...` line. For a standard Windows user, +open PowerShell as that user and save the line as follows: + +```powershell +$publicKey = 'ssh-ed25519 AAAA... replace-with-the-complete-key' +$sshDirectory = Join-Path $HOME '.ssh' +New-Item -ItemType Directory -Path $sshDirectory -Force | Out-Null +$authorizedKeys = Join-Path $sshDirectory 'authorized_keys' +$existingKeys = if (Test-Path $authorizedKeys) { [IO.File]::ReadAllLines($authorizedKeys) } else { @() } +if ($publicKey -notin $existingKeys) { + [IO.File]::WriteAllLines($authorizedKeys, @($existingKeys) + $publicKey, [Text.UTF8Encoding]::new($false)) +} +``` + +Windows OpenSSH uses a shared file for accounts that belong to the local +Administrators group. For such an account, run this instead from an elevated +PowerShell window: + +```powershell +$publicKey = 'ssh-ed25519 AAAA... replace-with-the-complete-key' +$authorizedKeys = Join-Path $env:ProgramData 'ssh\administrators_authorized_keys' +$existingKeys = if (Test-Path $authorizedKeys) { [IO.File]::ReadAllLines($authorizedKeys) } else { @() } +if ($publicKey -notin $existingKeys) { + [IO.File]::WriteAllLines($authorizedKeys, @($existingKeys) + $publicKey, [Text.UTF8Encoding]::new($false)) +} +icacls.exe $authorizedKeys /inheritance:r /grant '*S-1-5-32-544:F' /grant '*S-1-5-18:F' +``` + +The different key locations and required administrator-file permissions come +from Microsoft's +[Windows OpenSSH key-management guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement). + +Test the key from a second CachyOS terminal while the password-authenticated +session remains open: + +```bash +ssh -i ~/.ssh/config-central Alice@win-office +``` + +Only after key login works, edit `C:\ProgramData\ssh\sshd_config` as +Administrator and set: + +```text +PubkeyAuthentication yes +PasswordAuthentication no +AllowUsers alice +``` + +Replace `alice` with the exact login you successfully tested. Windows OpenSSH +expects names in `AllowUsers` to be lowercase; omit that line until the correct +local or domain account spelling is known. Validate the configuration and +restart the service without closing the working session: + +```powershell +& "$env:WINDIR\System32\OpenSSH\sshd.exe" -t +if ($LASTEXITCODE -ne 0) { throw 'Invalid sshd_config; do not restart sshd.' } +Restart-Service sshd +``` + +Open another new connection before ending the original session. This prevents a +configuration mistake from locking you out. + +## Use short machine names from CachyOS + +Create or edit `~/.ssh/config`: + +```sshconfig +Host cc-office + HostName win-office + User Alice + IdentityFile ~/.ssh/config-central + IdentitiesOnly yes + +Host cc-living-room + HostName 192.168.1.52 + User Alice + IdentityFile ~/.ssh/config-central + IdentitiesOnly yes +``` + +Protect the files and connect by alias: + +```bash +chmod 700 ~/.ssh +chmod 600 ~/.ssh/config ~/.ssh/config-central +ssh cc-office +``` + +The first connection displays the server host-key fingerprint. Compare it with +the fingerprint shown locally on Windows before accepting it: + +```powershell +Get-ChildItem $env:ProgramData\ssh\ssh_host_*_key.pub | + ForEach-Object { ssh-keygen.exe -lf $_.FullName } +``` + +## Use Config Central remotely + +Once the alias works, most inspection and config-only operations need no trip to +the Windows desktop: + +```bash +ssh cc-office 'cc doctor' +ssh cc-office 'cc configs' +ssh cc-office 'cc configs -Config xnviewmp-settings -Json' +ssh cc-office 'cc status -ConfigsOnly' +ssh cc-office 'cc sync -ConfigsOnly' +``` + +Commit and push repository edits from CachyOS, then run `cc sync -ConfigsOnly` +on each desktop. Keep package installation and other UAC-dependent operations +for an interactive Windows session unless the SSH account already has the +required elevated token; a remote shell cannot approve a secure-desktop UAC +prompt. + +Use SFTP for deliberate file retrieval. `cc configs -Config NAME` shows the live +path before copying anything: + +```bash +sftp cc-office +sftp> get C:/Users/Alice/AppData/Roaming/XnViewMP/xnview.ini ./xnview-office.ini +sftp> exit +``` + +Review retrieved files locally and copy only the portable values into the +repository declaration. In particular, never retrieve and commit the complete +Nextcloud configuration. + +## Optional PowerShell as the login shell + +Windows initially opens `cmd.exe` for an SSH login. To make PowerShell 7 the +default, run this in an elevated Windows PowerShell session: + +```powershell +$pwsh = (Get-Command pwsh.exe -ErrorAction Stop).Source +New-Item -Path 'HKLM:\SOFTWARE\OpenSSH' -Force | Out-Null +New-ItemProperty ` + -Path 'HKLM:\SOFTWARE\OpenSSH' ` + -Name DefaultShell ` + -Value $pwsh ` + -PropertyType String ` + -Force | Out-Null +Restart-Service sshd +``` + +Microsoft documents this registry setting in +[OpenSSH Server configuration for Windows](https://learn.microsoft.com/en-us/windows-server/administration/OpenSSH/openssh-server-configuration). + +For structured PowerShell sessions instead of a normal terminal, configure the +PowerShell SSH subsystem as described in Microsoft's +[PowerShell remoting over SSH guide](https://learn.microsoft.com/en-us/powershell/scripting/learn/remoting/ssh-remoting-in-powershell), +then use `Enter-PSSession -HostName ...` from PowerShell 7 on CachyOS. The normal +SSH shell is sufficient for Config Central commands and has fewer moving parts. + +## Troubleshooting + +On Windows, check the service and listening port: + +```powershell +Get-Service sshd +Get-NetTCPConnection -LocalPort 22 -State Listen +Get-NetFirewallRule -Name OpenSSH-Server-In-TCP +``` + +Run `ssh -vvv cc-office` on CachyOS for client diagnostics. Windows records SSH +events under **Applications and Services Logs > OpenSSH > Operational** in Event +Viewer. Keep one known-working session open while changing keys or +`sshd_config`.