Skip to content

Commit ae295f2

Browse files
v-tappelgatev-tappelgate
authored
Merge pull request #10405 from v-tappelgate/AB#7982-Upgrade-OpenSSH
AB#7982: Upgrading OpenSSH on Windows
2 parents 78916c5 + 6584b78 commit ae295f2

3 files changed

Lines changed: 222 additions & 0 deletions

File tree

‎support/windows-client/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1101,6 +1101,8 @@ items:
11011101
href: ../windows-server/system-management-components/troubleshoot-sftp-issues-using-openssh.md?context=/troubleshoot/windows-client/context/context
11021102
- name: Troubleshoot OpenSSH communication through Windows Firewall
11031103
href: ../windows-server/system-management-components/troubleshoot-openssh-windows-firewall-port22.md?context=/troubleshoot/windows-client/context/context
1104+
- name: Upgrade in-box OpenSSH to the latest OpenSSH release
1105+
href: ../windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release.md?context=/troubleshoot/windows-client/context/context
11041106
- name: Use "MaxStartups" and "MaxSessions" to troubleshoot OpenSSH connection issues
11051107
href: ../windows-server/system-management-components/troubleshoot-openssh-connection-issues-maxstartups-maxsessions.md?context=/troubleshoot/windows-client/context/context
11061108
- name: PowerShell

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

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
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 alternative access methods (such as RDP or console) available.
30+
- Make sure that 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, the software 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+
## Step 1: Back up the configuration and keys
40+
41+
Before you upgrade, back up all configuration and key files.
42+
43+
The following table lists the files and their default folder locations
44+
45+
| Folder and files | Description |
46+
| --- | --- |
47+
| C:\ProgramData\ssh\sshd_config | The server configuration file |
48+
| C:\ProgramData\ssh\administrators_authorized_keys | Keys for administrator accounts |
49+
| C:\\ProgramData\\ssh\\ssh_host\_\*\_key | Host identity keys |
50+
| C:\\Users\\\<UserName>\\.ssh\\authorized_keys | Per-user keys |
51+
52+
To copy these files, open a Windows PowerShell command prompt, and run a cmdlet that resembles the following cmdlet:
53+
54+
```powershell
55+
Copy-Item "C:\ProgramData\ssh" -Destination "C:\Backup\ssh_backup" -Recurse
56+
```
57+
58+
> [!IMPORTANT]
59+
>
60+
> - To avoid client trust warnings, don't change the host or user keys.
61+
> - 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:
62+
>
63+
> ```powershell
64+
> Get-Acl "C:\ProgramData\ssh\ssh_host_ed25519_key" | Format-List
65+
> ```
66+
67+
## Step 2: Upgrade OpenSSH
68+
69+
To upgrade OpenSSH, select one of the following methods:
70+
71+
- [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)
72+
- [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)
73+
- [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)
74+
75+
### Option 1: Use an MSI installer to upgrade OpenSSH to the latest GitHub release
76+
77+
> [!NOTE]
78+
> 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.
79+
80+
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 Win64 or Win32 OpenSSH .msi file.
81+
82+
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:
83+
84+
```powershell
85+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi
86+
```
87+
88+
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:
89+
90+
```powershell
91+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi ADDLOCAL=Client
92+
msiexec /i OpenSSH-Win64-v9.x.x.x.msi ADDLOCAL=Server
93+
```
94+
95+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets on the computer where you installed the server component:
96+
97+
```powershell
98+
Start-Service sshd
99+
Set-Service sshd -StartupType Automatic
100+
```
101+
102+
If the service wasn't created, run the following command:
103+
104+
```powershell
105+
PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\OpenSSH\install-sshd.ps1"
106+
```
107+
108+
### Option 2: Use a .zip file to upgrade OpenSSH to the latest GitHub release
109+
110+
If you don't want to use the MSI package to install the upgrade, you can use a .zip archive file.
111+
112+
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.
113+
114+
1. Extract the .zip file to C:\Program Files\OpenSSH.
115+
116+
1. Open an administrative PowerShell window, change to the C:\Program Files\OpenSSH folder, and then run the following command:
117+
118+
```powershell
119+
PowerShell.exe -ExecutionPolicy Bypass -File .\install-sshd.ps1
120+
```
121+
122+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets.
123+
124+
```powershell
125+
Start-Service sshd
126+
Set-Service sshd -StartupType Automatic
127+
```
128+
129+
### Option 3: Upgrade OpenSSH to the latest Windows Update release instead of the GitHub release
130+
131+
1. To check the current version of OpenSSH, run `ssh -V` at a PowerShell command prompt.
132+
133+
1. To uninstall the current version of OpenSSH, run the following cmdlets at a PowerShell command prompt:
134+
135+
```powershell
136+
Remove-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
137+
Remove-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
138+
```
139+
140+
1. After the software is uninstalled, restart Windows.
141+
142+
1. To install the latest release from Windows Update, run the following cmdlets at a PowerShell command prompt:
143+
144+
```powershell
145+
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
146+
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
147+
```
148+
149+
1. To configure the OpenSSH Server service and then start it, run the following cmdlets:
150+
151+
```powershell
152+
Start-Service sshd
153+
Set-Service sshd -StartupType Automatic
154+
```
155+
156+
## Step 3: Create the firewall rule, if it's necessary
157+
158+
1. To check for existing firewall rules, go to your OpenSSH client computer, and run the following cmdlet at a PowerShell command prompt:
159+
160+
```powershell
161+
Get-NetFirewallRule -DisplayName "*SSH*" | Get-NetFirewallPortFilter | Where-Object {$_.LocalPort -eq 22}
162+
```
163+
164+
1. If you can't find an existing SSH rule, open an administrative PowerShell command prompt window. Then, run the following cmdlet:
165+
166+
```powershell
167+
New-NetFirewallRule -Name "OpenSSH-Server-In-TCP" -DisplayName "OpenSSH Server (SSH)" -Enabled True -Direction Inbound -Protocol TCP -LocalPort 22 -Action Allow
168+
```
169+
170+
1. To verify that the rule is correctly configured, run `Get-NetFirewallRule` again.
171+
172+
## Step 4: Verify the installation
173+
174+
1. Make sure that C:\ProgramData\ssh still has your previous configuration and keys. If it's necessary, restore this information from your backup.
175+
176+
1. To check the version, run `ssh -V` at the PowerShell command prompt.
177+
178+
1. To check the service status and connectivity, run the following cmdlets at a PowerShell command prompt:
179+
180+
```powershell
181+
Get-Service sshd
182+
ssh localhost
183+
```
184+
185+
> [!NOTE]
186+
> The display name of the service is "OpenSSH SSH Server."
187+
188+
1. To verify that you're using the correct SSH binary, run the following cmdlets at a Windows PowerShell command prompt:
189+
190+
```powershell
191+
Get-Command ssh.exe | Select-Object Source
192+
```
193+
194+
1. To check for errors, open Event Viewer, and then select **Applications and Services Logs** > **OpenSSH** > **Operational**.
195+
196+
1. Make sure that administrators and users can authenticate.
197+
198+
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 folders.
199+
200+
## Common issues quick reference
201+
202+
| **Symptom** | **Likely cause** | **Resolution** |
203+
| --- | --- | --- |
204+
| SSH service doesn't start | Missing or misconfigured host keys | Restore backed-up keys and restart the service |
205+
| Authentication errors | Improper key file permissions | Make sure that only SYSTEM and Administrators can read or write key files |
206+
| Old binaries still run | PATH still points to System32\OpenSSH | Remove or rename the outdated directory |
207+
| Port 22 unreachable | Firewall rule is missing | Re-create the inbound rule for TCP port 22 |
208+
209+
## Related articles
210+
211+
- [Releases · PowerShell/Win32-OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/releases)
212+
- [OpenSSH for Windows overview](/windows-server/administration/OpenSSH/openssh-overview)
213+
- [Get started with OpenSSH Server for Windows](/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui&pivots=windows-server-2022)
214+
- [OpenSSH Server configuration for Windows Server and Windows](/windows-server/administration/OpenSSH/openssh-server-configuration)
215+
- [Key-Based Authentication in OpenSSH for Windows \| Microsoft Learn](/windows-server/administration/openssh/openssh_keymanagement)
216+
- [Install Win32 OpenSSH · PowerShell/Win32-OpenSSH Wiki · GitHub](https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH)
217+
- [OpenSSH: Manual Pages](https://www.openssh.com/manual.html)
218+
- [OpenSSH: Release Notes](https://www.openssh.com/releasenotes.html?)

‎support/windows-server/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2644,6 +2644,8 @@ items:
26442644
href: ./system-management-components/troubleshoot-sftp-issues-using-openssh.md
26452645
- name: Troubleshoot OpenSSH communication through Windows Firewall
26462646
href: ./system-management-components/troubleshoot-openssh-windows-firewall-port22.md
2647+
- name: Upgrade in-box OpenSSH to the latest OpenSSH release
2648+
href: ./system-management-components/upgrade-in-box-openssh-to-latest-openssh-release.md
26472649
- name: Use "MaxStartups" and "MaxSessions" to troubleshoot OpenSSH connection issues
26482650
href: ./system-management-components/troubleshoot-openssh-connection-issues-maxstartups-maxsessions.md
26492651
- name: PowerShell

0 commit comments

Comments
 (0)