about_Session_Configuration_Files
Short description
Describes session configuration files, which are used in a session configuration (also known as an "endpoint") to define the environment of sessions that use the session configuration.
Long description
A "session configuration file" is a text file with a .pssc file name extension that contains a hash table of session configuration properties and values. You can use a session configuration file to set the properties of a session configuration. Doing so defines the environment of any Windows PowerShell sessions that use that session configuration.
Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts.
A "session configuration" or "endpoint" is a collection of local computer settings that determine such things as which users can create sessions on the computer; which commands users can run in those sessions; and whether the session should run as a privileged virtual account. For more information about session configurations, see about_Session_Configurations.
Session configurations were introduced in Windows PowerShell 2.0, and session configuration files were introduced in Windows PowerShell 3.0. You must use Windows PowerShell 3.0 to include a session configuration file in a session configuration. However, users of Windows PowerShell 2.0 (and later) are affected by the settings in the session configuration.
Creating Custom Sessions
You can customize many features of a Windows PowerShell session by specifying session properties in a session configuration. You can customize a session by writing a C# program that defines a custom runspace, or you can use a session configuration file to define the properties of sessions created by using the session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program.
You can use a session configuration file to create items such as fully-functioning sessions for highly trusted users; locked-down sessions that allow minimal access; sessions designed for particular and that contain only the modules required for those tasks; and sessions where unprivileged users can only run specific commands as a privileged account.
In addition to that, you can manage whether users of the session can use Windows PowerShell language elements such as script blocks, or whether they can only run commands. You can manage the version of Windows PowerShell users can run in the session; manage which modules are imported into the session; and manage which cmdlets, functions, and aliases session users can run. When using the RoleDefinitions field, you can give users different capabilities in the session based on group membership.
For more information about RoleDefinitions and how to define this Value, see the help topic for the New-PSRoleCapabilityFile Cmdlet.
Creating a Session Configuration File
The easiest way to create a session configuration file is by using the New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses the correct syntax and format, and that automatically verifies many of the configuration file property values.
For detailed descriptions of the properties that you can set in a session configuration file, see the help topic for the New-PSSessionConfigurationFile cmdlet.
The following command creates a session configuration file that uses the default values. The resulting configuration file uses only the default values because no parameters other than the Path parameter (which specifies the file path) are included:
New-PSSessionConfigurationFile -Path .\Defaults.pssc
To view the new configuration file in your default text editor, use the following command:
Invoke-Item -Path .\Defaults.pssc
To create a session configuration for sessions in which user can run commands, but not use other elements of the Windows PowerShell language, type:
New-PSSessionConfigurationFile -LanguageMode NoLanguage
-Path .\NoLanguage.pssc
In the preceding command, setting the LanguageMode parameter to NoLanguage prevents users from doing such things as writing or running scripts, or using variables.
To create a session configuration for sessions in which users can use only Get cmdlets, type:
New-PSSessionConfigurationFile -VisibleCmdlets Get-*
-Path .\GetSessions.pssc
In the preceding example, setting the VisibleCmdlets parameter to Get-* limits users to cmdlets that have names that start with the string value "Get-".
To create a session configuration for sessions that run under a privileged virtual account instead of the user's credentials, type:
New-PSSessionConfigurationFile -RunAsVirtualAccount
-Path .\VirtualAccount.pssc
To create a session configuration for sessions in which the commands visible to the user are specified in a role capabilities file, type:
New-PSSessionConfigurationFile -RoleDefinitions
@{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }}
-Path .\Maintenance.pssc
Using a Session Configuration File
You can include a session configuration file when you create a session configuration or add you can add a file to the session configuration at a later time.
To include a session configuration file when creating a session configuration, use the Path parameter of the Register-PSSessionConfiguration cmdlet.
For example, the following command uses the NoLanguage.pssc file when it creates a NoLanguage session configuration.
Register-PSSessionConfiguration -Name NoLanguage
-Path .\NoLanguage.pssc
When a new NoLanguage session starts, users will only have access to Windows PowerShell commands.
To add a session configuration file to an existing session configuration, use the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any new sessions created with the specified session configuration. Note that the Set-PSSessionConfiguration cmdlet changes the session itself and does not modify the session configuration file.
For example, the following command adds the NoLanguage.pssc file to the LockedDown session configuration.
Set-PSSessionConfiguration -Name LockedDown
-Path .\NoLanguage.pssc
When users use the LockedDown session configuration to create a session, they will be able to run cmdlets but they will not be able to create or use variables, assign values, or use other Windows PowerShell language elements.
The following command uses the New-PSSession cmdlet to create a session on the computer Srv01 that uses the LockedDown session configuration, saving an object reference to the session in the $s variable. The ACL (access control list) of the session configuration determines who can use it to create a session.
$s = New-PSSession -ComputerName Srv01
-ConfigurationName LockedDown
Because the NoLanguage constraints were added to the LockedDown session configuration, users in LockedDown sessions will only be able to run Windows PowerShell commands and cmdlets. For example, the following two commands use the Invoke-Command cmdlet to run commands in the session referenced in the $s variable. The first command, which runs the Get-UICulture cmdlet and does not use any variables, succeeds. The second command, which gets the value of the $PSUICulture variable, fails.
Invoke-Command -Session $s {Get-UICulture}
en-US
Invoke-Command -Session $s {$PSUICulture}
The syntax is not supported by this runspace. This might be
because it is in no-language mode.
+ CategoryInfo : ParserError: ($PSUICulture:String) [],
ParseException
+ FullyQualifiedErrorId : ScriptsNotAllowed
Editing a Session Configuration File
All settings in a session configuration except for RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified by editing the session configuration file used by the session configuration. To do this, begin by locating the active copy of the session configuration file.
When you use a session configuration file in a session configuration, Windows PowerShell creates an active copy of the session configuration file and stores it in the $pshome\SessionConfig directory on the local computer.
The location of the active copy of a session configuration file is stored in the ConfigFilePath property of the session configuration object.
The following command gets the location of the session configuration file for the NoLanguage session configuration.
(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath
That command returns a file path similar to the following:
C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc
You can edit the .pssc file in any text editor. After the file is saved it will be employed by any new sessions that use the session configuration.
If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups settings, you must un-register the session configuration and re-register a session configuration file that includes the edited values.
Testing a Session Configuration File
Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session configuration files. That's important: if the file syntax and values are not valid users will not be able to use the session configuration to create a session.
For example, the following command tests the active session configuration file of the NoLanguage session configuration.
Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\
WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc
If the syntax and values in the configuration file are valid Test-PSSessionConfigurationFile returns True. If the syntax and values are not valid then the cmdlet returns False.
You can use Test-PSSessionConfigurationFile to test any session configuration file, including files that the New-PSSessionConfiguration cmdlet creates. For more information, see the help topic for the Test-PSSessionConfigurationFile cmdlet.
Removing a Session Configuration File
You cannot remove a session configuration file from a session configuration. However, you can replace the file with a new file that uses the default settings. This effectively cancels the settings used by the original configuration file.
To replace a session configuration file, create a new session configuration file that uses the default settings, then use the Set-PSSessionConfiguration cmdlet to replace the custom session configuration file with the new file.
For example, the following commands create a Default session configuration file and then replace the active session configuration file in the NoLanguage session configuration.
New-PSSessionConfigurationFile -Path .\Default.pssc
Set-PSSessionConfiguration -Name NoLanguage
-Path .\Default.pssc
When these commands finish, the NoLanguage session configuration will actually provide full language support (the default setting) for all sessions created with that session configuration.
Viewing the Properties of a Session Configuration The session configuration objects that represent session configurations using session configuration files have additional properties that make it easy to discover and analyze the session configuration. (Note that the type name shown below includes a formatted view definition.) You can view the properties by running the Get-PSSessionConfiguration cmdlet and piping the returned data to the Get-Member cmdlet:
Get-PSSessionConfiguration NoLanguage | Get-Member
TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands
#PSSessionConfiguration
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.O...
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Architecture NoteProperty System.String Archit...
Author NoteProperty System.String Author...
AutoRestart NoteProperty System.String AutoRe...
Capability NoteProperty System.Object[] Capa...
CompanyName NoteProperty System.String Compan...
configfilepath NoteProperty System.String config...
Copyright NoteProperty System.String Copyri...
Enabled NoteProperty System.String Enable...
ExactMatch NoteProperty System.String ExactM...
ExecutionPolicy NoteProperty System.String Execut...
Filename NoteProperty System.String Filena...
GUID NoteProperty System.String GUID=0...
ProcessIdleTimeoutSec NoteProperty System.String Proces...
IdleTimeoutms NoteProperty System.String IdleTi...
lang NoteProperty System.String lang=e...
LanguageMode NoteProperty System.String Langua...
MaxConcurrentCommandsPerShell NoteProperty System.String MaxCon...
MaxConcurrentUsers NoteProperty System.String MaxCon...
MaxIdleTimeoutms NoteProperty System.String MaxIdl...
MaxMemoryPerShellMB NoteProperty System.String MaxMem...
MaxProcessesPerShell NoteProperty System.String MaxPro...
MaxShells NoteProperty System.String MaxShells
MaxShellsPerUser NoteProperty System.String MaxShe...
Name NoteProperty System.String Name=N...
PSVersion NoteProperty System.String PSVersion
ResourceUri NoteProperty System.String Resour...
RunAsPassword NoteProperty System.String RunAsP...
RunAsUser NoteProperty System.String RunAsUser
SchemaVersion NoteProperty System.String Schema...
SDKVersion NoteProperty System.String SDKVer...
OutputBufferingMode NoteProperty System.String Output...
SessionType NoteProperty System.String Sessio...
UseSharedProcess NoteProperty System.String UseSha...
SupportsOptions NoteProperty System.String Suppor...
xmlns NoteProperty System.String xmlns=...
XmlRenderingType NoteProperty System.String XmlRen...
Permission ScriptProperty System.Object Permis...
These properties make it easy to search for specific session configurations. For example, you can use the ExecutionPolicy property to find a session configuration that supports sessions with the RemoteSigned execution policy. Note that, because the ExecutionPolicy property exists only on sessions that use session configuration files, the command might not return all qualifying session configurations.
Get-PSSessionConfiguration |
where {$_.ExecutionPolicy -eq "RemoteSigned"}
The following command gets session configurations in which the RunAsUser is the Exchange administrator.
Get-PSSessionConfiguration |
where {$_.RunAsUser -eq "Exchange01\Admin01"}
To view information about the role definitions associated with a configuration use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine the commands and environment available to specific users in specific endpoints.
Notes
Session configurations also support a type of session known as an "empty" session. An Empty session type enables you to create custom sessions with selected commands. If you do not add modules, functions, or scripts to an empty session, the session is limited to expressions and might not be of any practical use. The SessionType property tells you whether or not you are working with an empty session.
See also
- about_Session_Configurations
- New-PSRoleCapabilityFile
- New-PSSession
- Get-PSSessionCapability
- Disable-PSSessionConfiguration
- Enable-PSSessionConfiguration
- Get-PSSessionConfiguration
- Register-PSSessionConfiguration
- Set-PSSessionConfiguration
- Unregister-PSSessionConfiguration
- New-PSSessionConfigurationFile
- Test-PSSessionConfigurationFile