In this step-by-step tutorial, learn how you use PowerShell with OpenSSH to set up OpenSSH on Windows to connect to machines over PowerShell Remoting.

This blog post has a companion video created by TechSnips contributor, Matt McElreath. Feel free to have a watch or, if you prefer text, read on!

If you try to create a new PSSession over SSH after installing OpenSSH, you may see the following error:

Enter-PSSession : An error has occurred which PowerShell cannot handle. A remote session might have ended.

Add the OpenSSH Folder to the PATH environment variable

To remedy this, first make sure that the path to the ssh.exe executable is in the PATH environment variable on the computer that you will be using to connect to a remote SSH server. To do this, click on the Start button and search for advanced system settings then click on View Advanced System Settings.

Advanced system settings

Then, click on the Environment Variables button in the System Properties windows.

Environment variables

Select Path from the System Variables list and click Edit.

Viewing the PATH environment variable

On the Edit Environment Variable window, click New then enter the path where the ssh.exe executable resides. In my case, this path is C:\Program Files\OpenSSH.

Adding the OpenSSH folder path to the PATH environment variable

Click OK twice to save the new value.

Open a new PowerShell 6 console so the new PATH change can take effect and retry the connection again. You will notice that we are now being prompted for a password. That looks promising. But when we enter the password, we're presented with another error.

Enter-PSSession : The background process reported an error with the following message: The SSH client session has ended with error message: subsystem request failed on channel 0.

This is because we haven't specified the subsystem we want PowerShell to use when connecting over SSH. This is specified in the ssh_config folder on the remote server. This is located under c:\ProgramData\ssh\.

Specify the PowerShell Subsystem

Under the override default of no subsystems section of the ssh_config file, add a line that specifies the location of the pwsh.exe executable. However, OpenSSH doesn't handle spaces in file paths well, so we need to create a symbolic link on the C:\ drive and point it to the location of the pwsh.exe executable with PowerShell.

New-Item -ItemType SymbolicLink -Path c:\pwsh -Value "C:\Program Files\PowerShell\6-preview" -Force

Now you're ready to update the ssh_config file.

On the remote server, open the ssh_config file under C:\ProgramData\ssh. Under the override default of no subsystems section add the following line.

Subsystem � �powershell C:\pwsh\pwsh.exe -sshs -NoLogo -NoProfile

Adding the PowerShell Subsystem line

Save the ssh_config file then restart the SSH services on the remote server.

Get-Service -Name ssh* | Restart-Service -Verbose

Now, let's try to open a PSSession again.

Successful OpenSSH connection

Success! Now go ahead exit that session and verify that we are in fact connecting through SSH to the remote server by using New-PSSession.

Creating a new session

We can see under transport that the session is connecting over the SSH protocol. If we compare that to using New-PSSession with the original ComputerName parameter, we can see that is using the WSMan protocol.

WSMan is being used


In this blog post, you have learned how to get OpenSSH set up and running on Windows. Once you've got OpenSSH set up, you can then begin leveraging PowerShell Remoting to use SSH instead of WinRM.