about_Session_Configurations

TOPIC
	about_Session_Configurations

SHORT DESCRIPTION
	Describes session configurations, which determine the users who can 
	connect to the computer remotely and the commands they can run.

LONG DESCRIPTION
	A session configuration is a group of settings on the local computer
	that define the environment for the Windows PowerShell sessions that are
	created when remote users connect to the local computer. 

	Administrators of the computer can use session configurations to protect
	the computer and to define custom environments for users who connect to
	the computer.

	Administrators can also use session configurations to determine the
	permissions that are required to connect to the computer remotely. By
	default, only members of the Administrators group have permission to 
	use the session configuration to connect remotely, but you can change
	the default settings to allow all users, or selected users, to connect
	remotely to your computer.

	Session configurations are a feature of Web Services for Management 
	(WS-Management) based Windows PowerShell remoting. They are used only 
	when you use the New-PSSession, Invoke-Command, or Enter-PSSession cmdlets
	to connect to a remote computer.

	Note: To manage the session configurations on a computer that is running
		Windows Vista, Windows Server 2008, or a later version of Windows, 
		start Windows PowerShell with the "Run as administrator" option.


  About Session Configurations
   
	Every Windows PowerShell session uses a session configuration. This
	includes persistent sessions that you create by using the 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-based remoting technology, such as 
	Invoke-Command. 

	Administrators can use session configurations to protect the resources 
	of the computer and to create custom environments for users who connect
	to the computer. For example, you can use a session configuration to 
	limit the size of objects that the computer receives in the session, 
	to define the language mode of the session, and to specify the cmdlets,
	providers, and functions that are available in the session. 

	By configuring the security descriptor of a session configuration, you
	determine who can use the session configuration to connect to the 
	computer. Users must have Execute permission to a session configuration 
	to use it in a session. If a user does not have the required permissions
	to use any of the session configurations on a computer, the user cannot
	connect to the computer remotely.	 
   
	By default, only Administrators of the computer have permission to use
	the default session configurations. But, you can change the security 
	descriptors to allow everyone, no one, or only selected users to use 
	the session configurations on your computer.


 
  Default Session Configurations

	Windows PowerShell includes a built-in session configuration named 
	Microsoft.PowerShell. On computers running 64-bit versions of Windows, 
	Windows PowerShell also provides Microsoft.PowerShell32, a 32-bit 
	session configuration.

	These session configurations are used for sessions by default, that is, 
	when a command to create a session does not include the ConfigurationName
	parameter of the New-PSSession, Enter-PSSession, or Invoke-Command 
	cmdlet.

	The security descriptors for the default session configurations allow 
	only members of the Administrators group on the local computer to use 
	them. As such, only members of the Administrators group can connect to
	the computer remotely unless you change the default settings.

	You can change the default session configurations by using the 
	$PSSessionConfigurationName preference variable. For more information, 
	see about_Preference_Variables.



  Viewing Session Configurations on the Local Computer

	To get the session configurations on your local computer, use the
	Get-PSSessionConfiguration cmdlet. 

	For example, type:

		C:\PS> get-pssessionconfiguration | format-list -property name, permission

		Name	 : microsoft.powershell
		Permission : BUILTIN\Administrators AccessAllowed

		Name	 : microsoft.powershell32
		Permission : BUILTIN\Administrators AccessAllowed


	You can also use the WS-Management provider in Windows PowerShell to view
	session configurations. The WS-Management provider creates a WSMAN: 
	drive in your session.

	In the WSMAN: drive, session configurations are in the Plugin node. 
	(All session configurations are in the Plugin node, but there are items
	in the Plugin node that are not session configurations.)

	For example, to view the session configurations on the local computer, 
	type:

		 C:\PS> dir wsman:\localhost\plugin\microsoft*

					WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin

		 Name					Type				 Keys
		 ----					----				 ----
		 microsoft.powershell	Container			{Name=microsoft.powershell}
		 microsoft.powershell32	Container			{Name=microsoft.powershell}


  Viewing Session Configurations on a Remote Computer

	To view the session configurations on a remote computer, use the 
	Connect-WSMan cmdlet to add a note for the remote computer to the WSMAN: 
	drive on your local computer, and then use the WSMAN: drive to view 
	the session configurations.

	For example, the following command adds a node for the Server01 remote
	computer to the WSMAN: drive on the local computer.

		C:\PS> connect-wsman server01.corp.fabrikam.com

	When the command is complete, you can navigate to the node for the
	Server01 computer to view the session configurations.
	
	For example:

		C:\PS> cd wsman:
	
		PS WSMan:\> dir 

		ComputerName								Type
		------------								----
		localhost									 Container
		server01.corp.fabrikam.com					Container

		PS WSMan:\> dir server01*\plugin\*


			 WSManConfig: Microsoft.WSMan.Management\WSMan::server01.corp.fabrikam.com\Plugin

		Name					Type			Keys
		----					----			----
		microsoft.powershell	Container	 {Name=microsoft.powershell}
		microsoft.powershell32	Container	 {Name=microsoft.powershell32}


  Changing the Security Descriptor of a Session Configuration

	By default, members of the Administrators group on the computer have
	Execute permission to the default session configurations, but you can
	change the security descriptors on the default session configurations
	and on any session configurations that you create.

	To give other users permission to connect to the computer remotely, 
	use the Set-PSSessionConfiguration cmdlet to add "Execute" permissions
	for those users to the security descriptors of the Microsoft.PowerShell
	and Microsoft.PowerShell32 session configurations.

	For example, the following command opens a property page that lets you
	change the security descriptor for the Microsoft.PowerShell default
	session configuration.

		C:\PS> set-pssessionConfiguration -name Microsoft.PowerShell -showSecurityDescriptorUI

	To deny everyone permission to all the session configurations on the
	computer, use the Disable-PSRemoting function or the
	Disable-PSSessionConfiguration cmdlet. For example, the following
	command adds a "Deny All" entry to all the session configurations on the
	computer.

		C:\PS> disable-psremoting


	To add a "Deny All" entry to a particular session configuration, use
	the Disable-PSSessionConfiguration cmdlet. For example, the following
	command adds a "Deny All" entry to the Microsoft.PowerShell session
	configuration.

		C:\PS> disable-pssessionConfiguration -name Microsoft.PowerShell


	To remove the "Deny All" entry from all the session configurations, use
	the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlet. For 
	example, the following command removes the "Deny All" entry from the
	default session configurations.

		C:\PS> enable-pssessionConfiguration -name Microsoft.Power*


	To make other changes to the security descriptor of a session 
	configuration, use the Set-PSSessionConfiguration cmdlet. Use the
	SecurityDescriptorSDDL parameter to submit an SDDL string value. Use the
	ShowSecurityDescriptorUI parameter to display a user interface property
	sheet that helps you to create a new SDDL.

	For example:

		C:\PS> set-pssessionConfiguration -name Microsoft.PowerShell -showSecurityDescriptorUI

	 

  Creating a New Session Configuration

	To create a new session configuration on the local computer, use the
	Register-PSSessionConfiguration cmdlet. To define the new session 
	configuration, you can use a C# assembly, a Window PowerShell script,
	and the parameters of the Register-PSSessionConfiguration cmdlet.

	For example, the following command creates a session configuration 
	that is identical the Microsoft.PowerShell session configuration, except
	that it limits the data received from a remote command to 20 megabytes
	(MB). (The default is 50 MB).

		c:\PS> register-psSessionConfiguration -name NewConfig --MaximumReceivedDataSizePerCommandMB 20

	When you create a session configuration, you can manage it by using the 
	other session configuration cmdlets, and it appears in the WSMAN: drive.

	For more information, see Register-PSSessionConfiguration.


	 
  Removing a Session Configuration

	To remove a session configuration from the local computer, use the 
	Unregister-PSSessionConfiguration cmdlet. For example, the following 
	command removes the NewConfig session configuration from the computer.

		c:\PS> unregister-psSessionConfiguration -name NewConfig

	For more information, see Unregister-PSSessionConfiguration.



  Selecting a Session Configuration

	To select a particular session configuration for a session, use the 
	ConfigurationName parameter of New-PSSession, Enter-PSSession, or
	Invoke-Command. 

	For example, this command uses the New-PSSession cmdlet to start a
	PSSession on the Server01 computer. The command uses the 
	ConfigurationName parameter to select the WithProfile configuration
	on the Server01 computer.

		C:\PS> new-pssession -computername Server01 -configurationName WithProfile

	This command will succeed only if the current user has permission to use
	the WithProfile session configuration or can supply the credentials of a
	user who has the required permissions.

	You can also use the $PSSessionConfigurationName preference variable to
	change the default session configuration on the computer. For more 
	information about the $PSSessionConfigurationName preference variable,
	see about_Preference_Variables.


SEE ALSO
	about_Preference_Variables
	about_PSSession
	about_Remote
	New-PSSession
	Disable-PSSessionConfiguration
	Enable-PSSessionConfiguration
	Get-PSSessionConfiguration
	Register-PSSessionConfiguration
	Set-PSSessionConfiguration
	Unregister-PSSessionConfiguration