New PSSession - PowerShell

Overview

New-PSSession establishes a remote PowerShell session to a specified computer. It allows users to execute PowerShell commands and manage resources on remote systems as if they were working locally. This command is invaluable for remote administration, troubleshooting, and managing multiple systems efficiently.

Syntax

New-PSSession [-ComputerName <string>] [-Credential <PSCredential>] [-Name <string>] [-Port <int>] [-ProxyCredential <PSCredential>] [-ProxyUseDefaultCredentials] [-SessionOption <PSSessionOption>] [-UseSSL] [-Authentication <AuthenticationMechanism>] [-ConfigurationName <string>]

Options/Flags

  • -ComputerName Specifies the name of the remote computer to establish a session with. By default, the local computer is used.
  • -Credential Provides credentials for authentication on the remote computer, if necessary.
  • -Name Assigns a name to the new session for easy identification.
  • -Port Specifies the port number for the remote PowerShell service. Default is 5985.
  • -ProxyCredential Provides credentials for a proxy server, if required.
  • -ProxyUseDefaultCredentials Uses the system’s default credentials for the proxy server.
  • -SessionOption Configures advanced session options, such as buffer size or connection timeout.
  • -UseSSL Encrypts the session using SSL.
  • -Authentication Specifies the authentication mechanism to use, such as Negotiate, Kerberos, or CredSSP. Default is Negotiate.
  • -ConfigurationName Imports a saved session configuration containing pre-configured connection settings.

Examples

Create a session to a remote computer with default credentials:

New-PSSession -ComputerName remote-server

Create a session with custom credentials and specify a session name:

$cred = Get-Credential
New-PSSession -ComputerName remote-server -Credential $cred -Name "MySession" -Port 5986

Create a session with advanced session options:

$sessionOption = New-PSSessionOption -BufferSize 1024 -ConnectionTimeout 180
New-PSSession -ComputerName remote-server -SessionOption $sessionOption

Common Issues

  • Authentication errors: Ensure that the specified credentials have sufficient permissions on the remote computer.
  • Connection timeouts: Adjust the -ConnectionTimeout option if the session is taking too long to establish.
  • Access denied: Verify that the remote PowerShell service is running and that the firewall is not blocking the connection.

Integration

Combine with Invoke-Command: Execute commands remotely using the established session:

Invoke-Command -Session $session -ScriptBlock { Get-Service }

Use within scripts: Automate remote management tasks by incorporating New-PSSession into scripts:

$session = New-PSSession -ComputerName remote-server
Invoke-Command -Session $session -ScriptBlock { Start-Service W3Svc }
  • Get-PSSession: Retrieves existing remote PowerShell sessions.
  • Remove-PSSession: Closes and removes a remote session.
  • Enter-PSSession: Enters an existing remote session for interactive management.
  • Set-PSSessionConfiguration: Creates or modifies a session configuration for future use.