about_Session_Configuration_Files

Artículo
04/13/2023

Descripción breve

Describe los archivos de configuración de sesión, que se usan en una configuración de sesión (también conocido como "punto de conexión") para definir el entorno de las sesiones que usan la configuración de sesión.

Descripción larga

Esta información solo se aplica a PowerShell que se ejecuta en Windows.

Un "archivo de configuración de sesión" es un archivo de texto con una extensión de nombre de archivo .pssc que contiene una tabla hash de propiedades y valores de configuración de sesión. Puede usar un archivo de configuración de sesión para establecer las propiedades de una configuración de sesión. Al hacerlo, se define el entorno de las sesiones de PowerShell que usan esa configuración de sesión.

Los archivos de configuración de sesión facilitan la creación de configuraciones de sesión personalizadas sin usar scripts ni ensamblados de C# complejos.

Una "configuración de sesión" o "punto de conexión" es una colección de configuraciones de equipo local que determinan aspectos como los que los usuarios pueden crear sesiones en el equipo; qué comandos pueden ejecutar los usuarios en esas sesiones; y si la sesión debe ejecutarse como una cuenta virtual con privilegios. Para más información sobre las configuraciones de sesión, vea about_Session_Configurations.

Las configuraciones de sesión se introdujeron en Windows PowerShell 2.0 y los archivos de configuración de sesión se introdujeron en Windows PowerShell 3.0. Debe usar Windows PowerShell 3.0 para incluir un archivo de configuración de sesión en una configuración de sesión. Sin embargo, los usuarios de Windows PowerShell 2.0 (y versiones posteriores) se ven afectados por la configuración de la sesión.

Creación de sesiones personalizadas

Puede personalizar muchas características de una sesión de PowerShell especificando las propiedades de sesión en una configuración de sesión. Puede personalizar una sesión escribiendo un programa de C# que defina un espacio de ejecución personalizado o puede usar un archivo de configuración de sesión para definir las propiedades de las sesiones creadas mediante la configuración de sesión. Como regla general, es más fácil usar el archivo de configuración de sesión que escribir un programa de C#.

Puede usar un archivo de configuración de sesión para crear elementos como sesiones de funcionamiento completo para usuarios de alta confianza; sesiones bloqueadas que permiten el acceso mínimo; sesiones diseñadas para determinadas tareas y que contienen solo los módulos necesarios para esas tareas; y las sesiones en las que los usuarios sin privilegios solo pueden ejecutar comandos específicos como una cuenta con privilegios.

Además de eso, puede administrar si los usuarios de la sesión pueden usar elementos de lenguaje de PowerShell como bloques de script o si solo pueden ejecutar comandos. Puede administrar la versión de los usuarios de PowerShell que se puede ejecutar en la sesión; administrar qué módulos se importan en la sesión; y administre qué cmdlets, funciones y alias pueden ejecutar los usuarios de sesión. Al usar el campo RoleDefinitions, puede proporcionar a los usuarios diferentes funcionalidades en la sesión en función de la pertenencia a grupos.

Para obtener más información sobre RoleDefinitions y cómo definir este valor, consulte el tema de ayuda del cmdlet New-PSRoleCapabilityFile.

Creación de un archivo de configuración de sesión

La manera más fácil de crear un archivo de configuración de sesión es mediante el cmdlet New-PSSessionConfigurationFile. Este cmdlet genera un archivo que usa la sintaxis y el formato correctos, y que comprueba automáticamente muchos de los valores de propiedad del archivo de configuración.

Para obtener descripciones detalladas de las propiedades que puede establecer en un archivo de configuración de sesión, consulte el tema de ayuda del cmdlet New-PSSessionConfigurationFile.

El comando siguiente crea un archivo de configuración de sesión que usa los valores predeterminados. El archivo de configuración resultante usa solo los valores predeterminados porque no se incluyen parámetros distintos del parámetro Path (que especifica la ruta de acceso del archivo):

New-PSSessionConfigurationFile -Path .\Defaults.pssc

Para ver el nuevo archivo de configuración en el editor de texto predeterminado, use el siguiente comando:

Invoke-Item -Path .\Defaults.pssc

Para crear una configuración de sesión para sesiones en las que el usuario puede ejecutar comandos, pero no usar otros elementos del lenguaje de PowerShell, escriba:

New-PSSessionConfigurationFile -LanguageMode NoLanguage
-Path .\NoLanguage.pssc

En el comando anterior, establecer el parámetro LanguageMode en NoLanguage impide que los usuarios realicen acciones como escribir o ejecutar scripts, o usar variables.

Para crear una configuración de sesión para sesiones en las que los usuarios solo pueden usar cmdlets Get, escriba:

New-PSSessionConfigurationFile -VisibleCmdlets Get-*
-Path .\GetSessions.pssc

En el ejemplo anterior, al establecer el parámetro VisibleCmdlets en Get-* se limitan los usuarios a los cmdlets que tienen nombres que comienzan por el valor de cadena "Get-".

Para crear una configuración de sesión para las sesiones que se ejecutan en una cuenta virtual con privilegios en lugar de las credenciales del usuario, escriba:

New-PSSessionConfigurationFile -RunAsVirtualAccount
-Path .\VirtualAccount.pssc

Para crear una configuración de sesión para sesiones en las que los comandos visibles para el usuario se especifican en un archivo de funcionalidades de rol, escriba:

New-PSSessionConfigurationFile -RoleDefinitions
@{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }}
-Path .\Maintenance.pssc

Uso de un archivo de configuración de sesión

Puede incluir un archivo de configuración de sesión al crear una configuración de sesión o agregar un archivo a la configuración de sesión más adelante.

Para incluir un archivo de configuración de sesión al crear una configuración de sesión, use el parámetro Path del cmdlet Register-PSSessionConfiguration.

Por ejemplo, el comando siguiente usa el archivo NoLanguage.pssc cuando crea una configuración de sesión NoLanguage.

Register-PSSessionConfiguration -Name NoLanguage
-Path .\NoLanguage.pssc

Cuando se inicia una nueva sesión de NoLanguage, los usuarios solo tendrán acceso a los comandos de PowerShell.

Para agregar un archivo de configuración de sesión a una configuración de sesión existente, use el cmdlet Set-PSSessionConfiguration y el parámetro Path. Esto afecta a las nuevas sesiones creadas con la configuración de sesión especificada. Tenga en cuenta que el cmdlet Set-PSSessionConfiguration cambia la propia sesión y no modifica el archivo de configuración de sesión.

Por ejemplo, el comando siguiente agrega el archivo NoLanguage.pssc a la configuración de sesión LockedDown.

Set-PSSessionConfiguration -Name LockedDown
-Path .\NoLanguage.pssc

Cuando los usuarios usan la configuración de sesión LockedDown para crear una sesión, podrán ejecutar cmdlets, pero no podrán crear ni usar variables, asignar valores ni usar otros elementos de lenguaje de PowerShell.

El siguiente comando usa el cmdlet New-PSSession para crear una sesión en el equipo Srv01 que usa la configuración de sesión LockedDown, guardando una referencia de objeto a la sesión en la variable $s. La ACL (lista de control de acceso) de la configuración de sesión determina quién puede usarlo para crear una sesión.

$s = New-PSSession -ComputerName Srv01
-ConfigurationName LockedDown

Dado que las restricciones NoLanguage se agregaron a la configuración de sesión LockedDown, los usuarios de sesiones LockedDown solo podrán ejecutar comandos y cmdlets de PowerShell. Por ejemplo, los dos comandos siguientes usan el cmdlet Invoke-Command para ejecutar comandos en la sesión a la que se hace referencia en la variable $s. El primer comando, que ejecuta el cmdlet Get-UICulture y no usa ninguna variable, se realiza correctamente. Se produce un error en el segundo comando, que obtiene el valor de la variable $PSUICulture.

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

Edición de un archivo de configuración de sesión

Todas las opciones de una configuración de sesión excepto RunAsVirtualAccount y RunAsVirtualAccountGroups se pueden modificar editando el archivo de configuración de sesión usado por la configuración de sesión. Para ello, empiece por buscar la copia activa del archivo de configuración de sesión.

Cuando se usa un archivo de configuración de sesión en una configuración de sesión, PowerShell crea una copia activa del archivo de configuración de sesión y la almacena en el directorio $pshome\SessionConfig del equipo local.

La ubicación de la copia activa de un archivo de configuración de sesión se almacena en la propiedad ConfigFilePath del objeto de configuración de sesión.

El siguiente comando obtiene la ubicación del archivo de configuración de sesión para la configuración de sesión noLanguage.

(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath

Ese comando devuelve una ruta de acceso de archivo similar a la siguiente:

C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc

Puede editar el archivo .pssc en cualquier editor de texto. Después de guardar el archivo, las sesiones nuevas que usen la configuración de sesión emplearán el archivo.

Si necesita modificar la configuración de RunAsVirtualAccount o RunAsVirtualAccountGroups, debe anular el registro de la configuración de sesión y volver a registrar un archivo de configuración de sesión que incluya los valores editados.

Probar un archivo de configuración de sesión

Use el cmdlet Test-PSSessionConfigurationFile para probar los archivos de configuración de sesión editados manualmente. Eso es importante: si la sintaxis del archivo y los valores no son usuarios válidos no podrán usar la configuración de sesión para crear una sesión.

Por ejemplo, el siguiente comando prueba el archivo de configuración de sesión activo de la configuración de sesión NoLanguage.

Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\
WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc

Si la sintaxis y los valores del archivo de configuración son válidos Test-PSSessionConfigurationFile devuelve True. Si la sintaxis y los valores no son válidos, el cmdlet devuelve False.

Puede usar Test-PSSessionConfigurationFile para probar cualquier archivo de configuración de sesión, incluidos los archivos que crea el cmdlet New-PSSessionConfiguration. Para obtener más información, consulte el tema de ayuda del cmdlet Test-PSSessionConfigurationFile.

Quitar un archivo de configuración de sesión

No se puede quitar un archivo de configuración de sesión de una configuración de sesión. Sin embargo, puede reemplazar el archivo por un nuevo archivo que use la configuración predeterminada. Esto cancela eficazmente la configuración utilizada por el archivo de configuración original.

Para reemplazar un archivo de configuración de sesión, cree un nuevo archivo de configuración de sesión que use la configuración predeterminada y, a continuación, use el cmdlet Set-PSSessionConfiguration para reemplazar el archivo de configuración de sesión personalizado por el nuevo archivo.

Por ejemplo, los siguientes comandos crean un archivo de configuración de sesión predeterminado y, a continuación, reemplazan el archivo de configuración de sesión activa en la configuración de sesión noLanguage.

New-PSSessionConfigurationFile -Path .\Default.pssc
Set-PSSessionConfiguration -Name NoLanguage
-Path .\Default.pssc

Cuando finalicen estos comandos, la configuración de la sesión NoLanguage proporcionará realmente compatibilidad completa con el idioma (la configuración predeterminada) para todas las sesiones creadas con esa configuración de sesión.

Ver las propiedades de una configuración de sesión Los objetos de configuración de sesión que representan configuraciones de sesión mediante archivos de configuración de sesión tienen propiedades adicionales que facilitan la detección y el análisis de la configuración de la sesión. (Tenga en cuenta que el nombre de tipo que se muestra a continuación incluye una definición de vista con formato). Para ver las propiedades, ejecute el cmdlet Get-PSSessionConfiguration y canalice los datos devueltos al cmdlet Get-Member:

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...

Estas propiedades facilitan la búsqueda de configuraciones de sesión específicas. Por ejemplo, puede usar la propiedad ExecutionPolicy para buscar una configuración de sesión que admita sesiones con la directiva de ejecución RemoteSigned. Tenga en cuenta que, dado que la propiedad ExecutionPolicy solo existe en sesiones que usan archivos de configuración de sesión, es posible que el comando no devuelva todas las configuraciones de sesión aptas.

Get-PSSessionConfiguration |
where {$_.ExecutionPolicy -eq "RemoteSigned"}

El siguiente comando obtiene configuraciones de sesión en las que RunAsUser es el administrador de Exchange.

 Get-PSSessionConfiguration |
where {$_.RunAsUser -eq "Exchange01\Admin01"}

Para ver información sobre las definiciones de roles asociadas a una configuración, use el cmdlet Get-PSSessionCapability. Este cmdlet le permite determinar los comandos y el entorno disponibles para usuarios específicos en puntos de conexión específicos.

Notas

Las configuraciones de sesión también admiten un tipo de sesión conocido como sesión "vacía". Un tipo de sesión vacío le permite crear sesiones personalizadas con comandos seleccionados. Si no agrega módulos, funciones o scripts a una sesión vacía, la sesión se limita a expresiones y podría no ser de ningún uso práctico. La propiedad SessionType indica si está trabajando o no con una sesión vacía.