config-central/docs/advanced-remote-access.md

8.5 KiB

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. 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:

$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. Confirm that the Windows network is marked Private, then test password login from CachyOS before changing authentication settings:

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:

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:

$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:

$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.

Test the key from a second CachyOS terminal while the password-authenticated session remains open:

ssh -i ~/.ssh/config-central Alice@win-office

Only after key login works, edit C:\ProgramData\ssh\sshd_config as Administrator and set:

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:

& "$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:

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:

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:

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:

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:

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:

$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.

For structured PowerShell sessions instead of a normal terminal, configure the PowerShell SSH subsystem as described in Microsoft's PowerShell remoting over SSH guide, 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:

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.