Skip to content

Commit dc8b4ef

Browse files
v-tappelgatev-tappelgate
committed
AB#7982: Upgrading OpenSSH on Windows
New article for [CI 7982](https://dev.azure.com/KMOps/ContentExperience/_queries/edit/7982)
1 parent 00c0953 commit dc8b4ef

1 file changed

Lines changed: 224 additions & 0 deletions

File tree

‎support/windows-server/system-management-components/upgrade in-box-openssh-to-latest-openssh-release.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Upgrade in-box OpenSSH to the Latest OpenSSH Release
3+
description: Discusses the difference between the in-box and GitHub versions of OpenSSH, how to back up your existing configuration, and how to upgrade safely while keeping your service settings intact.
4+
ms.date: 12/19/2025
5+
manager: dcscontentpm
6+
audience: itpro
7+
ms.topic: troubleshooting
8+
ms.reviewer: kaushika, warrenw, v-appelgatet
9+
ai.usage: ai-assisted
10+
ms.custom:
11+
- sap:system management components\openssh (including sftp)
12+
- pcy:WinComm User Experience
13+
---
14+
15+
# Upgrade in-box OpenSSH to the latest OpenSSH release
16+
17+
To provide secure remote management by using Secure Shell (SSH), Windows includes OpenSSH as a Feature on Demand. However, the built-in (in-box) version that ships as part of the Windows and Windows Server installation media, such as 7.7p1 or 8.1p1, often lags behind the latest Win32-OpenSSH releases that are available on GitHub. To use newer encryption algorithms, enhanced logging, and important security updates, upgrade OpenSSH to the GitHub version.
18+
19+
This article explains the difference between the in-box and GitHub versions, how to back up your existing configuration, and how to upgrade safely while keeping your service settings intact. It also includes instructions for using Windows Update to manually update OpenSSH.
20+
21+
## Prerequisites
22+
23+
- Use local Administrator credentials to sign in to the computer.
24+
- Make sure that the OpenSSH Server service isn't handling active sessions.
25+
26+
> [!NOTE]
27+
> Upgrading temporarily stops the OpenSSH Server service and disconnects any active SSH sessions.
28+
29+
- In case the service restarts, have alternate access methods (such as RDP or console) available.
30+
- Make sure you have the correct permissions to modify C:\ProgramData\ssh and install MSI packages.
31+
- Before you install a new release in a production environment, test it in a staging environment first.
32+
33+
## Understanding in-box versus GitHub OpenSSH
34+
35+
By default, you use Windows Update to install and maintain the in-box OpenSSH feature. Typically, it resides in C:\Windows\System32\OpenSSH. The in-box version is Microsoft-supported and stable, but it updates only when Windows itself updates.
36+
37+
The GitHub version, known as Win32-OpenSSH, installs in C:\Program Files\OpenSSH, and has the newest features and fixes. However, you have to manually update it.
38+
39+
## Best practices
40+
41+
- Keep your host and user keys unchanged to avoid client trust warnings.
42+
43+
- Verify file permissions after upgrading.
44+
45+
- Monitor the Win32-OpenSSH GitHub page for future updates.
46+
47+
## Step 1: Back up the configuration and keys
48+
49+
Before you upgrade, back up all configuration and key files.
50+
51+
The following table lists the files and their default folder locations
52+
53+
| Folder and files | Description |
54+
| --- | --- |
55+
| C:\ProgramData\ssh\sshd_config | The server configuration file |
56+
| C:\ProgramData\ssh\administrators_authorized_keys | Keys for admininstrator accounts |
57+
| C:\\ProgramData\\ssh\\ssh_host\_\*\_key | Host identity keys |
58+
| C:\\Users\\\<UserName>\\.ssh\\authorized_keys | Per-user keys |
59+
60+
To copy these files, open a Windows PowerShell command prompt and run a cmdlet that resembles the following cmdlet:
61+
62+
```powershell
63+
Copy-Item "C:\ProgramData\ssh" -Destination "C:\Backup\ssh_backup" -Recurse
64+
```
65+
66+
> [!IMPORTANT]
67+
> Don't change file permissions for either the source files and folders or the destination files and folders. Private keys must remain readable only by SYSTEM and Administrators. To verify the permissions, run a cmdlet that resembles the following cmdlet at a PowerShell command prompt:
68+
>
69+
> ```powershell
70+
> Get-Acl "C:\ProgramData\ssh\ssh_host_ed25519_key" | Format-List
71+
> ```
72+
73+
## Step 2: Upgrade OpenSSH
74+
75+
Select one of the following methods to upgrade OpenSSH:
76+
77+
- [Option 1: Use an MSI installer to upgrade OpenSSH to the latest GitHub release](#option-1-use-an-msi-installer-to-upgrade-openssh-to-the-latest-github-release)
78+
- [Option 2: Use a ZIP file to upgrade OpenSSH to the latest GitHub release](#option-2-use-a-zip-file-to-upgrade-openssh-to-the-latest-github-release)
79+
- [Option 3: Upgrade OpenSSH to the latest Windows Update release instead of the GitHub release](#option-3-upgrade-openssh-to-the-latest-windows-update-release-instead-of-the-github-release)
80+
81+
### Option 1: Use an MSI installer to upgrade OpenSSH to the latest GitHub release
82+
83+
> [!NOTE]
84+
> Depending on your processor, OpenSSH installs in either C:\Program Files\OpenSSH or C:\Program Files\OpenSSH-Win64. The installer automatically registers the OpenSSH services and updates the PATH environment variable.
85+
86+
1. To download the MSI installer, go to [Win32-OpenSSH releases page on GitHub](https://github.com/PowerShell/Win32-OpenSSH/releases) and download the latest OpenSSH-Win64.msi or Win32 build.
87+
88+
1. To install all components of the new version, open an administrative PowerShell command prompt window and run a cmdlet that resembles the following cmdlet:
89+
90+
```powershell
91+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi
92+
```
93+
94+
1. To install only the client or server component, open an administrative PowerShell command prompt window and run a cmdlet that resembles the one of the following cmdlets, as appropriate:
95+
96+
```powershell
97+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi ADDLOCAL=Client
98+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi ADDLOCAL=Server
99+
```
100+
101+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets on the computer where you installed the server component.
102+
103+
```powershell
104+
Start-Service sshd
105+
Set-Service sshd -StartupType Automatic
106+
```
107+
108+
If the service wasn't created, run the following command:
109+
110+
```powershell
111+
PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\OpenSSH\install-sshd.ps1"
112+
```
113+
114+
### Option 2: Use a ZIP file to upgrade OpenSSH to the latest GitHub release
115+
116+
If you don't want to use the MSI package to install the upgrade, you can use a ZIP archive file.
117+
118+
1. To download the latest ZIP file, go to [Win32-OpenSSH releases page on GitHub](https://github.com/PowerShell/Win32-OpenSSH/releases) and download the appropriate file.
119+
120+
1. Extract the ZIP file to C:\Program Files\OpenSSH.
121+
122+
1. Open an administrative PowerShell window, change to the C:\Program Files\OpenSSH folder, and then run the following command:
123+
124+
```powershell
125+
PowerShell.exe -ExecutionPolicy Bypass -File .\install-sshd.ps1
126+
```
127+
128+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets.
129+
130+
```powershell
131+
Start-Service sshd
132+
Set-Service sshd -StartupType Automatic
133+
```
134+
135+
### Option 3: Upgrade OpenSSH to the latest Windows Update release instead of the GitHub release
136+
137+
1. To check the current version of OpenSSH, run `ssh -V` at a PowerShell command prompt.
138+
139+
1. To uninstall the current version of OpenSSH, run the following cmdlets at a PowerShell command prompt:
140+
141+
```powershell
142+
Remove-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
143+
Remove-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
144+
```
145+
146+
1. After the uninstall operations finish, restart Windows.
147+
148+
1. To install the latest release from Windows Update, run the following cmdlets at a PowerShell command prompt.
149+
150+
```powershell
151+
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
152+
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
153+
```
154+
155+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets.
156+
157+
```powershell
158+
Start-Service sshd
159+
Set-Service sshd -StartupType Automatic
160+
```
161+
162+
## Step 3: Create the firewall rule, if necessary
163+
164+
1. To check for existing firewall rules, go to your OpenSSH client computer, and run the following cmdlet at a PowerShell command prompt:
165+
166+
```powershell
167+
Get-NetFirewallRule -DisplayName "*SSH*" | Get-NetFirewallPortFilter | Where-Object {$_.LocalPort -eq 22}
168+
```
169+
170+
1. If you can't find an existing SSH rule, open an administrative PowerShell command prompt window. Then, run the following cmdlet:
171+
172+
```powershell
173+
New-NetFirewallRule -Name "OpenSSH-Server-In-TCP" -DisplayName "OpenSSH Server (SSH)" -Enabled True -Direction Inbound -Protocol TCP -LocalPort 22 -Action Allow
174+
```
175+
176+
1. To verify that the rule is correctly configured, run `Get-NetFirewallRule` again.
177+
178+
## Step 4: Verify the installation
179+
180+
1. Make sure that C:\ProgramData\ssh still has your previous configuration and keys. If necessary, restore this information from your backup.
181+
182+
1. To check the version, run `ssh -V` at the PowerShell command prompt.
183+
184+
1. To check the service status and connectivity, run the following cmdlets at the PowerShell command prompt:
185+
186+
```powershell
187+
Get-Service sshd
188+
ssh localhost
189+
```
190+
191+
> [!NOTE]
192+
> The display name of the service is "OpenSSH SSH Server".
193+
194+
1. To verify that you're using the correct SSH binary, run the following cmdlets at the Windows PowerShell command prompt:
195+
196+
```powershell
197+
Get-Command ssh.exe | Select-Object Source
198+
```
199+
200+
1. To check for errors, open Event Viewer and then select **Applications and Services Logs** > **OpenSSH** > **Operational**.
201+
202+
1. Make sure that administrators and users can authenticate.
203+
204+
1. To avoid path conflicts check for multiple OpenSSH folders (typically in the System32 folder). If multiple OpenSSH folders exist, keep the newest folder and remove any older ones.
205+
206+
## Common issue quick reference
207+
208+
| **Symptom** | **Likely cause** | **Resolution** |
209+
| --- | --- | --- |
210+
| SSH service fails to start | Missing or misconfigured host keys | Restore backed-up keys and restart the service |
211+
| Authentication errors | Improper key file permissions | Make sure only SYSTEM and Administrators can read or write key files |
212+
| Old binaries still run | PATH still points to System32\OpenSSH | Remove or rename the outdated directory |
213+
| Port 22 unreachable | Firewall rule is missing | Recreate inbound rule for TCP port 22 |
214+
215+
## Related articles
216+
217+
- [Releases · PowerShell/Win32-OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/releases)
218+
- [OpenSSH for Windows overview](/windows-server/administration/OpenSSH/openssh-overview)
219+
- [Get started with OpenSSH Server for Windows](/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui&pivots=windows-server-2022)
220+
- [OpenSSH Server configuration for Windows Server and Windows](/windows-server/administration/OpenSSH/openssh-server-configuration)
221+
- [Key-Based Authentication in OpenSSH for Windows \| Microsoft Learn](/windows-server/administration/openssh/openssh_keymanagement)
222+
- [Install Win32 OpenSSH · PowerShell/Win32-OpenSSH Wiki · GitHub](https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH)
223+
- [OpenSSH: Manual Pages](https://www.openssh.com/manual.html)
224+
- [OpenSSH: Release Notes](https://www.openssh.com/releasenotes.html?)

0 commit comments

Comments
 (0)