Create a persistent connection to a local or remote computer.
Syntax
New-PSSession [[-ComputerName] string[]] [-ApplicationName string] [-Name string[]]
[-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint string] [-ConfigurationName string] [-Credential PSCredential] [-EnableNetworkAccess]
[-Port Int32] [-SessionOption PSSessionOption] [-ThrottleLimit Int32] [-UseSSL] [CommonParameters]
New-PSSession [-ConnectionUri] Uri[] [-AllowRedirection] [-Name string[]]
[-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}]
[-CertificateThumbprint string] [-ConfigurationName string] [-Credential PSCredential] [-EnableNetworkAccess]
[-SessionOption PSSessionOption] [-ThrottleLimit Int32] [CommonParameters]
New-PSSession [-VMId] Guid[] -Credential PSCredential [-ConfigurationName string][-Name string[]]
[-ThrottleLimit Int32] [CommonParameters]
New-PSSession -VMName string[] -Credential PSCredential [-ConfigurationName string] [-Name string[]]
[-ThrottleLimit Int32][CommonParameters]
New-PSSession -ContainerId String[] [-ConfigurationName string] [-Name string[]] [-RunAsAdministrator]
[-ThrottleLimit Int32] [CommonParameters]
New-PSSession [[-Session] PSSession[]] [-EnableNetworkAccess] [-Name string[]]
[-ThrottleLimit Int32] [CommonParameters]
Key
-AllowRedirection
Allow redirection of this connection to an alternate Uniform Resource Identifier (URI).
By default, PowerShell does not redirect connections.
To also limit the number of times that the connection is redirected, set the
MaximumConnectionRedirectionCount property of the $PSSessionOption preference variable, or
the MaximumConnectionRedirectionCount property of the value of the SessionOption parameter.
The default value is 5.
For more information, see the description of the SessionOption parameter, and see New-PSSessionOption.
-ApplicationName string
The application name segment of the connection URI.
Use this to specify the application name when you are not using -ConnectionURI.
The default value is the value of the $PSSessionApplicationName preference variable on
the local computer. If this preference variable is not defined, the default value is "WSMAN".
This value is appropriate for most uses. For more see about_Preference_Variables.
The WinRM service uses the application name to select a listener to service the connection
request. This name should match the URLPrefix property of a listener on the remote computer.
-Authentication AuthenticationMechanism
The mechanism used to authenticate the user's credentials:
Default | Basic | Negotiate | NegotiateWithImplicitCredential | CredSSP | Digest | Kerberos
The default value is "Default".
CredSSP authentication is available only in Windows Vista and later versions of Windows.
For more information about the values of this parameter, see docs.Microsoft.com
Caution: Credential Security Service 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.
-CertificateThumbprint string
The digital public key certificate (X509) of a user account that has permission
to perform 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 thumbprint, use the Get-Item or Get-ChildItem
command in the PowerShell Cert: drive.
-ComputerName string[]
An array of one or more computer names. Creates a persistent connection (PSSession) to
the specified computer(s). If you enter multiple computer names, New-PSSession creates
multiple PSSessions, one for each computer. 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. To specify the local computer, type the computer name,
"localhost", or a dot (.).
When the computer is in a different domain than the user, the fully qualified
domain name is required. You can also pipe a computer name (in quotes) to New-PSSession.
To use an IP address in the value of the ComputerName parameter, the command
must include the Credential parameter. 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.
To include the local computer in the value of the -ComputerName parameter, you must
start PowerShell with the "Run as administrator" option.
-ConfigurationName string
The session configuration that is used for the new PSSession.
Enter a configuration name or the fully qualified resource Uniform Resource
Identifier (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 configuration 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_Preference_Variables.
-ConnectionURI Uri[]
A Uniform Resource Identifier (URI) that defines the connection endpoint.
The URI must be fully qualified.
The format of this string is as follows:
Transport://ComputerName:Port/ApplicationName
The default value is as follows:
http://localhost:5985/WSMAN
Valid values for the Transport segment of the URI are HTTP and HTTPS.
If you do not specify a ConnectionURI, you can use the UseSSL, ComputerName,
Port, and ApplicationName parameters to specify the URI values.
If you specify a connection URI with a Transport segment, but do not specify a port,
the session is created with standards 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, PowerShell will prevent
the redirection unless you use -AllowRedirection in the command.
-ContainerId String[]
An array of IDs of containers. New-PSSession will start an interactive session with each
of the specified containers. To see the containers that are available, use Get-Container.
-Credential PSCredential
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, such as one returned by Get-Credential.
When you type a user name, you will be prompted for a password.
-EnableNetworkAccess []
Add an interactive security token to loopback sessions. The interactive token lets you
run commands in the loopback session that get data from other computers. For example,
you can run a command in the session that copies XML files from a remote computer to the local computer.
A loopback session is a PSSession that originates and ends on the same computer. To create a loopback session,
omit the ComputerName parameter or set its value to dot (.), localhost, or the name of the local computer.
By default, this cmdlet creates loopback sessions by using a network token, which might not provide sufficient
permission to authenticate to remote computers.
The EnableNetworkAccess parameter is effective only in loopback sessions. If you use EnableNetworkAccess when
you create a session on a remote computer, the command succeeds, but the parameter is ignored.
You can also enable remote access in a loopback session by using the CredSSP value of the Authentication
parameter, which delegates the session credentials to other computers.
To protect the computer from malicious access, disconnected loopback sessions that have interactive tokens,
which are those created by using the EnableNetworkAccess parameter, can be reconnected only from the computer
on which the session was created. Disconnected sessions that use CredSSP authentication can be reconnected
from other computers. For more information, see Disconnect-PSSession.
This parameter was introduced in PowerShell 3.0.
-Name string[]
A friendly name for the PSSession.
You can use this name to refer to the PSSession when using other cmdlets,
such as Get-PSSession and Enter-PSSession.
The name is not required to be unique to the computer or the current session.
-Port int32
The network port on the remote computer that is used for this command.
To connect to a remote computer, the remote computer must be listening on the port
that the connection uses. The default ports are 5985, which is the WinRM port for HTTP,
and 5986, which is the WinRM port for HTTPS.
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="port-number";}
Do not use the Port parameter unless you must. The port setting in the
command applies to all computers and sessions in which the command runs.
An alternate port setting might prevent the command from running on all computers.
-RunAsAdministrator
When you use the -ConnectionURI parameter, the remote destination can return an instruction to redirect to a
different URI. By default, PowerShell does not redirect connections, but you can use this parameter to
enable 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 of the
New-PSSessionOption cmdlet or set the MaximumConnectionRedirectionCount property of the $PSSessionOption
preference variable. The default value is 5.
-Session PSSession[]
Use the specified PSSession as a model for the new PSSession.
This parameter creates new PSSessions with the same properties as the specified PSSessions.
Enter a variable that contains the PSSessions or a command that creates or
gets the PSSessions, such as a New-PSSession or Get-PSSession command.
The resulting PSSessions have the same computer name, application name,
connection URI, port, configuration name, throttle limit, and Secure Sockets Layer (SSL)
value as the originals, but they have a different display name, ID, and instance ID (GUID).
-SessionOption PSSessionOption
Set advanced options for the session.
Enter a SessionOption object that you create by using the New-PSSession Option 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 information about the $PSSessionOption preference variable, see help about_Preference_Variables.
-ThrottleLimit int32
The maximum number of concurrent connections that can be established
to run this command. If you omit this parameter or enter a value of 0 (zero),
the default value, 32, is used.
The throttle limit applies only to the current command, not to the session or to the computer.
-UseSSL
Use 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 protection 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.
-VMId Guid[]
An array of virtual machines IDs. This cmdlet starts an interactive session with each of the
specified virtual machines. To see the virtual machines that are available to you, use:
`Get-VM | Select-Object -Property Name, ID`
-VMName String[]
An array of virtual machine names. This cmdlet starts an interactive session with each of the
specified virtual machines. To see the virtual machines that are available, use Get-VM cmdlet.
Standard Aliases for New-PSSession: nsn
New-PSSession creates a PowerShell session (PSSession) on a local or remote computer. When you
create a PSSession, PowerShell establishes a persistent connection to the remote computer.
Use a PSSession to run multiple commands that share data, such as a function or the value of a variable. To run commands in a PSSession, use Invoke-Command. To use the PSSession to interact directly with a remote computer, use Enter-PSSession . For more information, see help about_PSSessions.
You can run commands on a remote computer without creating a PSSession by using the -ComputerName parameter of Enter-PSSession or Invoke-Command. When you use -ComputerName , PowerShell creates a temporary connection that is used for the interactive session or for a single command and is then closed.
Create a new PSSession on the local computer and save the PSSession in the $sess variable:
PS C:> $sess = new-pssession
Create a new PSSession on Server64 and save it in the $s64 variable:
PS C:> $s64 = new-pssession -ComputerName Server64
Create a new PSSession on Server65 and server66 and save the sessions to 2 variables:
PS C:> $s65, $s66 = new-session -computername server65,server66
Create a new PSSession on Server64 and use the SSL protocol with an alternate session configuration called 'DBA1' then connect via server port 8081:
PS C:> new-pssession -computername Server64 -port 8081 -useSSL -ConfigurationName DBA1
Create a new PSSession with the same properties as an existing PSSession:
PS C:> new-pssession -session $s -credential domain01\user01
Create a PSSession calles $sess with a global scope on a computer in a different domain:
PS C:> $global:sess = new-pssession -computername server64.dom24.ss64.com -credential domain01\admin01
Create a PSSession on each of the 200 computers listed in the Servers.txt file and store the resulting PSSession in the $rs variable, this syntax can also be used with spreadsheets and databases:
PS C:> $rs = get-content c:\servers.txt | new-PSsession -throttleLimit 50
Create a PSSession and store it in the $sess variable, specify the transport protocol (http), the remote computer (Server64), the port (91), and an alternate session configuration:
PS C:> $sess = new-PSSession -URI http://Server64:91/NewSession -credential domain01\user01
Create a set of PSSessions and then run a background job in each:
PS C:> $sess = new-PSSession -computername (import-csv servers.csv) -credential domain01\admin01 -throttlelimit 16
PS C:> invoke-command -session $sess -scriptblock {get-process powershell} -AsJob
Create a new PSSession that connects to a computer specified with a URI:
PS C:> new-PSSession -ConnectionURI https://management.exchangelabs.com/Management
“We never fully grasp the import of any true statement until we have a clear notion of what the opposite untrue statement would be” ~ William James
Remove-PSSession - Close PowerShell session(s).
Enter-PSSession - Start an interactive session with a remote computer.
Export-PSSession - Import commands and save them in a PowerShell module.