PowerShell remoting: Controlling what edition is being targeted (PowerShell Core or Windows PowerShell); the state of cross-platform remoting

Question

This self-answered question, which focuses on Windows^[1], addresses the following aspects:

Now that there are two PowerShell editions - the legacy, Windows-only Windows PowerShell and the cross-platform PowerShell Core, both may be installed on a given Windows machine:

• How can I tell which PowerShell edition will execute remote commands, such as via Invoke-Command -ComputerName?

• How can I target a specific edition, both ad hoc and persistently, through configuration?

Note:

For an edition to be targetable via remoting on a given machine, it must be set up for remoting:

• Only Windows PowerShell is automatically set up for remoting, but only on servers running Windows Server 2012 or higher.

• As of v7, PowerShell Core doesn't come with Windows yet; if you're using the official installer, you're given the option of enabling remoting during the installation.

In any event, you can use Enable-PSRemoting to (re-)enable PowerShell remoting on demand, which:

• must be run from the respective edition.

• must be run with administrative privileges

---

[1] That is, the question focuses on WinRM-based remoting (WinRM is a Windows-specific implementation of the DTMF WSMan (WS-Management) standard).

As for cross-platform remoting with PowerShell Core:

• You can already use SSH-based remoting, on all platforms:

  • Using SSH-based remoting involves mostly the same cmdlets as WinRM-based remoting, though the parameters involved differ; most notably, you specify the target computer(s) via the -HostName parameter rather than the -ComputerName parameter.

  • Limitations (as of v7): "SSH-based remoting doesn't currently support remote endpoint configuration and Just Enough Administration (JEA)."

• For Unix-to-Windows remoting (Unix referring to Unix-like platforms such as macOS and Linux) - that is, remoting into a Windows machine from a Unix-like machine - you can alternatively use WinRM-based remoting with additional configuration:

  • On the Windows machine:

    • SSL connections must be enabled by configuring WinRM for HTTPS.
    • The user accounts to be used from the Unix-like machines must be defined as local user accounts in the local Administrators group - domain accounts won't work.

  • The Unix-like machines must use the remoting cmdlets with the -Authentication Basic -UseSsl parameters.

  • See about_Remote_Requirements

• A Unix WSMan-based implementation is being worked on in the psl-omi-provider repository, which already enables Linux machines to act as remoting targets (that is, the server component is already usable - it's not clear to me whether it can also be installed on macOS); the client component, however, is not yet production-ready as of this writing.
  Once the client client component is available, uniform WSMan-based cross-platform remoting will be possible, both between Unix-like machines (Linux, macOS) and between Unix-like machines and Windows machines.

Answer 1

Note: Changing what remote endpoint PowerShell [Core] targets by default - which as of 7.0 is still Window PowerShell - is being considered: see this GitHub issue.

---

It is the locally specified remoting session configuration that determines what PowerShell edition, and possibly version, will be used on the remote machine:

• Ad hoc, you can use the -ConfigurationName parameter of remoting cmdlets such as Invoke-Command, New-PSSession, and Enter-PSSession to specify a session configuration explicitly.

• Persistently, via configuration, you can set the default session configuration via the $PSSessionConfigurationName preference variable (the linked help topic also dicusses other remote-session-related preference variables, namely $PSSessionApplicationName and $PSSessionOption)

  • By default, clients connect to session configuration microsoft.powershell on the remote machine (see below). Therefore, you can alternatively change the definition of this configuration on the remote target machine, but note that this means that all clients that use the defaults will use the redefined configuration - see bottom for how to achieve this redefinition.

On the target machine of a remoting operation, Get-PSSessionConfiguration cmdlet lists all registered session configurations that clients can use to connect to, and which you can manage with Register-PSSessionConfiguration and Unregister-PSSessionConfiguration:

• Caveat: Get-PSSessionConfiguration must be run in an elevated session (as administrator), and, due to a bug in Windows PowerShell 5.1, you may have to run the following dummy command first: $null = Get-Command Test-WSMan, so as to ensure that the wsman: drive is defined).

• Session configurations whose names are prefixed with 'microsoft.powershell' belong to Windows PowerShell.

• Prefix 'PowerShell.' refers to PowerShell Core.

$PSSessionConfigurationName defaults to 'http://schemas.microsoft.com/powershell/Microsoft.PowerShell' in both editions, which means that Windows PowerShell is by default targeted on remote machines even if you're running from PowerShell Core:

• The Microsoft.PowerShell part refers to the (64-bit) Windows PowerShell session configuration, as listed by Get-PSSessionConfiguration (in lowercase).

• The http://schemas.microsoft.com/powershell/ prefix is optional and can be omitted; note that using https: in the prefix does not work and will not automatically switch to an SSL-based transport; for the latter, explicit configuration is needed. Note that HTTPS/SSL-based remoting isn't necessary if all of your remoting happens within a Windows domain.

To target PowerShell Core (PowerShell v6+) on a remote machine:

• Generally, PowerShell Core session configurations are version-specific, and you have two choices:

  • Target a major PowerShell Core version - e.g., PowerShell.7 - using whatever the latest v7.x version is installed on the target machine.

    • This is preferable, because your code then doesn't require updating every time you install a patch or minor version update on the target machine.

  • Target a specific version - e.g., PowerShell.7.1.2

    • Do this only if you have multiple, side-by-side installations that share the same major version, and you explicitly need to target one of them.

  • Again, running Get-PSSessionConfiguration on the target machine, from an elevated session, tells you the names of all registered session configurations.

• To target PowerShell Core ad hoc, use -ConfigurationName PowerShell.7, for instance:

# Connect to computer $comp and make it execute $PSVersionTable 
# in PowerShell Core v7.x, which tells you what PowerShell edition 
# and version is running.
Invoke-Command -ComputerName $comp -ConfigurationName PowerShell.7 { $PSVersionTable }

• To target PowerShell Core by default, persistently, from a given client machine, add something like the following to your $PROFILE file:

# When remoting, default to running PowerShell Core v7.x on the
# the target machines:
$PSSessionConfigurationName = 'PowerShell.7'

• To have all clients of a given remote server machine target PowerShell Core by default, persistently, you must redefine the server's microsoft.powershell session configuration, which requires administrative privileges; you can adapt the following snippet:

# Run WITH ELEVATION (as administrator) and
# ONLY IF YOU UNDERSTAND THE IMPLICATIONS.

$ErrorActionPreference = 'Stop'

# The configuration whose definition you want to make the new default.
$newDefaultConfigSource = 'PowerShell.7'

# Standard registry locations and names.
$defaultConfigName = 'Microsoft.PowerShell'
$configXmlValueName = 'ConfigXml'
$configRootKey = 'registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Plugin'

# Rename the current default configuration XML to "ConfigXml.OLD" to keep a backup.
Rename-ItemProperty $configRootKey\$defaultConfigName $configXmlValueName -NewName "$configXmlValueName.OLD"

# Get the configuration XML from the configuration that should become the new default.
# Modify it to replace the source configuration name with the default configuration name.
$xmlText = (Get-ItemPropertyValue $configRootKey\$newDefaultConfigSource $configXmlValueName) -replace 
             ('\b{0}\b' -f [regex]::Escape($newDefaultConfigSource)), $defaultConfigName

# Save the modified XML as the default configuration's config XML.
Set-ItemProperty $configRootKey\$defaultConfigName $configXmlValueName $xmlText

# Restart the WinRM service for changes to take effect.
Restart-Service WinRM