about_Remote_Disconnected_Sessions

Short description

Explains how to disconnect and reconnect to a PowerShell Session (PSSession).

Long description

Beginning in PowerShell 3.0, you can disconnect from a PSSession and reconnect to the PSSession from the same computer or a different computer. The session state is maintained and commands in the PSSession continue to run while the session is disconnected.

The Disconnected Sessions feature allows you to close the session in which a PSSession was created and shut down the computer without disrupting commands running in the remote PSSession. Disconnected sessions are useful for running commands that take an extended time to complete.

You can't disconnect from an interactive session that's started using the Enter-PSSession cmdlet.

You can use disconnected sessions to manage PSSessions that were disconnected unintentionally as the result of a computer or network outage.

Disconnected session cmdlets

The following cmdlets support the Disconnected Sessions feature:

  • Connect-PSSession: Connects to a disconnected PSSession.
  • Disconnect-PSSession: Disconnects a PSSession.
  • Get-PSSession: Gets PSSessions on the local computer or on remote computers.
  • Receive-PSSession: Gets the results of commands that ran in disconnected sessions.
  • Invoke-Command: InDisconnectedSession parameter creates a PSSession and disconnects immediately.

How the Disconnected Sessions feature works

Beginning in PowerShell 3.0, PSSessions are independent of the sessions in which they're created. Active PSSessions are maintained on the remote computer or server side of the connection, even if client side computer is shut down or disconnected from the network.

In PowerShell 2.0, the PSSession is deleted from the remote computer when it's disconnected from the originating session or the session in which it was created ends.

When you disconnect a PSSession, the PSSession remains active and is maintained on the remote computer. The session state changes from Running to Disconnected. You can reconnect to a disconnected PSSession from

  • The current session on the same computer
  • A different session on the same computer
  • From a session on a different computer

The remote computer that maintains the session must be running and be connected to the network.

Commands in a disconnected PSSession continue to run uninterrupted on the remote computer until the command completes or the output buffer fills. To prevent a full output buffer from suspending a command, use the OutputBufferingMode parameter of the Disconnect-PSSession, New-PSSessionOption, or New-PSTransportOption cmdlets.

Disconnected sessions are maintained in the disconnected state on the remote computer. They're available for you to reconnect until you delete the PSSession, such as by using the Remove-PSSession cmdlet, or until the idle timeout of the PSSession expires. You can adjust the idle timeout of a PSSession by using the IdleTimeoutSec or IdleTimeout parameters of the Disconnect-PSSession, New-PSSessionOption, or New-PSTransportOption cmdlets.

Another user can connect to PSSessions that you created, but only if they can provide the credentials that were used to create the session, or use the RunAs credentials of the session configuration.

How to get PSSessions

Beginning in PowerShell 3.0, the Get-PSSession cmdlet gets PSSessions on the local computer and remote computers. It can also get PSSessions that were created in the current session.

To get PSSessions on the local computer or remote computers, use the ComputerName or ConnectionUri parameters. Without parameters, Get-PSSession gets PSSession that were created in the local session, regardless of where they terminate.

The following example shows how to use Get-PSSession.

New-PSSession creates a session to the Server01 computer. The session resides on the Server01 computer.

New-PSSession -ComputerName Server01
Id Name      ComputerName  State    ConfigurationName     Availability
-- ----      ------------  -----    -----------------     ------------
 2 Session2  Server01      Opened   Microsoft.PowerShell     Available

To get the session from Server01, use the ComputerName parameter to specify the target of Get-PSSession.

Get-PSSession -ComputerName Server01
Id Name      ComputerName  State    ConfigurationName     Availability
-- ----      ------------  -----    -----------------     ------------
 2 Session2  Server01      Opened   Microsoft.PowerShell     Available

If the value of the ComputerName parameter of Get-PSSession is localhost, Get-PSSession gets PSSessions that terminate at and are maintained on the local computer. It doesn't get PSSessions on the Server01 computer, even if they were started on the local computer.

Get-PSSession -ComputerName localhost

To get sessions that were created in the current session, use the Get-PSSession cmdlet without parameters. In this example, Get-PSSession gets the PSSession that was created in the current session and connects to the Server01 computer.

Get-PSSession
Id Name      ComputerName  State    ConfigurationName     Availability
-- ----      ------------  -----    -----------------     ------------
 2 Session2  Server01      Opened   Microsoft.PowerShell     Available

How to disconnect sessions

Use the Disconnect-PSSession cmdlet to disconnect a session. To identify the PSSession, use the Session parameter, or pipe a PSSession object from the New-PSSession or Get-PSSession cmdlets to Disconnect-PSSession.

The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the Availability is None.

Get-PSSession -ComputerName Server01 | Disconnect-PSSession
Id Name      ComputerName  State         ConfigurationName     Availability
-- ----      ------------  -----         -----------------     ------------
 2 Session2  Server01      Disconnected  Microsoft.PowerShell          None

To create a disconnected session, use the InDisconnectedSession parameter of the Invoke-Command cmdlet. It creates a session, starts the command, and disconnects immediately, before the command can return any output.

The following command runs a Get-WinEvent command in a disconnected session on the remote computer Server02.

Invoke-Command -ComputerName Server02 -InDisconnectedSession -ScriptBlock {
   Get-WinEvent -LogName "*PowerShell*" }
Id Name      ComputerName  State         ConfigurationName     Availability
-- ----      ------------  -----         -----------------     ------------
 4 Session3  Server02      Disconnected  Microsoft.PowerShell          None

How to connect to disconnected sessions

To connect a disconnected session, use the Connect-PSSession cmdlet with the ComputerName or ConnectionUri parameters. Alternatively, you could pipe the output of Get-PSSession to Connect-PSSession.

The following example gets the sessions on the Server02 computer. The output includes two disconnected sessions.

Get-PSSession -ComputerName Server02
Id Name      ComputerName   State         ConfigurationName     Availability
-- ----      ------------   -----         -----------------     ------------
 2 Session2  juneb-srv8320  Disconnected  Microsoft.PowerShell          None
 4 Session3  juneb-srv8320  Disconnected  Microsoft.PowerShell          None

The following command connects to Session2. The PSSession is now open and available.

Connect-PSSession -ComputerName Server02 -Name Session2
Id Name      ComputerName    State    ConfigurationName     Availability
-- ----      ------------    -----    -----------------     ------------
 2 Session2  juneb-srv8320   Opened   Microsoft.PowerShell     Available

How to get the results

To get the results of commands that ran in a disconnected PSSession, use the Receive-PSSession cmdlet.

You can use Receive-PSSession rather than using the Connect-PSSession cmdlet. If the session is already reconnected, Receive-PSSession gets the results of commands that ran when the session was disconnected. If the PSSession is still disconnected, Receive-PSSession connects to it and then gets the results of commands that ran while it was disconnected.

Receive-PSSession can return the results in a job (asynchronously) or to the host program (synchronously). Use the OutTarget parameter to select Job or Host. The default value is Host. However, if the command that's being received was started in the current session as a Job, it's returned as a Job by default.

The following example uses the Receive-PSSession cmdlet to reconnect to the session on Server02 and get the results of the Get-WinEvent command. The OutTarget parameter is used to get the results in a Job.

Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job
Id   Name   PSJobTypeName   State         HasMoreData     Location
--   ----   -------------   -----         -----------     --------
 3   Job3   RemoteJob       Running       True            Server02

To get the job's results, use the Receive-Job cmdlet.

Get-Job | Receive-Job -Keep
ProviderName: PowerShell

TimeCreated             Id LevelDisplayName Message     PSComputerName
-----------             -- ---------------- -------     --------------
5/14/2012 7:26:04 PM   400 Information      Engine stat Server02
5/14/2012 7:26:03 PM   600 Information      Provider "W Server02
5/14/2012 7:26:03 PM   600 Information      Provider "C Server02
5/14/2012 7:26:03 PM   600 Information      Provider "V Server02

State and Availability properties

The State and Availability properties of a disconnected PSSession tell you whether the session is available for you to reconnect to it.

When a PSSession is connected to the current session, its state is Opened and its availability is Available. When you disconnect from the PSSession, the PSSession state is Disconnected and its availability is None.

The value of the State property is relative to the current session. A value of Disconnected means that the PSSession isn't connected to the current session. But, it doesn't mean that the PSSession is disconnected from all sessions. It might be connected to a different session.

To determine whether you can connect or reconnect to the PSSession, use the Availability property. A value of None indicates that you can connect to the session. A value of Busy indicates that you can't connect to the PSSession because it's connected to another session.

The following example is run in two PowerShell sessions on the same computer. Note the changing values of the State and Availability properties in each session as the PSSession is disconnected and reconnected.

# Session 1
New-PSSession -ComputerName Server30 -Name Test
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1  Test   Server30        Opened        Microsoft.PowerShell     Available
# Session 2
Get-PSSession -ComputerName Server30 -Name Test
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1 Test    Server30        Disconnected  Microsoft.PowerShell          Busy
# Session 1
Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1 Test    Server30        Disconnected  Microsoft.PowerShell          None
# Session 2
Get-PSSession -ComputerName Server30
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1 Test    Server30        Disconnected  Microsoft.PowerShell          None
# Session 2
Connect-PSSession -ComputerName Server30 -Name Test
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
3 Test    Server30        Opened        Microsoft.PowerShell     Available
# Session 1
Get-PSSession -ComputerName Server30
Id Name   ComputerName    State         ConfigurationName     Availability
-- ----   ------------    -----         -----------------     ------------
1 Test    Server30        Disconnected  Microsoft.PowerShell          Busy

Disconnected sessions are maintained on the remote computer until you delete them, such as by using the Remove-PSSession cmdlet, or they time out. The IdleTimeout property of a PSSession determines how long a disconnected session is maintained before it's deleted.

Idle timeout values

PSSessions are idle when the heartbeat thread receives no response. Disconnecting a session makes it idle and starts the IdleTimeout clock, even if commands are still running in the disconnected session. PowerShell considers disconnected sessions to be active, but idle.

When creating and disconnecting sessions, verify that the idle timeout in the PSSession is long enough to maintain the session for your needs, but not so long that it consumes unnecessary resources on the remote computer.

The IdleTimeoutMs property of the session configuration determines the default idle timeout of sessions that use the session configuration. You can override the default value, but that value can't exceed the MaxIdleTimeoutMs property of the session configuration.

Use the following command to get the values of IdleTimeoutMs and MaxIdleTimeoutMs for a session configuration.

Get-PSSessionConfiguration |
  Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs

If you're a member of the Administrators group on the remote computer, you can set these values when you create a session configuration. Also, you can change the values when you disconnect.

The idle timeout value of session configurations and session options is in milliseconds. The idle timeout value of sessions and session configuration options is in seconds.

You can set the idle timeout of a PSSession when you create the PSSession (New-PSSession, Invoke-Command) and when you disconnect from it (Disconnect-PSSession). However, you can't change the IdleTimeout value when you connect to the PSSession (Connect-PSSession) or get results (Receive-PSSession).

The Connect-PSSession and Receive-PSSession cmdlets have a SessionOption parameter that takes a PSSessionOption object, such as one returned by the New-PSSessionOption cmdlet.

The IdleTimeout value in SessionOption object and the IdleTimeout value in the $PSSessionOption preference variable don't change the value of the IdleTimeout in a Connect-PSSession or Receive-PSSession command.

To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds).

When you create PSSessions, the values in $PSSessionOption variable take precedence over the values in the session configuration.

For example, the following command sets an idle timeout of 48 hours:

$PSSessionOption = New-PSSessionOption -IdleTimeoutMSec 172800000

To create a PSSession with a particular idle timeout value, use the IdleTimeoutMSec parameter of the New-PSSessionOption cmdlet. Then, use the session option in the value of the SessionOption parameter of the New-PSSession or Invoke-Command cmdlets.

The values set when creating the session take precedence over the values set in the $PSSessionOption preference variable and the session configuration.

For example:

$o = New-PSSessionOption -IdleTimeoutMSec 172800000
New-PSSession -SessionOption $o

To change the idle timeout of a PSSession when disconnecting, use the IdleTimeoutSec parameter of the Disconnect-PSSession cmdlet.

For example:

Disconnect-PSSession -IdleTimeoutSec 172800

To create a session configuration with a particular idle timeout and maximum idle timeout, use the IdleTimeoutSec and MaxIdleTimeoutSec parameters of the New-PSTransportOption cmdlet. Then, use the transport option in the value of the TransportOption parameter of Register-PSSessionConfiguration.

For example:

$o = New-PSTransportOption -IdleTimeoutSec 172800 -MaxIdleTimeoutSec 259200
Register-PSSessionConfiguration -Name Test -TransportOption $o

To change the default idle timeout and maximum idle timeout of a session configuration, use the IdleTimeoutSec and MaxIdleTimeoutSec parameters of the New-PSTransportOption cmdlet. Then, use the transport option in the value of the TransportOption parameter of Set-PSSessionConfiguration.

For example:

$o = New-PSTransportOption -IdleTimeoutSec 172800 -MaxIdleTimeoutSec 259200
Set-PSSessionConfiguration -Name Test -TransportOption $o

Output buffering mode

The output buffering mode of a PSSession determines how command output is managed when the output buffer of the PSSession is full.

In a disconnected session, the output buffering mode effectively determines whether the command continues to run while the session is disconnected.

The valid values as follows:

  • Block (default) - When the output buffer is full, execution is suspended until the buffer is clear. Block preserves data, but might interrupt the command.
  • Drop - When the output buffer is full, execution continues. As new output is generated, the oldest output is discarded. When using the Drop value, redirect the output to a file. This value is recommended for disconnected sessions.

The OutputBufferingMode property of the session configuration determines the default buffering mode of sessions that use the session configuration.

To find a session configuration's value of the OutputBufferingMode, you can use either of the following command formats:

(Get-PSSessionConfiguration <ConfigurationName>).OutputBufferingMode
Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode

You can override the default value in the session configuration and set the output buffering mode of a PSSession when you create a PSSession, when you disconnect, and when you reconnect.

If you're a member of the Administrators group on the remote computer, you can create and change the output buffering mode of session configurations.

To create a PSSession with an output buffering mode of Drop, create a $PSSessionOption preference variable in which the value of the OutputBufferingMode property is Drop.

When you create PSSessions, the values in $PSSessionOption variable take precedence over the values in the session configuration.

For example:

$PSSessionOption = New-PSSessionOption -OutputBufferingMode Drop

Use the OutputBufferingMode parameter of the New-PSSessionOption cmdlet to create a session option with a value of Drop. Then, use the PSSessionOption object as value of the SessionOption parameter of the New-PSSession or Invoke-Command cmdlets.

The values set when creating the session take precedence over the values set in the $PSSessionOption preference variable and the session configuration.

For example:

$o = New-PSSessionOption -OutputBufferingMode Drop
New-PSSession -SessionOption $o

To change the output buffering mode of a PSSession when disconnecting, use the OutputBufferingMode parameter of the Disconnect-PSSession cmdlet.

For example:

Disconnect-PSSession -OutputBufferingMode Drop

To change the output buffering mode of a PSSession when reconnecting, use the OutputBufferingMode parameter of the New-PSSessionOption cmdlet. Then, use the session option in the value of the SessionOption parameter of Connect-PSSession or Receive-PSSession.

For example:

$o = New-PSSessionOption -OutputBufferingMode Drop
Connect-PSSession -ComputerName Server01 -Name Test -SessionOption $o

To create a session configuration with a default output buffering mode of Drop, use the OutputBufferingMode parameter of the New-PSTransportOption cmdlet to create a transport option object with a value of Drop. Then, use the transport option in the value of the TransportOption parameter of Register-PSSessionConfiguration.

For example:

$o = New-PSTransportOption -OutputBufferingMode Drop
Register-PSSessionConfiguration -Name Test -TransportOption $o

To change the default output buffering mode of a session configuration, use the OutputBufferingMode parameter of the New-PSTransportOption cmdlet to create a transport option with a value of Drop. Then, use the Transport option in the value of the SessionOption parameter of Set-PSSessionConfiguration.

For example:

$o = New-PSTransportOption -OutputBufferingMode Drop
Set-PSSessionConfiguration -Name Test -TransportOption $o

Disconnecting loopback sessions

Loopback sessions, or local sessions, are PSSessions that originate and terminate on the same computer. Like other PSSessions, active loopback sessions are maintained on the computer on the remote end of the connection (the local computer), so you can disconnect from and reconnect to loopback sessions.

By default, loopback sessions are created with a network security token that doesn't permit commands run in the session to access other computers. You can reconnect to loopback sessions that have a network security token from any session on the local computer or a remote computer.

However, if you use the EnableNetworkAccess parameter of the New-PSSession, Enter-PSSession, or Invoke-Command cmdlet, the loopback session is created with an interactive security token. The interactive token enables commands that run in the loopback session to get data from other computers.

You can disconnect loopback sessions with interactive tokens and then reconnect to them from the same session or a different session on the same computer. However, to prevent malicious access, you can reconnect to loopback sessions with interactive tokens only from the computer on which they were created.

Waiting for jobs in disconnected sessions

The Wait-Job cmdlet waits until a job completes and then returns to the command prompt or the next command. By default, Wait-Job returns if the session in which a job is running is disconnected. To direct the Wait-Job cmdlet to wait until the session is reconnected, in the Opened state, use the Force parameter. For more information, see Wait-Job.

Robust sessions and unintentional disconnection

A PSSession might be unintentionally disconnected because of a computer failure or network outage. PowerShell attempts to recover the PSSession, but its success depends upon the severity and duration of the cause.

The state of an unintentionally disconnected PSSession might be Broken or Closed, but it might also be Disconnected. If the value of State is Disconnected, you can use the same techniques to manage the PSSession as you would if the session were disconnected intentionally. For example, you can use the Connect-PSSession cmdlet to reconnect to the session and the Receive-PSSession cmdlet to get results of commands that ran while the session was disconnected.

If you close (exit) the session in which a PSSession was created while commands are running in the PSSession, PowerShell maintains the PSSession in the Disconnected state on the remote computer. If you close (exit) the session in which a PSSession was created, but no commands are running in the PSSession, PowerShell doesn't attempt to maintain the PSSession.

See also