diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index b06620c47ee2..88a054571818 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -25,6 +25,21 @@ "redirect_url": "/powershell/scripting/discover-powershell", "source_path": "reference/docs-conceptual/learn/tutorials/01-discover-powershell.md" }, + { + "redirect_document_id": true, + "redirect_url": "/powershell/scripting/learn/remoting/wsman-remoting-in-powershell", + "source_path": "reference/docs-conceptual/learn/remoting/wsman-remoting-in-powershell-core.md" + }, + { + "redirect_document_id": true, + "redirect_url": "/powershell/scripting/learn/remoting/ssh-remoting-in-powershell", + "source_path": "reference/docs-conceptual/learn/remoting/ssh-remoting-in-powershell-core.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/learn/remoting/wsman-remoting-in-powershell", + "source_path": "reference/docs-conceptual/learn/remoting/wsman-unsupported-for-nonwindows.md" + }, { "redirect_document_id": false, "redirect_url": "/powershell/utility-modules/platyps/create-help-using-platyps", diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Modes.md index d3a7fa6f31c9..20a3af780a01 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -1,7 +1,7 @@ --- description: Explains language modes and their effect on PowerShell sessions. Locale: en-US -ms.date: 06/07/2023 +ms.date: 10/04/2023 no-loc: [FullLanguage, ConstrainedLanguage, RestrictedLanguage, NoLanguage] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_modes?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -153,15 +153,15 @@ versions of Windows. ### RestrictedLanguage mode -The `RestrictedLanguage` mode was created for Windows RT, which is no longer -supported. This mode is also used to process modules manifests loaded by -`Import-Module`. - In `RestrictedLanguage` mode, users can run commands (cmdlets, functions, CIM -commands, and workflows), but can't use script blocks. +commands, and workflows), but can't use script blocks. This mode is also used +to process modules manifests loaded by `Import-Module`. + +Beginning in PowerShell 7.2, the `New-Object` cmdlet is disabled in +`RestrictedLanguage` mode when system lockdown is configured. -By default, only the following variables are permitted in -`RestrictedLanguage` mode: +By default, only the following variables are permitted in `RestrictedLanguage` +mode: - `$PSCulture` - `$PSUICulture` diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Language_Modes.md index 5e989c39ce79..6bcf220bb8e7 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -1,7 +1,7 @@ --- description: Explains language modes and their effect on PowerShell sessions. Locale: en-US -ms.date: 06/07/2023 +ms.date: 10/04/2023 no-loc: [FullLanguage, ConstrainedLanguage, RestrictedLanguage, NoLanguage] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_modes?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -153,18 +153,15 @@ versions of Windows. ### RestrictedLanguage mode -The `RestrictedLanguage` mode was created for Windows RT, which is no longer -supported. This mode is also used to process modules manifests loaded by -`Import-Module`. - In `RestrictedLanguage` mode, users can run commands (cmdlets, functions, CIM -commands, and workflows), but can't use script blocks. +commands, and workflows), but can't use script blocks. This mode is also used +to process modules manifests loaded by `Import-Module`. Beginning in PowerShell 7.2, the `New-Object` cmdlet is disabled in `RestrictedLanguage` mode when system lockdown is configured. -By default, only the following variables are permitted in -`RestrictedLanguage` mode: +By default, only the following variables are permitted in `RestrictedLanguage` +mode: - `$PSCulture` - `$PSUICulture` diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Language_Modes.md index 1d8478eddb58..e5ce4b866ae9 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -1,7 +1,7 @@ --- description: Explains language modes and their effect on PowerShell sessions. Locale: en-US -ms.date: 06/07/2023 +ms.date: 10/04/2023 no-loc: [FullLanguage, ConstrainedLanguage, RestrictedLanguage, NoLanguage] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_modes?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -156,18 +156,15 @@ versions of Windows. ### RestrictedLanguage mode -The `RestrictedLanguage` mode was created for Windows RT, which is no longer -supported. This mode is also used to process modules manifests loaded by -`Import-Module`. - In `RestrictedLanguage` mode, users can run commands (cmdlets, functions, CIM -commands, and workflows), but can't use script blocks. +commands, and workflows), but can't use script blocks. This mode is also used +to process modules manifests loaded by `Import-Module`. Beginning in PowerShell 7.2, the `New-Object` cmdlet is disabled in `RestrictedLanguage` mode when system lockdown is configured. -By default, only the following variables are permitted in -`RestrictedLanguage` mode: +By default, only the following variables are permitted in `RestrictedLanguage` +mode: - `$PSCulture` - `$PSUICulture` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Modes.md index c6d63021ecee..b5373d9d0e17 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -1,7 +1,7 @@ --- description: Explains language modes and their effect on PowerShell sessions. Locale: en-US -ms.date: 06/07/2023 +ms.date: 10/04/2023 no-loc: [FullLanguage, ConstrainedLanguage, RestrictedLanguage, NoLanguage] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_modes?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -156,18 +156,15 @@ versions of Windows. ### RestrictedLanguage mode -The `RestrictedLanguage` mode was created for Windows RT, which is no longer -supported. This mode is also used to process modules manifests loaded by -`Import-Module`. - In `RestrictedLanguage` mode, users can run commands (cmdlets, functions, CIM -commands, and workflows), but can't use script blocks. +commands, and workflows), but can't use script blocks. This mode is also used +to process modules manifests loaded by `Import-Module`. Beginning in PowerShell 7.2, the `New-Object` cmdlet is disabled in `RestrictedLanguage` mode when system lockdown is configured. -By default, only the following variables are permitted in -`RestrictedLanguage` mode: +By default, only the following variables are permitted in `RestrictedLanguage` +mode: - `$PSCulture` - `$PSUICulture` diff --git a/reference/docs-conceptual/learn/remoting/SSH-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/learn/remoting/SSH-Remoting-in-PowerShell.md similarity index 100% rename from reference/docs-conceptual/learn/remoting/SSH-Remoting-in-PowerShell-Core.md rename to reference/docs-conceptual/learn/remoting/SSH-Remoting-in-PowerShell.md diff --git a/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell-Core.md deleted file mode 100644 index 116cfc4efef4..000000000000 --- a/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell-Core.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: Remoting in PowerShell using WSMan -ms.date: 11/16/2022 -title: WS-Management (WSMan) Remoting in PowerShell ---- -# WS-Management (WSMan) Remoting in PowerShell - -## Instructions to Create a Remoting Endpoint - -The PowerShell package for Windows includes a WinRM plug-in (`pwrshplugin.dll`) and an installation -script (`Install-PowerShellRemoting.ps1`) in `$PSHome`. These files enable PowerShell to accept -incoming PowerShell remote connections when its endpoint is specified. - -### Motivation - -An installation of PowerShell can establish PowerShell sessions to remote computers using -`New-PSSession` and `Enter-PSSession`. To enable it to accept incoming PowerShell remote -connections, the user must create a WinRM remoting endpoint. This is an explicit opt-in scenario -where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint. The installation -script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to -perform the same action. For more details, please see issue [#1193][01]. - -### Script Actions - -The script - -1. Creates a directory for the plug-in within `$env:windir\System32\PowerShell` -1. Copies pwrshplugin.dll to that location -1. Generates a configuration file -1. Registers that plug-in with WinRM - -### Registration - -The script must be executed within an Administrator-level PowerShell session and runs in two modes. - -#### Executed by the instance of PowerShell that it will register - -```powershell -Install-PowerShellRemoting.ps1 -``` - -#### Executed by another instance of PowerShell on behalf of the instance that it will register - -```powershell -\Install-PowerShellRemoting.ps1 -PowerShellHome "" -``` - -For Example: - -```powershell -Set-Location -Path 'C:\Program Files\PowerShell\6.0.0\' -.\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0\" -``` - -> [!NOTE] -> The remoting registration script restarts WinRM. All existing PSRP sessions are terminated -> immediately after the script is run. If run during a remote session, the script terminates the -> connection. - -## How to Connect to the New Endpoint - -Create a PowerShell session to the new PowerShell endpoint by specifying -`-ConfigurationName "some endpoint name"`. To connect to the PowerShell instance from the example -above, use either: - -```powershell -New-PSSession ... -ConfigurationName "powershell.6.0.0" -Enter-PSSession ... -ConfigurationName "powershell.6.0.0" -``` - -Note that `New-PSSession` and `Enter-PSSession` invocations that don't specify `-ConfigurationName` -will target the default PowerShell endpoint, `microsoft.powershell`. - - -[01]: https://github.com/PowerShell/PowerShell/issues/1193 diff --git a/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell.md b/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell.md new file mode 100644 index 000000000000..28f9a0c5c494 --- /dev/null +++ b/reference/docs-conceptual/learn/remoting/WSMan-Remoting-in-PowerShell.md @@ -0,0 +1,63 @@ +--- +description: Remoting in PowerShell using WSMan +ms.date: 10/03/2023 +title: Using WS-Management (WSMan) Remoting in PowerShell +--- +# Using WS-Management (WSMan) Remoting in PowerShell + +## Enabling PowerShell remoting + +To enable PowerShell remoting run the `Enable-PSRemoting` cmdlet in an elevated PowerShell session. +Running `Enable-PSRemoting` configures a remoting endpoint for the specific installation version +that you are running the cmdlet in. For example, when you run `Enable-PSRemoting` while running +PowerShell 7.3, PowerShell creates a remoting endpoint runs PowerShell 7.3. If you run +`Enable-PSRemoting` while running PowerShell 7-preview, PowerShell creates a remoting endpoint that +runs PowerShell 7-preview. You can create multiple remoting endpoints for different versions of that +run side-by-side. + +Running `Enable-PSRemoting` creates two endpoints for that version. + +- One has a simple name corresponding to the PowerShell major version. that hosts the session. For + example, **PowerShell.7.3**. +- The other configuration name contains the full version number. For example, **PowerShell.7.3.7**. + +You can connect to the latest version of PowerShell 7 host version using the simple name, +**PowerShell.7.3**. You can connect to a specific version of PowerShell using the longer, +version-specific name. + +Use the **ConfigurationName** parameter with the `New-PSSession` and `Enter-PSSession` cmdlets to +connect to a named configuration. + +## WSMan remoting isn't supported on non-Windows platforms + +Since the release of PowerShell 6, support for remoting over WS-Management (WSMan) on non-Windows +platforms has only been available to a limited set of Linux distributions. All versions of those +distributions that supported WSMan are no longer supported by the Linux vendors that created them. + +On non-Windows, WSMan relied on the [Open Management Infrastructure (OMI)][01] project, which no +longer supports PowerShell remoting. The OMI WSMan client is dependent on **OpenSSL 1.0**. Most +Linux distributions have moved to **OpenSSL 2.0**, which isn't backward-compatible. At this time, +there is no supported distribution that has the dependencies needed for the OMI WSMan client to +work. + +The outdated libraries and supporting code have been removed for non-Windows platforms. WSMan-based +remoting is still supported between Windows systems. Remoting over SSH is supported for all +platforms. For more information, see [PowerShell remoting over SSH][03]. + +> [!NOTE] +> Users may be able to get WSMan remoting to work using the [PSWSMan][02] module. This module isn't +> supported or maintained by Microsoft. + +## Further reading + +- [Enable-PSRemoting][04] +- [Enter-PSSession][05] +- [New-PSSession][06] + + +[01]: https://github.com/Microsoft/omi +[02]: https://www.powershellgallery.com/packages/PSWSMan +[03]: SSH-Remoting-in-PowerShell.md +[04]: xref:Microsoft.PowerShell.Core.Enable-PSRemoting +[05]: xref:Microsoft.PowerShell.Core.Enter-PSSession +[06]: xref:Microsoft.PowerShell.Core.New-PSSession diff --git a/reference/docs-conceptual/learn/remoting/wsman-unsupported-for-nonwindows.md b/reference/docs-conceptual/learn/remoting/wsman-unsupported-for-nonwindows.md deleted file mode 100644 index 66299fdf4161..000000000000 --- a/reference/docs-conceptual/learn/remoting/wsman-unsupported-for-nonwindows.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: This article is explains the support policy for WSMan-based remoting on non-Windows platforms. -ms.date: 06/28/2023 -title: WSMan remoting is not supported on non-Windows platforms ---- -# WSMan remoting is not supported on non-Windows platforms - -Since the release of PowerShell 6, support for remoting over WS-Management (WSMan) on non-Windows -platforms has only been available to a limited set of Linux distributions. All versions of those -distributions that supported WSMan are no longer supported by the Linux vendors that created them. - -On non-Windows, WSMan relied on the [Open Management Infrastructure (OMI)][01] project, which no -longer supports PowerShell remoting. The OMI WSMan client is dependent on **OpenSSL 1.0**. Most -Linux distributions have moved to **OpenSSL 2.0**, which is not backward-compatible. At this time, -there is no supported distribution that has the dependencies needed for the OMI WSMan client to -work. - -Our plan for PowerShell 7.3 is to remove outdated libraries and supporting code for non-Windows -platforms. WSMan-based remoting is still supported between Windows systems. Remoting over SSH is -supported for all platforms. For more information, see [PowerShell remoting over SSH][03]. - -> [!NOTE] -> Users may be able to get WSMan remoting to work using the [PSWSMan][02] module. This module is not -> supported or maintained by Microsoft. - - -[01]: https://github.com/Microsoft/omi -[02]: https://www.powershellgallery.com/packages/PSWSMan -[03]: SSH-Remoting-in-PowerShell-Core.md diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 676567696956..cab4b492b861 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -219,11 +219,9 @@ items: - name: Running remote commands href: learn/remoting/running-remote-commands.md - name: PowerShell remoting over SSH - href: learn/remoting/ssh-remoting-in-powershell-core.md - - name: WS-Management (WSMan) remoting in PowerShell Core - href: learn/remoting/wsman-remoting-in-powershell-core.md - - name: WSMan remoting is not supported on non-Windows platforms - href: learn/remoting/wsman-unsupported-for-nonwindows.md + href: learn/remoting/ssh-remoting-in-powershell.md + - name: WS-Management (WSMan) remoting in PowerShell + href: learn/remoting/wsman-remoting-in-powershell.md - name: WinRM Security href: learn/remoting/winrmsecurity.md - name: Making the second hop in PowerShell Remoting