Skip to content

Enter-PSSession - Fix example 7 description #9128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 16, 2022
Merged

Enter-PSSession - Fix example 7 description #9128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ee0bf8
Fix example 7 description
ClaudioESSilva Aug 16, 2022
da4f5c3
Editorial changes and copy to other versions
sdwheeler Aug 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 25 additions & 23 deletions reference/5.1/Microsoft.PowerShell.Core/Enter-PSSession.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: System.Management.Automation.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Core
ms.date: 05/15/2019
ms.date: 08/16/2022
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/enter-pssession?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Enter-PSSession
Expand Down Expand Up @@ -108,8 +108,10 @@ session as text.

The first command uses the `Enter-PSSession` cmdlet to start an interactive session with Server01, a
remote computer. When the session starts, the command prompt changes to include the computer name.
The second command gets the Windows PowerShell process and redirects the output to the Process.txt
file. The command is submitted to the remote computer, and the file is saved on the remote computer.

The second command gets the PowerShell process and redirects the output to the Process.txt file. The
command is submitted to the remote computer, and the file is saved on the remote computer.

The third command uses the **Exit** keyword to end the interactive session and close the connection.
The fourth command confirms that the Process.txt file is on the remote computer. A `Get-ChildItem`
("dir") command on the local computer cannot find the file.
Expand Down Expand Up @@ -137,7 +139,7 @@ PS C:\> Enter-PSSession -Session $s
```

These commands use the **Session** parameter of `Enter-PSSession` to run the interactive session in
an existing Windows PowerShell session (**PSSession**).
an existing PowerShell session (**PSSession**).

### Example 4: Start an interactive session and specify the Port and Credential parameters

Expand Down Expand Up @@ -172,8 +174,8 @@ Allows redirection of this connection to an alternate Uniform Resource Identifie
redirection is not allowed.

When you use the **ConnectionURI** parameter, the remote destination can return an instruction to
redirect to a different URI. By default, Windows PowerShell does not redirect connections, but you
can use this parameter to allow it to redirect the connection.
redirect to a different URI. By default, PowerShell does not redirect connections, but you can use
this parameter to allow it to redirect the connection.

You can also limit the number of times the connection is redirected by changing the
**MaximumConnectionRedirectionCount** session option value. Use the **MaximumRedirection** parameter
Expand All @@ -187,7 +189,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -239,11 +241,12 @@ of the Windows operating system.
For more information about the values of this parameter, see
[AuthenticationMechanism Enum](/dotnet/api/system.management.automation.runspaces.authenticationmechanism).

Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's
credentials are passed to a remote computer to be authenticated, is designed for commands that
require authentication on more than one resource, such as accessing a remote network share. This
mechanism increases the security risk of the remote operation. If the remote computer is
compromised, the credentials that are passed to it can be used to control the network session.
> [!CAUTION]
> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are
> passed to a remote computer to be authenticated, is designed for commands that require
> authentication on more than one resource, such as accessing a remote network share. This mechanism
> increases the security risk of the remote operation. If the remote computer is compromised, the
> credentials that are passed to it can be used to control the network session.

```yaml
Type: System.Management.Automation.Runspaces.AuthenticationMechanism
Expand All @@ -266,8 +269,7 @@ this action. Enter the certificate thumbprint of the certificate.
Certificates are used in client certificate-based authentication. They can be mapped only to local
user accounts; they do not work with domain accounts.

To get a certificate, use the `Get-Item` or `Get-ChildItem` command in the Windows PowerShell Cert:
drive.
To get a certificate, use the `Get-Item` or `Get-ChildItem` command in the PowerShell Cert: drive.

```yaml
Type: System.String
Expand Down Expand Up @@ -296,9 +298,9 @@ computer. For instructions for adding a computer name to the TrustedHosts list,
Computer to the Trusted Host List" in
[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md).

Note: In Windows Vista and later versions of the Windows operating system, to include the local
computer in the value of the **ComputerName** parameter, you must start Windows PowerShell with the
Run as administrator option.
> [!NOTE]
> On the Windows operating system, to include the local computer in the value of the
> **ComputerName** parameter, you must start PowerShell with the Run as administrator option.

```yaml
Type: System.String
Expand Down Expand Up @@ -355,11 +357,11 @@ and **ApplicationName** parameters to specify the **ConnectionURI** values.

Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection
URI with a Transport segment, but do not specify a port, the session is created by using standards
ports: 80 for HTTP and 443 for HTTPS. To use the default ports for Windows PowerShell remoting,
specify port 5985 for HTTP or 5986 for HTTPS.
ports: 80 for HTTP and 443 for HTTPS. To use the default ports for PowerShell remoting, specify port
5985 for HTTP or 5986 for HTTPS.

If the destination computer redirects the connection to a different URI, Windows PowerShell prevents
the redirection unless you use the **AllowRedirection** parameter in the command.
If the destination computer redirects the connection to a different URI, PowerShell prevents the
redirection unless you use the **AllowRedirection** parameter in the command.

```yaml
Type: System.Uri
Expand Down Expand Up @@ -556,7 +558,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -637,7 +639,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down
49 changes: 25 additions & 24 deletions reference/7.0/Microsoft.PowerShell.Core/Enter-PSSession.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: System.Management.Automation.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Core
ms.date: 07/23/2020
ms.date: 08/16/2022
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/enter-pssession?view=powershell-7&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Enter-PSSession
Expand Down Expand Up @@ -133,7 +133,7 @@ The fourth command confirms that the Process.txt file is on the remote computer.

```powershell
PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS>
[Server01]: PS C:\>
[Server01]: PS C:\> Get-Process PowerShell > C:\ps-test\Process.txt
[Server01]: PS C:\> exit
PS C:\>
Expand Down Expand Up @@ -188,18 +188,18 @@ PS> Enter-PSSession -HostName UserA@LinuxServer01
```

This example shows how to start an interactive session using Secure Shell (SSH). If SSH is
configured on the remote computer to prompt for passwords then you will get a password prompt.
Otherwise you will have to use SSH key based user authentication.
configured on the remote computer to use passwords then you are prompted to enter a password.
Otherwise, you must use key-based user authentication.

### Example 7: Start an interactive session using SSH and specify the Port and user authentication key
### Example 7: Start an interactive session using SSH with a port and user authentication key

```powershell
PS> Enter-PSSession -HostName UserA@LinuxServer02:22 -KeyFilePath c:\<path>\userAKey_rsa
PS> Enter-PSSession -HostName UserA@LinuxServer02:22 -KeyFilePath c:\sshkeys\userAKey_rsa
```

This example shows how to start an interactive session using SSH. It uses the **Port** parameter to
specify the port to use and the **KeyFilePath** parameter to specify an RSA key used to authenticate
the user on the remote computer.
This example shows how to start an interactive session using SSH. The username and SSH port number
are specified as parts of the value of the **HostName** parameter. The **KeyFilePath** parameter
specifies the location of an RSA key used to authenticate the user on the remote computer.

## PARAMETERS

Expand All @@ -224,7 +224,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -276,11 +276,12 @@ of the Windows operating system.
For more information about the values of this parameter, see
[AuthenticationMechanism Enum](/dotnet/api/system.management.automation.runspaces.authenticationmechanism).

Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's
credentials are passed to a remote computer to be authenticated, is designed for commands that
require authentication on more than one resource, such as accessing a remote network share. This
mechanism increases the security risk of the remote operation. If the remote computer is
compromised, the credentials that are passed to it can be used to control the network session.
> [!CAUTION]
> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are
> passed to a remote computer to be authenticated, is designed for commands that require
> authentication on more than one resource, such as accessing a remote network share. This mechanism
> increases the security risk of the remote operation. If the remote computer is compromised, the
> credentials that are passed to it can be used to control the network session.

```yaml
Type: System.Management.Automation.Runspaces.AuthenticationMechanism
Expand Down Expand Up @@ -332,9 +333,9 @@ computer. For instructions for adding a computer name to the TrustedHosts list,
Computer to the Trusted Host List" in
[about_Remote_Troubleshooting](About/about_Remote_Troubleshooting.md).

Note: In Windows Vista and later versions of the Windows operating system, to include the local
computer in the value of the **ComputerName** parameter, you must start PowerShell with the Run as
administrator option.
> [!NOTE]
> On the Windows operating system, to include the local computer in the value of the
> **ComputerName** parameter, you must start PowerShell with the Run as administrator option.

```yaml
Type: System.String
Expand Down Expand Up @@ -486,7 +487,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -653,7 +654,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -732,7 +733,7 @@ Accepted values: true

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand All @@ -754,7 +755,7 @@ Aliases:

Required: False
Position: Named
Default value: powershell
Default value: Powershell
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
```
Expand Down Expand Up @@ -809,7 +810,7 @@ Aliases:

Required: False
Position: Named
Default value: None
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```
Expand Down Expand Up @@ -892,7 +893,7 @@ is available. To cancel the `Enter-PSSession` command, press <kbd>CTRL</kbd>+<kb

The **HostName** parameter set was included starting with PowerShell 6.0. It was added to provide
PowerShell remoting based on Secure Shell (SSH). Both SSH and PowerShell are supported on multiple
platforms (Windows, Linux, macOS) and PowerShell remoting will work over these platforms where
platforms (Windows, Linux, macOS) and PowerShell remoting works over these platforms where
PowerShell and SSH are installed and configured. This is separate from the previous Windows only
remoting that is based on WinRM and much of the WinRM specific features and limitations do not
apply. For example, WinRM based quotas, session options, custom endpoint configuration, and
Expand Down
Loading