Disable-PSSessionConfiguration

Disables session configurations on the local computer.
Disable-PSSessionConfiguration [[-Name] [<String[]>]] [-Force] [-NoServiceRestart] [-Confirm] [-WhatIf][<CommonParameters>]

The Disable-PSSessionConfiguration cmdlet disables session configurations on the local computer, which prevents all users from using the session configurations to create a user-managed sessions (PSSessions) on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users.

Starting in Windows PowerShell 3.0, the Disable-PSSessionConfiguration cmdlet sets the Enabled setting of the session configuration (WSMan:localhostPluginsEnabled) to False.

In Windows PowerShell 2.0, the Disable-PSSessionConfiguration cmdlet adds a Deny_All entry to the security descriptor of one or more registered session configurations.

Without parameters, Disable-PSSessionConfiguration disables the Microsoft.PowerShell configuration, which is the default configuration that is used for sessions. Unless the user specifies a different configuration, both local and remote users are effectively prevented from creating any sessions that connect to the computer.

To disable all session configurations on the computer, use Disable-PSRemoting.

Parameters
-Force [<SwitchParameter>]

Forces the command to run without asking for user confirmation.

-Name [<String[]>]

Specifies an array of names of session configurations to disable. Enter one or more configuration names. Wildcard characters are permitted. You can also pipe a string that contains a configuration name or a session configuration object to Disable-PSSessionConfiguration.

If you omit this parameter, Disable-PSSessionConfiguration disables the Microsoft.PowerShell session configuration.

-NoServiceRestart [<SwitchParameter>]
 
-Confirm [<SwitchParameter>]

  • Default value is false

Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.

-WhatIf [<SwitchParameter>]

  • Default value is false

Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.

<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable,OutBuffer, PipelineVariable, and OutVariable.

Inputs

Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration, System.String

You can pipe a session configuration object or a string that contains the name of a session configuration to this cmdlet.

Outputs

None

This cmdlet does not return any objects.

Examples
  1. Disable the default configuration:
    PS C:> Disable-PSSessionConfiguration
    

    This command disables the Microsoft.PowerShell session configuration.

  2. Disable all registered session configurations:
    PS C:> Disable-PSSessionConfiguration -Name *
    

    This command disables all registered session configurations on the computer.

  3. Disable session configurations by name:
    PS C:> Disable-PSSessionConfiguration -Name Microsoft* -Force
    

    This command disables all session configurations that have names that begin with Microsoft. The command uses the Force parameter to suppress all user prompts from the command.

  4. Disable session configurations by using the pipeline:
    PS C:> Get-PSSessionConfiguration -Name MaintenanceShell, AdminShell | Disable-PSSessionConfiguration
    

    This command disables the MaintenanceShell and AdminShell session configurations.

    The command uses a pipeline operator (|) to send the results of a Get-PSSessionConfiguration command to Disable-PSSessionConfiguration.

  5. Effects of disabling a session configuration:
    1. The first command uses the Get-PSSessionConfiguration and Format-Table cmdlets to display only the Name and Permission properties of the session configuration objects:
      PS C:> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto
      
         Name                   Permission
         ----                   ----------
         MaintenanceShell       BUILTINAdministrators AccessAllowed
         microsoft.powershell   BUILTINAdministrators AccessAllowed
         microsoft.powershell32 BUILTINAdministrators AccessAllowed

      This table format makes it easier to see the values of the objects. The results show that members of the Administrators group are permitted to use the session configurations.

    2. The second command uses the Disable-PSSessionConfiguration cmdlet to disable the MaintenanceShell session configuration:
      PS C:> Disable-PSSessionConfiguration -Name MaintenanceShell -Force
      

      The command uses the Force parameter to suppress all user prompts.

    3. The third command repeats the first command:
      PS C:> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto
      
         Name                   Permission
         ----                   ----------
         MaintenanceShell       Everyone AccessDenied, BUILTINAdministrators AccessAllowed
         microsoft.powershell   BUILTINAdministrators AccessAllowed
         microsoft.powershell32 BUILTINAdministrators AccessAllowed

      The results show that you can still get the object that represents the MaintenanceShell session configuration even though everyone is denied access to it. The “AccessDenied” entry takes precedence over all other entries in the security descriptor.

    4. The fourth command uses the Set-PSSessionConfiguration cmdlet to increase the MaximumDataSizePerCommandMB setting on the MaintenanceShell session configuration to 60:
      PS C:> Set-PSSessionConfiguration -Name MaintenanceShell -MaximumReceivedDataSizePerCommandMB 60
      
         ParamName            ParamValue
         ---------            ----------
         psmaximumreceived... 60
         "Restart WinRM service"
         WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service 
         winrm"?
         [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

      The results show that the command was successful even though everyone is denied access to the configuration.

    5. The fifth command attempts to use the MaintenanceShell session configuration in a session:
      PS C:> New-PSSession -ComputerName localhost -ConfigurationName MaintenanceShell
      [localhost] Connecting to remote server failed with the following error message : Access is denied. For more information, see the about_Remote_Troubl
      eshooting Help topic.
      + CategoryInfo          : OpenError: (System.Manageme....RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
      + FullyQualifiedErrorId : PSSessionOpenFailed
      

      It uses the New-PSSession cmdlet to create a new session and the ConfigurationName parameter to specify the MaintenanceShell configuration.The results show that the New-PSSession command fails because the user is denied access to the configuration.This example shows the effect of disabling a session configuration.

Additional Notes
 To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of the Windows operating system, 
 you must start Windows PowerShell by using the Run as administrator option.
Related Links

Enable-PSSessionConfiguration
Get-PSSessionConfiguration
New-PSSessionConfigurationFile
Register-PSSessionConfiguration
Set-PSSessionConfiguration
Test-PSSessionConfigurationFile
Unregister-PSSessionConfiguration