about_Session_Configuration_Files

Artigo
04/13/2023

Descrição breve

Descreve os arquivos de configuração de sessão, que são usados em uma configuração de sessão (também conhecida como "ponto de extremidade") para definir o ambiente de sessões que usam a configuração de sessão.

Descrição longa

Essas informações se aplicam apenas ao PowerShell em execução no Windows.

Um "arquivo de configuração de sessão" é um arquivo de texto com uma extensão de nome de arquivo .pssc que contém uma tabela de hash de propriedades e valores de configuração de sessão. Você pode usar um arquivo de configuração de sessão para definir as propriedades de uma configuração de sessão. Isso define o ambiente de todas as sessões do PowerShell que usam essa configuração de sessão.

Os arquivos de configuração de sessão facilitam a criação de configurações de sessão personalizadas sem usar assemblies ou scripts C# complexos.

Uma "configuração de sessão" ou "ponto de extremidade" é uma coleção de configurações do computador local que determinam coisas como quais usuários podem criar sessões no computador; quais comandos os usuários podem executar nessas sessões; e se a sessão deve ser executada como uma conta virtual privilegiada. Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

As configurações de sessão foram introduzidas no Windows PowerShell 2.0 e os arquivos de configuração de sessão foram introduzidos no Windows PowerShell 3.0. Você deve usar o Windows PowerShell 3.0 para incluir um arquivo de configuração de sessão em uma configuração de sessão. No entanto, os usuários do Windows PowerShell 2.0 (e posterior) são afetados pelas configurações na configuração da sessão.

Criando sessões personalizadas

Você pode personalizar muitos recursos de uma sessão do PowerShell especificando propriedades de sessão em uma configuração de sessão. Você pode personalizar uma sessão escrevendo um programa C# que define um runspace personalizado ou pode usar um arquivo de configuração de sessão para definir as propriedades das sessões criadas usando a configuração da sessão. Como regra geral, é mais fácil usar o arquivo de configuração de sessão do que escrever um programa C#.

Você pode usar um arquivo de configuração de sessão para criar itens como sessões totalmente funcionais para usuários altamente confiáveis; sessões bloqueadas que permitem acesso mínimo; sessões destinadas a um determinado efeito e que contenham apenas os módulos necessários para essas tarefas; e sessões em que usuários sem privilégios só podem executar comandos específicos como uma conta privilegiada.

Além disso, você pode gerenciar se os usuários da sessão podem usar elementos de linguagem do PowerShell, como blocos de script, ou se eles só podem executar comandos. Você pode gerenciar a versão do PowerShell que os usuários podem executar na sessão; gerenciar quais módulos são importados para a sessão; e gerenciar quais cmdlets, funções e aliases os usuários da sessão podem executar. Ao usar o campo RoleDefinitions, você pode fornecer aos usuários diferentes recursos na sessão com base na associação ao grupo.

Para obter mais informações sobre RoleDefinitions e como definir esse valor, consulte o tópico de ajuda do cmdlet New-PSRoleCapabilityFile.

Criando um arquivo de configuração de sessão

A maneira mais fácil de criar um arquivo de configuração de sessão é usando o cmdlet New-PSSessionConfigurationFile. Esse cmdlet gera um arquivo que usa a sintaxe e o formato corretos e que verifica automaticamente muitos dos valores de propriedade do arquivo de configuração.

Para obter descrições detalhadas das propriedades que você pode definir em um arquivo de configuração de sessão, consulte o tópico de ajuda do cmdlet New-PSSessionConfigurationFile.

O comando a seguir cria um arquivo de configuração de sessão que usa os valores padrão. O arquivo de configuração resultante usa apenas os valores padrão porque nenhum parâmetro diferente do parâmetro Path (que especifica o caminho do arquivo) está incluído:

New-PSSessionConfigurationFile -Path .\Defaults.pssc

Para exibir o novo arquivo de configuração em seu editor de texto padrão, use o seguinte comando:

Invoke-Item -Path .\Defaults.pssc

Para criar uma configuração de sessão para sessões nas quais o usuário pode executar comandos, mas não usar outros elementos da linguagem do PowerShell, digite:

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

No comando anterior, definir o parâmetro LanguageMode como NoLanguage impede que os usuários façam coisas como escrever ou executar scripts ou usar variáveis.

Para criar uma configuração de sessão para sessões nas quais os usuários podem usar apenas cmdlets Get, digite:

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

No exemplo anterior, definir o parâmetro VisibleCmdlets como Get-* limita os usuários a cmdlets que têm nomes que começam com o valor de cadeia de caracteres "Get-".

Para criar uma configuração de sessão para sessões executadas em uma conta virtual privilegiada em vez das credenciais do usuário, digite:

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

Para criar uma configuração de sessão para sessões nas quais os comandos visíveis para o usuário são especificados em um arquivo de recursos de função, digite:

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

Usando um arquivo de configuração de sessão

Você pode incluir um arquivo de configuração de sessão ao criar uma configuração de sessão ou adicionar um arquivo à configuração de sessão posteriormente.

Para incluir um arquivo de configuração de sessão ao criar uma configuração de sessão, use o parâmetro Path do cmdlet Register-PSSessionConfiguration.

Por exemplo, o comando a seguir usa o arquivo NoLanguage.pssc ao criar uma configuração de sessão NoLanguage.

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

Quando uma nova sessão NoLanguage for iniciada, os usuários terão acesso apenas aos comandos do PowerShell.

Para adicionar um arquivo de configuração de sessão a uma configuração de sessão existente, use o cmdlet Set-PSSessionConfiguration e o parâmetro Path. Isso afeta todas as novas sessões criadas com a configuração de sessão especificada. Observe que o cmdlet Set-PSSessionConfiguration altera a própria sessão e não modifica o arquivo de configuração da sessão.

Por exemplo, o comando a seguir adiciona o arquivo NoLanguage.pssc à configuração da sessão LockedDown.

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

Quando os usuários usam a configuração de sessão LockedDown para criar uma sessão, eles poderão executar cmdlets, mas não poderão criar ou usar variáveis, atribuir valores ou usar outros elementos de linguagem do PowerShell.

O comando a seguir usa o cmdlet New-PSSession para criar uma sessão no computador Srv01 que usa a configuração de sessão LockedDown, salvando uma referência de objeto para a sessão na variável $s. A ACL (lista de controle de acesso) da configuração da sessão determina quem pode usá-la para criar uma sessão.

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

Como as restrições NoLanguage foram adicionadas à configuração da sessão LockedDown, os usuários em sessões LockedDown só poderão executar comandos e cmdlets do PowerShell. Por exemplo, os dois comandos a seguir usam o cmdlet Invoke-Command para executar comandos na sessão referenciada na variável $s. O primeiro comando, que executa o cmdlet Get-UICulture e não usa nenhuma variável, é bem-sucedido. O segundo comando, que obtém o valor da variável $PSUICulture, falha.

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

Editando um arquivo de configuração de sessão

Todas as configurações em uma configuração de sessão, exceto RunAsVirtualAccount e RunAsVirtualAccountGroups, podem ser modificadas editando o arquivo de configuração de sessão usado pela configuração de sessão. Para fazer isso, comece localizando a cópia ativa do arquivo de configuração da sessão.

Quando você usa um arquivo de configuração de sessão em uma configuração de sessão, o PowerShell cria uma cópia ativa do arquivo de configuração de sessão e a armazena no diretório $pshome\SessionConfig no computador local.

O local da cópia ativa de um arquivo de configuração de sessão é armazenado na propriedade ConfigFilePath do objeto de configuração de sessão.

O comando a seguir obtém o local do arquivo de configuração de sessão para a configuração de sessão NoLanguage.

(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath

Esse comando retorna um caminho de arquivo semelhante ao seguinte:

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

Você pode editar o arquivo .pssc em qualquer editor de texto. Depois que o arquivo for salvo, ele será empregado por todas as novas sessões que usam a configuração da sessão.

Se você precisar modificar as configurações RunAsVirtualAccount ou RunAsVirtualAccountGroups, deverá cancelar o registro da configuração da sessão e registrar novamente um arquivo de configuração de sessão que inclua os valores editados.

Testando um arquivo de configuração de sessão

Use o cmdlet Test-PSSessionConfigurationFile para testar arquivos de configuração de sessão editados manualmente. Isso é importante: se a sintaxe e os valores do arquivo não forem válidos, os usuários não poderão usar a configuração da sessão para criar uma sessão.

Por exemplo, o comando a seguir testa o arquivo de configuração de sessão ativo da configuração de sessão NoLanguage.

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

Se a sintaxe e os valores no arquivo de configuração forem válidos, Test-PSSessionConfigurationFile retornará True. Se a sintaxe e os valores não forem válidos, o cmdlet retornará False.

Você pode usar Test-PSSessionConfigurationFile para testar qualquer arquivo de configuração de sessão, incluindo arquivos criados pelo cmdlet New-PSSessionConfiguration. Para obter mais informações, consulte o tópico de ajuda do cmdlet Test-PSSessionConfigurationFile.

Removendo um arquivo de configuração de sessão

Não é possível remover um arquivo de configuração de sessão de uma configuração de sessão. No entanto, você pode substituir o arquivo por um novo arquivo que use as configurações padrão. Isso cancela efetivamente as configurações usadas pelo arquivo de configuração original.

Para substituir um arquivo de configuração de sessão, crie um novo arquivo de configuração de sessão que use as configurações padrão e use o cmdlet Set-PSSessionConfiguration para substituir o arquivo de configuração de sessão personalizado pelo novo arquivo.

Por exemplo, os comandos a seguir criam um arquivo de configuração de sessão padrão e, em seguida, substituem o arquivo de configuração de sessão ativo na configuração de sessão NoLanguage.

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

Quando esses comandos forem concluídos, a configuração da sessão NoLanguage fornecerá suporte total ao idioma (a configuração padrão) para todas as sessões criadas com essa configuração de sessão.

Visualizando as propriedades de uma configuração de sessão Os objetos de configuração de sessão que representam configurações de sessão usando arquivos de configuração de sessão têm propriedades adicionais que facilitam a descoberta e a análise da configuração de sessão. (Observe que o nome do tipo mostrado abaixo inclui uma definição de exibição formatada.) Você pode exibir as propriedades executando o cmdlet Get-PSSessionConfiguration e canalizando os dados retornados para o 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...

Essas propriedades facilitam a pesquisa de configurações de sessão específicas. Por exemplo, você pode usar a propriedade ExecutionPolicy para localizar uma configuração de sessão que ofereça suporte a sessões com a política de execução RemoteSigned. Observe que, como a propriedade ExecutionPolicy existe apenas em sessões que usam arquivos de configuração de sessão, o comando pode não retornar todas as configurações de sessão qualificadas.

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

O comando a seguir obtém configurações de sessão nas quais o RunAsUser é o administrador do Exchange.

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

Para exibir informações sobre as definições de função associadas a uma configuração, use o cmdlet Get-PSSessionCapability. Esse cmdlet permite que você determine os comandos e o ambiente disponíveis para usuários específicos em pontos de extremidade específicos.

Observações

As configurações de sessão também suportam um tipo de sessão conhecido como sessão "vazia". Um tipo de sessão Vazio permite que você crie sessões personalizadas com comandos selecionados. Se você não adicionar módulos, funções ou scripts a uma sessão vazia, a sessão será limitada a expressões e poderá não ter nenhum uso prático. A propriedade SessionType informa se você está ou não trabalhando com uma sessão vazia.

Compartilhar via