powershellscripts.com

Tutorials  PowerShell Cmdlet Help for New-PSSession



NAME
New-PSSession

SYNOPSIS
Creates a persistent connection to a local or remote computer.

SYNTAX
New-PSSession [[-ComputerName] ] [-ApplicationName ] [-Authentication {Default | Basic | Negotiat
e | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint ] [-Configurati
onName ] [-Credential ] [-Name ] [-Port ] [-SessionOption ] [
-UseSSL] [-ThrottleLimit ] []

New-PSSession [[-Session] ] [-Name ] [-ThrottleLimit ] []

New-PSSession [-ConnectionURI] [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | Negotiat
eWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint ] [-ConfigurationName ng>] [-Credential ] [-Name ] [-SessionOption ] [-ThrottleLimit ] [ mmonParameters>]


DESCRIPTION
The New-PSSession cmdlet creates a Windows PowerShell session (PSSession) on a local or remote computer. When you
create a PSSession, Windows 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 com
mands in a PSSession, use the Invoke-Command cmdlet. To use the PSSession to interact directly with a remote comput
er, use the Enter-PSSession cmdlet. For more information, see about_PSSessions.

You can run commands on a remote computer without creating a PSSession by using the ComputerName parameters of Ente
r-PSSession or Invoke-Command. When you use the ComputerName parameter, Windows PowerShell creates a temporary conn
ection that is used for the interactive session or for a single command and is then closed.


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 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 description of the SessionOption parameter, and see New-P
SSessionOption.

Required? false
Position? named
Default value
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.
For 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 more information about the values of this parameter, see the description of the System.Management.Automatio
n.Runspaces.AuthenticationMechanism enumeration in the MSDN (Microsoft Developer Network) library at http://go.
microsoft.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 Default
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
Creates a persistent connection (PSSession) to the specified computer. If you enter multiple computer names, Ne
w-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 spec
ify 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 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? false
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-ConfigurationName
Specifies 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 conf
iguration. If you specify only the configuration name, the following schema URI is prepended: http://schemas.m
icrosoft.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. The URI must be fully quali
fied.

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? true
Position? 1
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
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Name
Specifies a friendly name for the PSSession.

You can use the name to refer to the PSSession when using other cmdlets, such as Get-PSSession and Enter-PSSess
ion. The name is not required to be unique to the computer or the current session.

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

-Port
Specifies the network port on the remote computer that is used for this command. The default is port 80 (the H
TTP 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="<port-number>"}

Do not use the Port parameter unless you must. The port setting in the command applies to all computers and ses
sions in which the command runs. An alternate port setting might prevent the command from running on all comput
ers.

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

-Session
Uses the specified PSSession as a model for the new PSSession. This parameter creates new PSSessions with the s
ame 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-P
SSession or Get-PSSession command.

The resulting PSSessions have the same computer name, application name, connection URI, port, configuration nam
e, throttle limit, and Secure Sockets Layer (SSL) value as the originals, but they have a different display nam
e, ID, and instance ID (GUID).

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

-SessionOption
Sets 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 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

-ThrottleLimit
Specifies 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.

Required? false
Position? named
Default value 32
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, System.URI, System.Management.Automation.Runspaces.PSSession
You can pipe a ComputerName (string), ConnectionURI (URI), or Session (PSSession) object to New-PSSession.


OUTPUTS
System.Management.Automation.Runspaces.PSSession



NOTES


This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any
remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Re
quirements.

In Windows Vista and later versions of Windows, to create a PSSession on the local computer, you must start Win
dows PowerShell with the "Run as administrator" option.

When you are finished with the PSSession, use the Remove-PSSession cmdlet to delete the PSSession and release i
ts resources.


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

C:\PS>$s = new-pssession


Description
-----------
This command creates a new PSSession on the local computer and saves the PSSession in the $s variable.

You can now use this PSSession to run commands on the local computer.





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

C:\PS>$Server01 = new-pssession -ComputerName Server01


Description
-----------
This command creates a new PSSession on the Server01 computer and saves it in the $Server01 variable.

When creating multiple PSSessions, assign them to variables with useful names. This will help you manage the PSSess
ions in subsequent commands.





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

C:\PS>$s1, $s2, $s3 = new-session -computername server1,server2,server3


Description
-----------
This command creates three new PSSessions, one on each of the computers specified by the ComputerName parameter.

The command uses the assignment operator (=) to assign the new PSSessions to an array of variables: $s1, $s2, $s3.
It assigns the Server01 PSSession to $s1, the Server02 PSSession to $s2, and the Server03 PSSession to $s3.

When you assign multiple objects to an array of variables, Windows PowerShell assigns each object to a variable in
the array respectively. If there are more objects than variables, all remaining objects are assigned to the last va
riable. If there are more variables than objects, the remaining variables are empty (null).





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

C:\PS>new-pssession -computername Server01 -port 8081 -useSSL -ConfigurationName E12


Description
-----------
This command creates a new PSSession on the Server01 computer that connects to server port 8081 and uses the SSL pr
otocol. The new PSSession uses an alternate session configuration called "E12".

Before setting the port, you must configure the WinRM listener on the remote computer to listen on port 8081. For m
ore information, see the description of the Port parameter.





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

C:\PS>new-pssession -session $s -credential domain01\user01


Description
-----------
This command creates a new PSSession with the same properties as an existing PSSession. You can use this command fo
rmat when the resources of an existing PSSession are exhausted and a new PSSession is needed to offload some of the
demand.

The command uses the Session parameter of New-PSSession to specify the PSSession saved in the $s variable. It uses
the credentials of the Domain1\Admin01 user to complete the command.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>$global:s = new-pssession -computername server1.domain44.corpnet.fabrikam.com -credential domain01\admin01


Description
-----------
This example shows how to create a PSSession with a global scope on a computer in a different domain.

By default, PSSessions created at the command line are created with local scope and PSSessions created in a script
have script scope.

To create a PSSession with global scope, create a new PSSession and then store the PSSession in a variable that is
cast to a global scope. In this case, the $s variable is cast to a global scope.

The command uses the ComputerName parameter to specify the remote computer. Because the computer is in a different
domain than the user account, the full name of the computer is specified along with the credentials of the user.





-------------------------- EXAMPLE 7 --------------------------

C:\PS>$rs = get-content c:\test\servers.txt | new-PSsession -throttleLimit 50


Description
-----------
This command creates a PSSession on each of the 200 computers listed in the Servers.txt file and it stores the resu
lting PSSession in the $rs variable. The PSSessions have a throttle limit of 50.

You can use this command format when the names of computers are stored in a database, spreadsheet, text file, or ot
her text-convertible format.





-------------------------- EXAMPLE 8 --------------------------

C:\PS>$s = new-PSSession -URI http://Server01:91/NewSession -credential domain01\user01


Description
-----------
This command creates a PSSession on the Server01 computer and stores it in the $s variable. It uses the URI paramet
er to specify the transport protocol, the remote computer, the port, and an alternate session configuration. It als
o uses the Credential parameter to specify a user account with permission to create a session on the remote compute
r.





-------------------------- EXAMPLE 9 --------------------------

C:\PS>$s = new-PSSession -computername (import-csv servers.csv) -credential domain01\admin01 -throttlelimit 16

C:\PS> invoke-command -session $s -scriptblock {get-process powershell} -AsJob


Description
-----------
These commands create a set of PSSessions and then run a background job in each of the PSSessions.

The first command creates a new PSSession on each of the computers listed in the Servers.csv file. It uses the New-
PSSession cmdlet to create the PSSession. The value of the ComputerName parameter is a command that uses the Import
-Csv cmdlet to import the Servers.csv file and read its contents.

The command uses the Credential parameter to create the PSSessions with the permission of a domain administrator, a
nd it uses the ThrottleLimit parameter to limit the command to 16 concurrent connections. The command saves the PSS
essions in the $s variable.

The second command uses the AsJob parameter of Invoke-Command to start a background job that runs a "Get-Process Po
werShell" command in each of the PSSessions in $s.

For more information about background jobs, see about_Jobs and about_Remote_Jobs.





-------------------------- EXAMPLE 10 --------------------------

C:\PS>new-PSSession -ConnectionURI https://management.exchangelabs.com/Management


Description
-----------
This command creates a new PSSession that connects to a computer that is specified by a URI instead of a computer n
ame.





-------------------------- EXAMPLE 11 --------------------------

C:\PS>$so = New-WSManSessionOption -SkipCACheck

PS C:\> new-pssession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -credential
server01\admin01


Description
-----------
This example shows how to create and use a SessionOption parameter.

The first command uses the New-WSManSessionOption cmdlet to create a session option. It saves the resulting Session
Option object in the $so parameter.

The second command uses the option in a new session. The command uses the New-PSSession cmdlet to create a new sess
ion. The value of the SessionOption parameter is the SessionOption object in the $so variable.






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