Import PSSession - PowerShell

Overview

Import-PSSession establishes a remote PowerShell session with a computer or device. It allows users to execute commands and manage resources on the remote system as if they were present locally. Remote sessions enable efficient administration and scripting across multiple devices.

Syntax

Import-PSSession [-ComputerName] <RemoteComputerName> [-Credential] <PSCredential> [-Authentication] <AuthenticationMethod> [-Port] <PortNumber> [-SessionName] <SessionName> [-ThrottleLimit] <MaximumConcurrency> [-UseSSL] [-AllowRedirection] [-DisableNAgle] [-MaximumReceivedObjectSize] <MaximumObjectSize> [-MaximumReceivedDataSizePerCommand] <MaximumDataSize> [-KeySize] <EncryptionKeySize> [-CertificateThumbprint] <CertificateThumbprint> [-AllowImplicitRemoting] [-AvoidPSRemotingWarning] [-ProxyAccessType] <ProxyAccessType> [-ProxyAuthentication] <ProxyCredentials> [-ProxyDestination] <ProxyDestination> [-ConnectionRetryCount] <ConnectionRetryAttempts> [-ConnectionRetryInterval] <ConnectionRetryDelay> [-OutputBufferingMode] <BufferingMode> [-Sta] [-Background] [-JobName] <JobName>

Options/Flags

  • -ComputerName: Specifies the name of the remote computer to establish a session with.
  • -Credential: Provides the user credentials for authentication on the remote system.
  • -Authentication: Sets the authentication method to use. Options include “Negotiate”, “Kerberos”, “Basic”, and “Digest”. Default: “Negotiate”.
  • -Port: Specifies the port number for the remote session. Default: 5985.
  • -SessionName: Names the created remote session.
  • -ThrottleLimit: Limits the maximum number of concurrent commands running in the remote session.
  • -UseSSL: Enforces the use of a secure SSL connection.
  • -AllowRedirection: Allows the remote session to be redirected through an intermediate server.
  • -DisableNAgle: Disables the Nagle algorithm, improving performance for small data transfers.
  • -MaximumReceivedObjectSize: Sets the maximum size of any object returned from the remote session.
  • -MaximumReceivedDataSizePerCommand: Limits the maximum amount of data that can be received per command.
  • -KeySize: Specifies the encryption key size to use for SSL connections.
  • -CertificateThumbprint: Uses the specified certificate’s thumbprint for SSL client authentication.
  • -AllowImplicitRemoting: Allows remote sessions without explicit authentication (experimental).
  • -AvoidPSRemotingWarning: Suppresses PSRemoting warnings about potential performance issues.
  • -ProxyAccessType: Sets the proxy access type for the session. Options include “None”, “AutoDetect”, and “Manual”.
  • -ProxyAuthentication: Provides the credentials for proxy authentication.
  • -ProxyDestination: Specifies the proxy server address and port.
  • -ConnectionRetryCount: Sets the maximum number of connection retry attempts.
  • -ConnectionRetryInterval: Defines the time delay between connection retries.
  • -OutputBufferingMode: Configures the buffering behavior for output from the remote session. Options include “None”, “Command”, and “Job”.
  • -Sta: Creates a single-threaded apartment (STA) environment for the session.
  • -Background: Runs the command asynchronously in the background.
  • -JobName: Names the job that will run the command in the background.

Examples

Establish a remote session with a local computer using default settings:

Import-PSSession

Create a named session to a remote computer with specific credentials:

Import-PSSession -ComputerName remote-server -Credential my-credentials -SessionName MyRemoteSession

Limit the maximum concurrency and use SSL on a remote session:

Import-PSSession -ComputerName remote-server -ThrottleLimit 10 -UseSSL

Common Issues

  • Authentication errors: Ensure you provide valid credentials and that the remote computer allows remote access.
  • Connection issues: Check network connectivity and firewall settings on both computers. Increase the retry count and interval if necessary.
  • Performance bottlenecks: Adjust the throttling limit or disable the Nagle algorithm for improved data transfer speed.
  • Buffering issues: Configure the output buffering mode to optimize the display of remote session output.

Integration

Combine with Invoke-Command:

Import-PSSession remote-server
Invoke-Command -SessionName MyRemoteSession { Get-Process }

Create a persistent session for automated tasks:

$session = Import-PSSession -ComputerName remote-server
Do-Stuff-On-Remote-Server -Session $session
  • New-PSSession: Creates a new session configuration without establishing a connection.
  • Enter-PSSession: Enters an established remote session interactively.
  • Disconnect-PSSession: Terminates an active remote session.