This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers New-PSSession.
When to use New-PSSession?
The New-PSSession cmdlet 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 the Invoke-Command cmdlet. To use the PSSession to interact directly with a remote computer, use the Enter-PSSession cmdlet.
You can run commands on a remote computer without creating a PSSession by using the –ComputerName parameters of Enter-PSSession or Invoke-Command. When you use the –ComputerName parameter, PowerShell creates a temporary connection that is used for the command and is then closed.
Starting with PowerShell 6.0 you can use Secure Shell (SSH) to establish a connection to and create a session on a remote computer, if SSH is available on the local computer and the remote computer is configured with a PowerShell SSH endpoint. The benefit of an SSH based PowerShell remote session is that it can work across multiple platforms (Windows, Linux, macOS). For SSH based sessions you use the –HostName or –SSHConnection parameter set to specify the remote computer and relevant connection information.
NOTE: When using WSMan remoting from a Linux or macOS client with a HTTPS endpoint where the server certificate is not trusted (e.g., a self-signed certificate). You must provide a -PSSessionOption that includes -SkipCACheck and -SkipCNCheck to successfully establish the connection. Only do this if you are in an environment where you can be certain of the server certificate and the network connection to the target system.
What version of PowerShell am I using?
Get the PowerShell Version from your machine:
$PSVersionTable
This command shows you the PowerShell version information on your machine.
How to use New-PSSession ?
Create a session on a remote computer:
$ITPTV01 = New-PSSession -ComputerName ITPTV01
This command creates a new PSSession on the ITPTV01 computer and saves it in the $ITPTV01 variable.
When creating multiple PSSession objects, assign them to variables with useful names. This will help you manage the PSSession objects in subsequent commands.
Create sessions on multiple computers:
$s1, $s2, $s3 = New-PSSession -ComputerName ITPTV01,ITPROTV02,ITPtv03
This command creates three PSSession objects, one on each of the computers specified by the –ComputerName parameter.
The command uses the assignment operator (=) to assign the new PSSession objects to variables: $s1, $s2, $s3. It assigns the ITPTV01 PSSession to $s1, the ITPROTV02 PSSession to $s2, and the ITPtv03 PSSession to $s3.
NOTE: When you assign multiple objects to a series of variables, PowerShell assigns each object to a variable in the series respectively. If there are more objects than variables, all remaining objects are assigned to the last variable. If there are more variables than objects, the remaining variables are empty (null).
Create a session with a specified port:
New-PSSession -ComputerName ITPTV01 -Port 8081 -UseSSL
This command creates a new PSSession on the ITPTV01 computer that connects to server port 8081 and uses the SSL protocol.
Before setting the port, you must configure the WinRM listener on the remote computer to listen on port 8081.
Create a session with a global scope in a different domain:
$global:s = New-PSSession -ComputerName ITPTV1.ITPRO.TV -Credential ITPROTVPSHELL\Adam
By default, PSSession objects created at the command line are created with local scope and PSSession objects 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 together with the credentials of the user.
Create sessions for many computers:
$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50
This command creates a PSSession on each of the computers listed in the Servers.txt file and it stores the resulting PSSession in the $rs variable. The PSSession objects have a throttle limit of 50.
NOTE: You can use this command format when the names of computers are stored in a database, spreadsheet, text file, or other text-convertible format.
Create a session by using a URI:
$s = New-PSSession -URI http://ITPTV01:91/NewSession -Credential ITPROTV\Adam
This command creates a PSSession on the Server01 computer and stores it in the $s variable. It uses the URI parameter to specify the transport protocol, the remote computer, the port, and an alternate session configuration.
It also uses the –Credential parameter to specify a user account that has permission to create a session on the remote computer.
Run a background job in a set of sessions:
$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential ITPTV\Adam -ThrottleLimit 16
Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob
These commands create a set of PSSession objects and then run a background job in each of the PSSession objects.
The first command creates a new PSSession on each of the computers listed in the Servers.txt file. It uses the New-PSSession cmdlet to create the PSSession. The value of the –ComputerName parameter is a command that uses the Get-Content cmdlet to get the list of computer names in the Servers.txt file.
The command uses the –Credential parameter to create the PSSession objects that have the permission of a domain administrator, and it uses the –ThrottleLimit parameter to limit the command to 16 concurrent connections. The command saves the PSSession objects in the $s variable.
The second command uses the –AsJob parameter of the Invoke-Command cmdlet to start a background job that runs a Get-Process PowerShell command in each of the PSSession objects in $s.
Create a session using SSH and specify the port and user authentication key:
New-PSSession -HostName Adam@ITPTVLinux:22 -KeyFilePath c:\\AdamKey_rsa
This example shows how to create a PSSession using Secure Shell (SSH). It uses the –Port parameter to specify the port to use and the –KeyFilePath parameter to specify an RSA key used to identify and authenticate the user on the remote computer.
Learn last week’s command: New-ModuleManifest.
Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.