PowerShell Logo Small

about_Session_Configuration_Files



This is the built-in help made by Microsoft for the document 'about_Session_Configuration_Files', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

about_Session_Configuration_Files
TOPIC
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
(http://go.microsoft.com/fwlink/?LinkID=145152).

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:

PS C:\> New-PSSessionConfigurationFile -Path .\Defaults.pssc

To view the new configuration file in your default text editor,
use the following command:

PS C:\> 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:

PS C:\> 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:

PS C:\> 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:

PS C:\> 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:

PS C:\> 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.

PS C:\> 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.

PS C:\> 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.

PS C:\> $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.

PS C:\> Invoke-Command -Session $s {Get-UICulture}
en-US

PS C:\> 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.

PS C:\> (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.

PS C:\> 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.

PS C:\> New-PSSessionConfigurationFile -Path .\Default.pssc
PS C:\> 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:

PS C:\> 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.

PS C:\> Get-PSSessionConfiguration |
where {$_.ExecutionPolicy -eq "RemoteSigned"}

The following command gets session configurations in which the
RunAsUser is the Exchange administrator.

PS C:\> 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-PSSession
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
New-PSSessionConfigurationFile
Register-PSSessionConfiguration
Set-PSSessionConfiguration
Test-PSSessionConfigurationFile
Unregister-PSSessionConfiguration
Get-PSSessionCapability
New-PSRoleCapabilityFile