Usando JEAUsing JEA

Aplica-se a: Windows PowerShell 5.0Applies to: Windows PowerShell 5.0

Este tópico descreve as várias maneiras pelas quais você pode se conectar e usar um ponto de extremidade JEA.This topic describes the various ways you can connect to and use a JEA endpoint.

Usando o JEA interativamenteUsing JEA interactively

Se você estiver testando sua configuração JEA ou tiver tarefas simples para os usuários executarem, você poderá usar o JEA da mesma forma que faria com uma sessão de comunicação remota regular do PowerShell.If you are testing your JEA configuration or have simple tasks for users to perform, you can use JEA the same way you would a regular PowerShell remoting session. Para tarefas de comunicação remota complexas, é recomendável usar a comunicação remota implícita em vez disso, para facilitar para os usuários, permitindo que eles operem com os objetos de dados localmente.For complex remoting tasks, it is recommended to use implicit remoting instead to make it easier for your users by allowing users to operate with the data objects locally.

Para usar o JEA interativamente, você precisará:To use JEA interactively, you will need:

  • Do nome do computador ao qual está se conectando (pode ser o computador local)The name of the computer you are connecting to (can be the local machine)
  • Do nome do ponto de extremidade JEA registrado nesse computadorThe name of the JEA endpoint registered on that computer
  • Das credenciais para o computador que tem acesso ao ponto de extremidade JEACredentials for the computer that have access to the JEA endpoint

Com essas informações em mãos, você pode iniciar uma sessão JEA usando New-PSSession ou Enter-PSSession.With that information in hand, you can start a JEA session using New-PSSession or Enter-PSSession.

$nonAdminCred = Get-Credential
Enter-PSSession -ComputerName localhost -ConfigurationName JEAMaintenance -Credential $nonAdminCred

Se a conta na qual está conectado no momento tem acesso ao ponto de extremidade JEA, você poderá omitir o parâmetro -Credential.If the account you're currently logged in as has access to the JEA endpoint, you can omit the -Credential parameter.

Quando o prompt do PowerShell mudar para [localhost]: PS> você saberá que está interagindo com a sessão remota do JEA.When the PowerShell prompt changes to [localhost]: PS> you will know that you are now interacting with the remote JEA session. Você pode executar o Get-Command para verificar quais comandos estão disponíveis.You can run Get-Command to check which commands are available. Você precisará consultar o administrador para saber se há alguma restrição nos parâmetros disponíveis ou nos valores de parâmetro permitidos.You will need to consult with your administrator to learn if there are any restrictions on the available parameters or allowable parameter values.

Como lembrete, as sessões JEA operam no modo NoLanguage, portanto, algumas das maneiras que você normalmente usa o PowerShell podem não estar disponíveis.As a reminder, JEA sessions operate in NoLanguage mode, so some of the ways you typically use PowerShell may not be available. Por exemplo, você não pode usar variáveis para armazenar dados ou inspecionar as propriedades em objetos retornados de cmdlets.For instance, you cannot use variables to store data or inspect the properties on objects returned from cmdlets. Abaixo há um exemplo que mostra como você usa PowerShell atualmente e duas abordagens para obter o mesmo funcionamento de comando no modo NoLanguage.The below example shows an example of how you may be using PowerShell today, and two approaches to get the same command working in NoLanguage mode.

# Using variables in NoLanguage mode is disallowed, so the following will not work
# $vm = Get-VM -Name 'SQL01'
# Start-VM -VM $vm

# You can use pipes to pass data through to commands that accept input from the pipeline
Get-VM -Name 'SQL01' | Start-VM

# You can also wrap subcommands in parentheses and enter them inline as arguments
Start-VM -VM (Get-VM -Name 'SQL01')

# Better yet, use parameter sets that don't require extra data to be passed in when possible
Start-VM -VMName 'SQL01'

Para invocações de comando mais complexas que tornam essa abordagem difícil, considere o uso de comunicação remota implícita ou da criação de funções personalizadas que encapsulam a funcionalidade desejada.For more complex command invocations that make this approach difficult, consider using implicit remoting or creating custom functions that wrap the functionality you desire.

Usando o JEA com comunicação remota implícitaUsing JEA with implicit remoting

O PowerShell oferece suporte a um modelo de comunicação remota alternativo no qual é possível importar cmdlets do proxy de um computador remoto para o computador local e interagir com eles como se fossem comandos locais.PowerShell supports an alternative remoting model where you can import proxy cmdlets from a remote machine on your local computer and interact with them as if they were local commands. Esse modelo é chamado de comunicação remota implícita e é bem explicado nessa postagem de blog Hey, Scripting Guy!.This is called implicit remoting, and is explained well in this Hey, Scripting Guy! blog post. A comunicação remota implícita é particularmente útil ao trabalhar com o JEA porque permite que você trabalhe com os cmdlets do JEA em um modo de linguagem completa.Implicit remoting is particularly useful when working with JEA because it allows you to work with JEA cmdlets in a full language mode. Isso significa que é possível usar a conclusão de guia, variáveis, manipular objetos e até mesmo usar scripts locais para automatizar mais facilmente em um ponto de extremidade JEA.This means you can use tab completion, variables, manipulate objects, and even use local scripts to more easily automate against a JEA endpoint. Sempre que você invocar um comando de proxy, os dados serão enviados ao ponto de extremidade JEA no computador remoto e executados lá.Anytime you invoke a proxy command, the data will be sent to the JEA endpoint on the remote machine and executed there.

A comunicação remota implícita funciona ao importar cmdlets de uma sessão existente do PowerShell.Implicit remoting works by importing cmdlets from an existing PowerShell session. Opcionalmente, é possível colocar prefixos nos substantivos de cada cmdlet de proxy, com uma cadeia de caracteres à sua escolha, para distinguir quais comandos são do sistema remoto.You can optionally choose to prefix the nouns of each proxy cmdlet with a string of your choosing to distinguish which commands are for the remote system. Um módulo de script temporário contendo todos os comandos de proxy será criado e poderá ser usado enquanto durar a sessão local do PowerShell.A temporary script module containing all of the proxy commands will be created and can be used for the duration of your local PowerShell session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Import the entire PSSession and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA'

# Invoke "Get-Command" on the remote JEA endpoint using the proxy cmdlet
Get-JEACommand

Importante

Alguns sistemas poderão não ser capazes de importar uma sessão inteira do JEA devido a restrições em cmdlets padrão do JEA.Some systems may not be able to import an entire JEA session due to constraints in the default JEA cmdlets. Para contornar isso, importe apenas os comandos necessários da sessão JEA fornecendo explicitamente os nomes deles para o parâmetro -CommandName.To get around this, only import the commands you need from the JEA session by explicitly providing their names to the -CommandName parameter. Uma atualização futura solucionará o problema com a importação de sessões inteiras do JEA nos sistemas afetados.A future update will address the issue with importing entire JEA sessions on affected systems.

Se não for possível importar uma sessão JEA devido a restrições nos parâmetros padrão do JEA, você poderá seguir as etapas abaixo para filtrar os comandos padrão do conjunto importado.If you are unable to import a JEA session due to constraints on the default JEA parameters, you can follow the steps below to filter out the default commands from the imported set. Ainda será possível usar comandos como o Select-Object – você usará a versão local instalada no computador em vez da versão remota, na sessão JEA.You will still be able to use commands like Select-Object -- you'll just use the local version installed on your computer instead of the remote one in the JEA session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Get a list of all the commands on the JEA endpoint
$commands = Invoke-Command -Session $jeasession -ScriptBlock { Get-Command }

# Filter out the default cmdlets
$jeaDefaultCmdlets = 'Clear-Host', 'Exit-PSSession', 'Get-Command', 'Get-FormatData', 'Get-Help', 'Measure-Object', 'Out-Default', 'Select-Object'
$filteredCommands = $commands.Name | Where-Object { $jeaDefaultCmdlets -notcontains $_ }

# Import only commands explicitly added in role capabilities and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA' -CommandName $filteredCommands 

Também é possível manter os cmdlets do proxy da comunicação remota implícita, usando o Export-PSSession.You can also persist the proxied cmdlets from implicit remoting using Export-PSSession. Para obter mais informações sobre a comunicação remota implícita, consulte a documentação de ajuda para Import-PSSession e Import-Module.For more information about implicit remoting, check out the help documentation for Import-PSSession and Import-Module.

Usando o JEA de forma programáticaUsing JEA programatically

O JEA também pode ser usado em sistemas de automação e em aplicativos de usuário, como aplicativos de assistência técnica interna e sites da Web.JEA can also be used in automation systems and in user applications, such as in-house helpdesk apps and web sites. A abordagem é a mesma que a da criação de aplicativos que se comunicam com pontos de extremidade irrestritos do PowerShell, com a ressalva de que o programa deve estar ciente de que o JEA está limitando os comandos que podem ser executados na sessão remota.The approach is the same as that for building apps that talk to unconstrained PowerShell endpoints, with the caveat that the program should be aware that JEA is limiting the commands that can be run in the remote session.

Para tarefas simples e únicas, você pode usar Invoke-Command para executar um conjunto de comandos usando o JEA.For simple, one-off tasks, you can use Invoke-Command to run a set of commands using JEA.

Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Process; Get-Service }

Para verificar quais comandos estão disponíveis para uso quando você se conectar a uma sessão JEA, execute o Get-Command e percorra os resultados para verificar os parâmetros permitidos.To check which commands are available for use when you connect to a JEA session, run Get-Command and iterate through the results to check for the allowed parameters.

$allowedCommands = Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Command }
$allowedCommands | Where-Object { $_.CommandType -in 'Function', 'Cmdlet' } | Format-Table Name, Parameters

Se estiver compilando um aplicativo C#, você pode criar um runspace do PowerShell que se conecta a uma sessão JEA, especificando o nome da configuração em um objeto WSManConnectionInfo.If you are building a C# app, you can create a PowerShell runspace that connects to a JEA session by specifying the configuration name in a WSManConnectionInfo object.


// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
var creds        = // create a PSCredential object here (https://msdn.microsoft.com/en-us/library/system.management.automation.pscredential(v=vs.85).aspx)

WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
                    false,                 // Use SSL
                    computerName,          // Computer name
                    5985,                  // WSMan Port
                    "/wsman",              // WSMan Path
                    string.Format(CultureInfo.InvariantCulture, "http://schemas.microsoft.com/powershell/{0}", configName),  // Connection URI with config name
                    creds);                // Credentials
// Now, use the connection info to create a runspace where you can run the commands
using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
{
    // Open the runspace
    runspace.Open();

    using (PowerShell ps = PowerShell.Create())
    {
        // Set the PowerShell object to use the JEA runspace
        ps.Runspace = runspace;

        // Now you can add and invoke commands
        ps.AddCommand("Get-Command");
        foreach (var result in ps.Invoke())
        {
            Console.WriteLine(result);
        }
    }

    // Close the runspace
    runspace.Close();
}

Usando o JEA com o PowerShell DirectUsing JEA with PowerShell Direct

O Hyper-V no Windows 10 e o Windows Server 2016 oferecem o PowerShell Direct, um recurso que permite aos administradores do Hyper-V gerenciar máquinas virtuais com o PowerShell, independentemente da configuração da rede ou das configurações de gerenciamento remoto na máquina virtual.Hyper-V in Windows 10 and Windows Server 2016 offers PowerShell Direct, a feature which allows Hyper-V administrators to manage virtual machines with PowerShell regardless of the network configuration or remote management settings on the virtual machine.

É possível usar o PowerShell Direct com o JEA para conceder acesso limitado a um administrador de Hyper-V à sua VM, o que pode ser útil se a conectividade de rede com sua VM for perdida e for necessário que um administrador de datacenter corrija as configurações de rede.You can use PowerShell Direct with JEA to give a Hyper-V administrator limited access to your VM, which can be useful if you lose network connectivity to your VM and need a datacenter admin to fix the network settings.

Não é necessário nenhuma configuração adicional para usar o JEA com o PowerShell Direct, no entanto, o sistema operacional em execução na máquina virtual deve ser Windows 10 ou Windows Server 2016.No additional configuration is required to use JEA over PowerShell Direct, however the operating system running inside the virtual machine must be Windows 10 or Windows Server 2016. O administrador do Hyper-V pode se conectar ao ponto de extremidade JEA usando os parâmetros -VMName ou -VMId em cmdlets PSRemoting:The Hyper-V admin can connect to the JEA endpoint by using the -VMName or -VMId parameters on PSRemoting cmdlets:

# Entering a JEA session using PowerShell Direct when the VM name is unique
Enter-PSSession -VMName 'SQL01' -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

# Entering a JEA session using PowerShell Direct using VM ids
$vm = Get-VM -VMName 'MyVM' | Select-Object -First 1
Enter-PSSession -VMId $vm.VMId -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

É altamente recomendável que você crie um usuário local dedicado, sem outros direitos para gerenciar o sistema, para ser usado pelos administradores do Hyper-V.It is strongly recommended that you create a dedicated local user with no other rights to manage the system for your Hyper-V administrators to use. Lembre-se de que até mesmo um usuário sem privilégios pode fazer logon em um computador Windows por padrão e, inclusive, usar o PowerShell irrestrito.Remember that even an unprivileged user can still log into a Windows machine by default, including using unconstrained PowerShell. Isso lhes permite navegar (em parte do) sistema de arquivos e saber mais sobre o ambiente do sistema operacional.That will allow them to browse (some of) the file system and learn more about your OS environment. Para bloquear um administrador do Hyper-V para somente acessar uma VM usando o PowerShell Direct com JEA, você precisará negar direitos de logon local à conta JEA do administrador do Hyper-V.To lock down a Hyper-V administrator to only access a VM using PowerShell Direct with JEA, you will need to deny local logon rights to the Hyper-V admin's JEA account.