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).
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).
Fig. 2: Enabling WinRM PowerShell Remoting in 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.
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).
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_configWithin 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 EightDotThreeFileNameExample 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
About the author:
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.