Connect PSSession - PowerShell

Overview

Connect-PSSession establishes a remote PowerShell session to manage and interact with a remote computer. It allows you to run commands, retrieve data, and modify settings on the remote system.

Syntax

Connect-PSSession [-ComputerName] <String[]> [-Credential] <PSCredential> [-Authentication] <String>
[-Port] <UInt32> [-SessionName] <String> [-ConfigurationName] <String> [-UseSSL] [-AllowRedirection]
[-ConnectionRetryCount] <Int32> [-ConnectionRetryInterval] <TimeSpan> [-SessionOption] <Object[]> [-ProxyAccessType] <String>
[-ProxyAuthentication] <AuthenticationMechanism> [-ProxyCredential] <PSCredential> [-ProxyPort] <Int32>
[-ProxyServer] <String> [-ProxyUri] <Uri> [-ProxyUseDefaultCredentials] [-Wait] [-OutputEncoding] <Encoding>
[-ErrorVariable] <String> [-WarningVariable] <String> [-Verbose] [-Debug] [-ErrorAction] <ActionPreference>
[-WarningAction] <ActionPreference> [-OutVariable] <String[]>

Options/Flags

  • -ComputerName: Specifies the computer name or IP address of the remote system.
  • -Credential: Uses the specified credentials to connect to the remote session.
  • -Authentication: Selects the authentication method: Default, Negotiate, Kerberos, CredSSP, or Basic.
  • -Port: Defines the port number for the remote session (default: 5985).
  • -SessionName: Specifies a name for the remote session.
  • -ConfigurationName: Uses a specific remote PowerShell configuration.
  • -UseSSL: Encrypts the connection using SSL.
  • -AllowRedirection: Allows the session to be redirected to another computer.
  • -ConnectionRetryCount: Sets the number of connection attempts if the initial connection fails.
  • -ConnectionRetryInterval: Defines the time interval between connection attempts.
  • -SessionOption: Adds additional session options, such as performance settings.
  • -ProxyAccessType: Type of proxy to use: None, WinHttpProxy, or WebProxy.
  • -ProxyAuthentication: Authentication type for the proxy: Basic, Negotiate, Digest, or Default.
  • -ProxyCredential: Credentials for connecting to the proxy.
  • -ProxyPort: Port number of the proxy server.
  • -ProxyServer: Name or IP address of the proxy server.
  • -ProxyUri: URI of the proxy server.
  • -ProxyUseDefaultCredentials: Uses the default system credentials for the proxy.
  • -Wait: Waits for the connection to be established before returning.
  • -OutputEncoding: Specifies the encoding for the output from the remote session.
  • -ErrorVariable: Stores any error messages in the specified variable.
  • -WarningVariable: Stores any warning messages in the specified variable.
  • -Verbose: Displays detailed output about the command execution.
  • -Debug: Displays even more detailed output for troubleshooting purposes.
  • -ErrorAction: Specifies the action to take if an error occurs.
  • -WarningAction: Specifies the action to take if a warning occurs.
  • -OutVariable: Stores the output in the specified variable.

Examples

Simple connection to a remote computer:

Connect-PSSession -ComputerName MyRemoteComputer

Connect using credentials and create a named session:

$creds = Get-Credential
Connect-PSSession -ComputerName MyRemoteComputer -Credential $creds -SessionName MyRemoteSession

Advanced connection with session options and proxy:

$sessionOption = New-PSSessionOption -IdleTimeout 300 -PerformanceDataInterval 10
$proxy = New-WebProxy -Uri http://myproxy:8080
Connect-PSSession -ComputerName MyRemoteComputer -SessionOption $sessionOption -ProxyAccessType WebProxy -ProxyCredential $creds -ProxyUri $proxy.Uri

Common Issues

  • Access denied: Ensure you have the necessary permissions on the remote computer.
  • Connection timeout: Increase the ConnectionRetryCount and ConnectionRetryInterval.
  • SSL errors: Verify the SSL certificate on the remote computer is valid.
  • Proxy issues: Check that your proxy settings are correct and that you have access to the proxy server.

Integration

Run commands in a remote session:

Connect-PSSession -ComputerName MyRemoteComputer
Get-Process

Get or set registry keys remotely:

Connect-PSSession -ComputerName MyRemoteComputer
Get-ItemProperty -Path HKLM:\SOFTWARE\Company\MyProduct

Invoke-Command:

To execute commands on the remote session without creating a session object, use Invoke-Command:

Invoke-Command -ComputerName MyRemoteComputer -ScriptBlock { Get-Process }