Disable-PSRemoting

Article
04/20/2010

Applies To: Windows PowerShell 2.0

Prevents the computer from receiving remote Windows PowerShell commands.

Syntax

Disable-PSRemoting [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Description

The Disable-PSRemoting function disables all session configurations on the local computer by adding a "deny all" entry to their security descriptors. This prevents the local computer from receiving remote commands.

Disable-PSRemoting does not stop the WinRM service and it does not prevent users of the local computer from establishing sessions that connect to remote computers or sending commands to other computers.

To re-enable the session configurations, use the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlets.

To run this function on Windows Vista, Windows Server 2008, and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option.

Parameters

-Force

Suppresses all user prompts. By default, you are prompted to confirm each operation.

Required?	false
Position?	named
Default Value	False
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Confirm

Prompts you for confirmation before executing the command.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-WhatIf

Describes what would happen if you executed the command without actually executing the command.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

None

This cmdlet does not return any object.

Notes

A session configuration is a group of settings that define the environment for a session. The session configurations are located on the remote computer and are used by local and remote sessions that connect to the computer.

Every session that connects to the computer must use one of the session configurations that are registered on the computer. This includes persistent sessions that you create by using New-PSSession or Enter-PSSession cmdlets, and the temporary sessions that Windows PowerShell creates when you use the ComputerName parameter of a cmdlet that uses WS-Management remoting technology, such as Invoke-Command. By denying access to all session configurations, you effectively prevent all users from establishing sessions that connect to the computer.

Disable-PSRemoting is the equivalent of "Disable-PSSessionConfiguration -name *.

Example 1

C:\PS>disable-psremoting

Description
-----------
This command disables all session configurations on the computer.

Example 2

C:\PS>disable-psremoting -force

Description
-----------
This command disables all session configurations on the computer without prompting.

Example 3

C:\PS>disable-psremoting -force

C:\PS> new-pssession -computername localhost

[localhost] Connecting to remote server failed with the following error
message : Access is denied. For more information, see the about_Remote_Troub
leshooting Help topic.
    + CategoryInfo          : OpenError: (System.Manageme....RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
    + FullyQualifiedErrorId : PSSessionOpenFailed


C:\PS> new-pssession -computername Server01

 Id Name       ComputerName    State    Configuration         Availability
 -- ----       ------------    -----    -------------         ------------
  1 Session1   Server01...     Opened   Microsoft.PowerShell     Available


C:\PS> enable-pssessionConfiguration -name * -force

C:\PS> new-pssession -computername localhost

 Id Name       ComputerName    State    Configuration         Availability
 -- ----       ------------    -----    -------------         ------------
  1 Session1   localhost       Opened   Microsoft.PowerShell     Available

Description
-----------
This example shows the effect of using Disable-PSRemoting.

The first command uses Disable-PSRemoting to disable all registered session configurations on the local computer.

The second command uses the New-PSSession to create a remote session to the local computer (also known as a "loopback"). Because the session configurations that session requires are disabled, the command fails.

The third command uses the New-PSSession cmdlet to create a session from the local computer to the Server01 remote computer. This command, which uses the session configurations on the remote computer, succeeds. 

The fourth command uses the Enable-PSSessionConfiguration cmdlet to re-enable all of the session configurations on the local computer. The command uses a value of * (all) in the Name parameter. 

The fifth command attempts again to establish a loopback session by using the New-PSSession cmdlet. This time the command succeeds, because the session configuration that requires are enabled.

Example 4

C:\PS>disable-psremoting -force

C:\PS> get-psSessionConfiguration | format-table -property name, permission -auto

Name                   Permission
----                   ----------
microsoft.powershell   Everyone AccessDenied, BUILTIN\Administrators AccessAllowed
microsoft.powershell32 Everyone AccessDenied, BUILTIN\Administrators AccessAllowed

C:\PS> enable-psremoting -force
WinRM already is set up to receive requests on this machine.
WinRM already is set up for remote management on this machine.

C:\PS>> Get-PSSessionConfiguration | ft name, Permission -auto

Name                   Permission
----                   ----------
microsoft.powershell   BUILTIN\Administrators AccessAllowed
microsoft.powershell32 BUILTIN\Administrators AccessAllowed

Description
-----------
This example shows the effect on the session configurations of using Disable-PSRemoting and Enable-PSRemoting.

The first command uses the Disable-PSRemoting function to disable all registered session configurations. The force parameter suppresses all user prompts.

The second command uses the Get-PSSessionConfiguration cmdlet to display the registered session configurations on the computer. The command uses a pipeline operator to send the results to a Format-Table command, which displays only the Name and Permission properties of the configurations in a table.

The resulting table shows that everyone is denied permission to the configurations.

The third command uses the Enable-PSRemoting cmdlet to re-enable all of the session configurations on the computer. You can also use an "Enable-PsSessionConfiguration -name *" command. The command uses the Force parameter to suppress all user prompts and to restart the WinRM service without prompting.

The fourth command uses Get-PSSessionConfiguration and Format-Table to display the names and permissions of the session configurations. The results show that members of the Administrators group now have access to the session configurations.

Share via