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 |
none |
|
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 |
none |
|
Accept Pipeline Input? |
false |
|
Accept Wildcard Characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. 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 This command disables all session configurations on the computer.
Example 2
C:\PS>disable-psremoting -force 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.
See Also