powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Enter-PSSession



NAME
Enter-PSSession

SYNOPSIS
Starts an interactive session with a remote computer.

SYNTAX
Enter-PSSession [-ComputerName] [-ApplicationName ] [-Authentication {Default | Basic | Negotiate
| NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint ] [-Configuration
Name ] [-Credential ] [-Port ] [-SessionOption ] [-UseSSL] [ meters>]

Enter-PSSession [[-Id] ] []

Enter-PSSession [-InstanceId ] []

Enter-PSSession [-Name ] []

Enter-PSSession [[-Session] ] []

Enter-PSSession [[-ConnectionURI] ] [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | Negoti
ateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint ] [-ConfigurationName ring>] [-Credential ] [-SessionOption ] []


DESCRIPTION
The Enter-PSSession cmdlet starts an interactive session with a single remote computer. During the session, the com
mands that you type run on the remote computer, just as though you were typing directly on the remote computer. You
can have only one interactive session at a time.

Typically, you use the ComputerName parameter to specify the name of the remote computer. However, you can also use
a session that you create by using New-PSSession for the interactive session.

To end the interactive session and disconnect from the remote computer, use the Exit-PSSession cmdlet, or type "exi
t".


PARAMETERS
-AllowRedirection []
Allows redirection of this connection to an alternate Uniform Resource Identifier (URI).

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

Allows redirection of this connection to an alternate URI.

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

You can also limit the number of times that the connection is redirected by setting the MaximumConnectionRedire
ctionCount property of the $PSSessionOption preference variable, or the MaximumConnectionRedirectionCount prope
rty of the value of the SessionOption parameter. The default value is 5. For more information, see the descript
ion of the SessionOption parameter, and see New-PSSessionOption.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-ApplicationName
Specifies the application name segment of the connection URI. Use this parameter to specify the application nam
e when you are not using the ConnectionURI parameter in the command.

The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If t
his preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. Fo
r more information, see about_Preference_Variables.

The WinRM service uses the application name to select a listener to service the connection request. The value o
f this parameter should match the value of the URLPrefix property of a listener on the remote computer.

Required? false
Position? named
Default value WSMAN
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Authentication
Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Bas
ic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". The default value is
"Default".

CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of Windows.

For information about the values of this parameter, see the description of the System.Management.Automation.Run
spaces.AuthenticationMechanism enumeration in the MSDN (Microsoft Developer Network) library at http://go.micro
soft.com/fwlink/?LinkId=144382.

Caution: Credential Security Service Provider (CredSSP) authentication, in which the user's credentials are pas
sed 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 remo
te operation. If the remote computer is compromised, the credentials that are passed to it can be used to contr
ol the network session.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-CertificateThumbprint
Specifies the digital public key certificate (X509) of a user account that has permission to perform this actio
n. Enter the certificate thumbprint of the certificate.

Certificates are used in client certificate-based authentication. They can be mapped only to local user account
s; they do not work with domain accounts.

To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: driv
e.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ComputerName
Starts an interactive session with the specified remote computer. Enter only one computer name. The default is
the local computer.

Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more remote computers. You can
also pipe a computer name to Enter-PSSession.

To use an IP address in the value of the ComputerName parameter, the command must include the Credential parame
ter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be
included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to
the TrustedHosts list, see "How to Add a Computer to the Trusted Host List" in about_Remote_Troubleshooting.

Note: In Windows Vista and later versions of Windows, to include the local computer in the value of the Comput
erName parameter, you must start Windows PowerShell with the "Run as administrator" option.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-ConfigurationName
Specifies the session configuration that is used for the interactive session.

Enter a configuration name or the fully qualified resource URI for a session configuration. If you specify only
the configuration name, the following schema URI is prepended: http://schemas.microsoft.com/powershell.

The session configuration for a session is located on the remote computer. If the specified session configurati
on does not exist on the remote computer, the command fails.

The default value is the value of the $PSSessionConfigurationName preference variable on the local computer. If
this preference variable is not set, the default is Microsoft.PowerShell. For more information, see about_Pref
erence_Variables.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-ConnectionURI
Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the interactive session.
The URI must be fully qualified.

The format of this string is as follows:
://:/

The default value is as follows:
http://localhost:80/WSMAN

Valid values for the Transport segment of the URI are HTTP and HTTPS. If you do not specify a ConnectionURI, yo
u can use the UseSSL, ComputerName, Port, and ApplicationName parameters to specify the URI values.

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

Required? false
Position? 2
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Credential
Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as "User01", "Domain01\User01", or "User@Domain.com", or enter a PSCredential object, su
ch as one returned by the Get-Credential cmdlet.

When you type a user name, you will be prompted for a password.

Required? false
Position? named
Default value Current user
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Id
Specifies the ID of an existing session. Enter-PSSession uses the specified session for the interactive session
.

To find the ID of a session, use the Get-PSSession cmdlet.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-InstanceId
Specifies the instance ID of an existing session. Enter-PSSession uses the specified session for the interactiv
e session.

The instance ID is a GUID. To find the instance ID of a session, use the Get-PSSession cmdlet. You can also use
the Session, Name, or ID parameters to specify an existing session. Or, you can use the ComputerName paramete
r to start a temporary session.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Name
Specifies the friendly name of an existing session. Enter-PSSession uses the specified session for the interact
ive session.

If the name that you specify matches more than one session, the command fails. You can also use the Session, In
stanceID, or ID parameters to specify an existing session. Or, you can use the ComputerName parameter to start
a temporary session.

To establish a friendly name for a session, use the Name parameter of the New-PSSession cmdlet.

Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Port
Specifies the network port on the remote computer used for this command. The default is port 80 (the HTTP port
).

Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that
port. Use the following commands to configure the listener:

1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port=""}

Do not use the Port parameter unless you must. The port setting in the command applies to all computers or sess
ions on which the command runs. An alternate port setting might prevent the command from running on all compute
rs.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Session
Specifies a Windows PowerShell session (PSSession) to use for the interactive session. This parameter takes a s
ession object. You can also use the Name, InstanceID, or ID parameters to specify a PSSession.

Enter a variable that contains a session object or a command that creates or gets a session object, such as a N
ew-PSSession or Get-PSSession command. You can also pipe a session object to Enter-PSSession. You can submit on
ly one PSSession with this parameter. If you enter a variable that contains more than one PSSession, the comman
d fails.

When you use Exit-PSSession or the EXIT keyword, the interactive session ends, but the PSSession that you creat
ed remains open and available for use.

Required? false
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? true

-SessionOption
Sets advanced options for the session. Enter a SessionOption object that you create by using the New-PSSessionO
ption cmdlet.

The default values for the options are determined by the value of the $PSSessionOption preference variable, if
it is set. Otherwise, the session uses the system defaults.

For a description of the session options, including the default values, see New-PSSessionOption. For informatio
n about the $PSSessionOption preference variable, see about_Preference_Variables.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-UseSSL []
Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL
is not used.

WS-Management encrypts all Windows PowerShell content transmitted over the network. UseSSL is an additional pro
tection that sends the data across an HTTPS connection instead of an HTTP connection.

If you use this parameter, but SSL is not available on the port used for the command, the command fails.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.String or System.Management.Automation.Runspaces.PSSession
You can pipe a computer name (a string) or a session object to Enter-PSSession.


OUTPUTS
None
The cmdlet does not return any output.


NOTES


-- To connect to a remote computer, you must be a member of the Administrators group on the remote computer.

-- In Windows Vista and later versions of Windows, to start an interactive session on the local computer, you m
ust start Windows PowerShell with the "Run as administrator" option.

-- When you use Enter-PSSession, your user profile on the remote computer is used for the interactive session.
The commands in the remote user profile, including commands to add Windows PowerShell snap-ins and to change th
e command prompt, run before the remote prompt is displayed.

-- Enter-PSSession uses the UI culture setting on the local computer for the interactive session. To find the l
ocal UI culture, use the $UICulture automatic variable.

-- Enter-PSSession requires the Get-Command, Out-Default, and Exit-PSSession cmdlets. If these cmdlets are not
included in the session configuration on the remote computer, the Enter-PSSession commands fails.

-- Unlike Invoke-Command, which parses and interprets the commands before sending them to the remote computer,
Enter-PSSession sends the commands directly to the remote computer without interpretation.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>Enter-PSSession

LocalHost\PS>


Description
-----------
This command starts an interactive session on the local computer. The command prompt changes to indicate that you a
re now running commands in a different session.

The commands that you enter run in the new session, and the results are returned to the default session as text.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>enter-pssession -computer Server01

Server01\PS> get-process powershell > C:\ps-test\process.txt

Server01\PS> exit-pssession
C:\PS>

C:\PS> dir C:\ps-test\process.txt
Get-ChildItem : Cannot find path 'C:\ps-test\process.txt' because it does not exist.
At line:1 char:4
+ dir <<<< c:\ps-test\process.txt


Description
-----------
This command shows how to work in an interactive session with a remote computer.

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 PowerShell process and redirects the output to the Process.txt file. The command is sub
mitted 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.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$s = new-pssession -computername Server01

C:\PS> Enter-PSSession -session $s

Server01\PS>


Description
-----------
These commands use the Session parameter of Enter-PSSession to run the interactive session in an existing Windows P
owerShell session (PSSession).





-------------------------- EXAMPLE 4 --------------------------

C:\PS>Enter-PSSession -computername Server01 -port 90 -credential domain01\user01

Server01\PS>


Description
-----------
This command starts an interactive session with the Server01 computer. It uses the Port parameter to specify the po
rt and the Credential parameter to specify the account of a user with permission to connect to the remote computer.





-------------------------- EXAMPLE 5 --------------------------

C:\PS>Enter-PSSession -computername Server01

Server01:\PS> Exit-PSSession

C:\PS>


Description
-----------
This example shows how to start and stop an interactive session. The first command uses the Enter-PSSession cmdlet
to start an interactive session with the Server01 computer.

The second command uses the Exit-PSSession cmdlet to end the session. You can also use the Exit keyword to end the
interactive session. Exit-PSSession and Exit have the same effect.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135210
about_PSSessions
about_Remote
New-PSSession
Get-PSSession
Exit-PSSession
Remove-PSSession
Invoke-Command