Edit

about_Session_Configuration_Files

  • Article

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

This information only applies to PowerShell running on Windows.

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 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 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 PowerShell language elements such as script blocks, or whether they can only run commands. You can manage the version of 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 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 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 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 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, 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