Skip to the main content.
Request demo
Request demo
Twitter Twitter GitHub GitHub

ScriptRunner Blog

Getting Started with PowerShell Remoting

15 min read

October 14, 2020

By: Adam Bertram Oct 14, 2020 12:08:50 PM

PowerShell Scripting

Table of Contents
Post Featured Image

PowerShell Remoting has been around since the early days of the PowerShell language and allows for running commands and receiving output between remote systems. Traditionally, PowerShell Remoting has been built on WinRM, but with newer PowerShell versions, the SSH protocol is now available to facilitate remoting between Linux systems as well. In this article, you’ll learn how to get started with PowerShell remoting, concentrating on PowerShell versions 5.1 and greater.

 

Requirements and Setup

There are three modern PowerShell variants still in widespread use. It is highly recommended moving to PowerShell 7 as this is a long-term release (LTS) and the most up-to-date. That being said, there are situations where this is not yet feasible.

PowerShell 5.1

This is the last version of Windows PowerShell that came bundled with the Windows operating system. Still in use by numerous companies, there are some simple requirements for remoting to work.
  • The Microsoft .NET Framework 4.5.2 or greater
    • .NET 4.6.2 comes pre-installed on Windows Server 2016
  • Windows Remote Management 5.1
    • Ships in-box for Windows Server 2016 and greater

In this article we concentrate on Windows Server 2016 as prior versions have been deemed end-of-life by Microsoft.

Take note that by default, Windows PowerShell will create a microsoft.powershell session endpoint. Enter-PSSession and New-PSSession will use this endpoint when no other session endpoint is specified. Since newer versions of PowerShell do not create or override this endpoint, the endpoint name must be specified to connect to the right remote instance, if not connecting to Windows PowerShell. An example of the default Windows PowerShell configuration is below (Figure 1).

Screenshot of the default Windows PowerShell configuration

Fig. 1: The default Windows PowerShell configuration


PowerShell Core (6.x)

PowerShell Core comes with the required .NET Core files necessary included out of the box. There are some steps necessary to make WinRM PowerShell Remoting work. Early versions of PowerShell Core did not have proper Enable-PSRemoting support and therefore required an installation script to move the pwrshplugin.dll file to System32 and register endpoints. In the latest point releases of PowerShell Core, Enable-PSRemoting does work correctly to register the DLL and version-specific endpoints (as seen in figure 2).

After running Enable-PSRemoting, the correct version-specific endpoints are registered, in this case 6.2.5 (figure 3).

 

Screenshot: WinRM PowerShell Remoting in PowerShell Core

Fig. 2: Enabling WinRM PowerShell Remoting in PowerShell Core


Screenshot: version-specific endpoints for PowerShell Core

Fig. 3: Version-specific endpoints for PowerShell Core

The reason that the -SkipNetworkProfileCheck parameter is specified is that any Public network will end the Enable-PSRemoting command early. As long as you are aware of the ramifications and proper control of this, then it is safe to run this command.


PowerShell 7

The latest version of PowerShell, similarly, does not require the Install-PowerShellRemoting.ps1 script anymore as Enable-PSRemoting registers everything needed, as seen below in figure 4, by running Enable-PSRemoting.
Screenshot: Output of the Enable-PSRemoting cmdlet in PowerShell 7

Fig. 4: Output of the Enable-PSRemoting cmdlet in PowerShell 7

The endpoint names that are then registered to allow for remoting are specific to the latest PowerShell version, in this case 7.0.1. (see figure 5).

Screenshot: List of endpoint names registered for PowerShell remoting in PowerShell 7

Fig. 5: List of the endpoint names registered for remoting with PowerShell 7

 


SSH Remoting Requirements

In PowerShell Core and PowerShell 7, the ability to use SSH as an endpoint is now available. There are a few requirements and steps necessary to make SSH remoting work.
  • PowerShell Core 6.x or PowerShell 7.x
  • ssh.exe (client) and sshd.exe (server)
  • Windows 10 build 1809 and Windows Server 2019 for built-in SSH (client)

Setup SSH Endpoints

Setting up PowerShell to use SSH requires the following steps and configurations.
  • Install OpenSSH Server and Client
    • OpenSSH for Windows is available directly in Windows 10 (1809 or higher) and Windows Server 2019 as an optional feature (visit Thomas Maurer’s Blog for instructions on how to install it on Windows 10 and on Windows Server)
    • On Linux, you can install OpenSSH depending on your platform
  • Configure the SSH subsystem to host a PowerShell process on the remote machine

Run the following commands to install the required capabilities (OpenSSH.Client may already be installed), service configuration, and firewall rules.

# Install the OpenSSH Client and Server 
Add-WindowsCapability -Online -Name 'OpenSSH.Client~~~~0.0.1.0' 
Add-WindowsCapability -Online -Name 'OpenSSH.Server~~~~0.0.1.0' 

# Initial Configuration of SSH Server 
Start-Service -Name 'sshd' 
Set-Service -Name 'sshd' -StartupType 'Automatic' 

# Confirm the Firewall rule is configured. It should be created automatically by setup. 
Get-NetFirewallRule -Name '*ssh*' | Format-Table -AutoSize 

# There should be a firewall rule named "OpenSSH-Server-In-TCP", which should be enabled 
New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

Finally, to enable the SSH server to work with PowerShell remoting, the subsystem must be correctly set.

notepad $Env:ProgramData\ssh\sshd_config

Within the sshd_config file, add the following configurations, specific to PowerShell 7. Once saved and configured, make sure to run the command Restart-Service -Name ‘sshd’ to restart the SSH server. 
# Make sure that the subsystem line goes after the existing SFTP subsystem line 
Subsystem powershell c:/progra~1/powershell/7/pwsh.exe -sshs -NoLogo -NoProfile 

# Change c:/progra~1/powershell/7/pwsh.exe to c:/progra~1/powershell/6/pwsh.exe for PowerShell Core 
PasswordAuthentication yes 

# Below is optional but recommended to allow use of public/private keys 
PubkeyAuthentication yes

Finally, restart the SSH server:

Restart-Service -Name 'sshd'

There is a bug in the OpenSSH server version included with Windows. It requires that 8.3 short names be used for any file paths, hence c:/progra~1. To verify that you are using the correct 8.3 short name, you can use the following command to retrieve this for Program Files (where PowerShell 6 or 7 is installed):

Get-CimInstance Win32_Directory -Filter 'Name="C:\\Program Files"' | Select-Object EightDotThreeFileName

Example Commands for PowerShell Remoting

So what can you do with PowerShell Remoting and how does it become useful? Many times a system administrator would need to collect information from a variety of systems or run a command on many at once to fix a problem or deploy a new package. With PowerShell Remoting this is easily done.

Gathering Information

In the below scenario, let’s connect remotely to a PowerShell 7 remote endpoint and get the running services.
$Params = @{ 
		"ComputerName" = 'Host1' 
		"ConfigurationName" = 'PowerShell.7' 
		"ScriptBlock" = { 
				Get-Service | Where-Object Status -EQ 'Running' | Format-Table -AutoSize 
				} 
		} 
Invoke-Command @Params

Running a Command

Perhaps we need to restart a service, in this case the Print Spooler.
$Params = @{ 
		"ComputerName" = 'Host1' 
		"ConfigurationName" = 'PowerShell.7' 
		"ScriptBlock" = { 
				Get-Service -Name 'Spooler' | Restart-Service 
				} 
		} 
Invoke-Command @Params

 

Conclusion

PowerShell Remoting is a powerful tool and with the addition of cross-platform capabilities and the use of optional SSH connections, it becomes an even more flexible and important tool for system administrators.
 

Related links

 

Related posts
4 min read

How to Leverage IT Automation for Maximum Efficiency

Nov 28, 2024 by Heiko Brenn

Are you ready for a transformation of your IT operations? Our brand-new white paper, Maximizing IT Automation: The...
9 min read

Automate VMware vSphere: Boost efficiency with PowerCLI

Nov 21, 2024 by Guy Leech

Perhaps it is because I began my professional coding career writing device drivers for Unix systems in C, back in the...
9 min read

Streamline data governance with PowerShell: What is Microsoft Purview for you?

Nov 20, 2024 by Damian Scoles

What is Microsoft Purview for you? Do you already master data governance with it? Learn how PowerShell simplifies...

About the author:

Adam Bertram

Adam is a 20+ year veteran of IT and experienced online business professional. He’s an entrepreneur, IT influencer, Microsoft MVP, blogger, trainer, author and content marketing writer for multiple technology companies.

Latest posts: