Enable-PSRemoting

  • Referência
Módulo:
Microsoft.PowerShell.Core

Configura o computador para receber comandos remotos.

Syntax

Enable-PSRemoting
      [-Force]
      [-SkipNetworkProfileCheck]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Description

Este cmdlet só está disponível na plataforma Windows.

O Enable-PSRemoting cmdlet configura o computador para receber comandos remotos do PowerShell que são enviados usando a tecnologia WS-Management. Atualmente, a comunicação remota do PowerShell baseada em WS-Management é suportada apenas na plataforma Windows.

A comunicação remota do PowerShell é habilitada por padrão em plataformas Windows Server. Você pode usar Enable-PSRemoting para habilitar a comunicação remota do PowerShell em outras versões com suporte do Windows e para reativar a comunicação remota se ela for desabilitada.

Você tem que executar este comando apenas uma vez em cada computador que receberá comandos. Não é necessário executá-lo em computadores que apenas enviam comandos. Como a configuração inicia os ouvintes para aceitar conexões remotas, é prudente executá-la apenas onde for necessária.

Habilitar a comunicação remota do PowerShell em versões de cliente do Windows quando o computador está em uma rede pública normalmente não é permitido, mas você pode ignorar essa restrição usando o parâmetro SkipNetworkProfileCheck . Para obter mais informações, consulte a descrição do parâmetro SkipNetworkProfileCheck .

Várias instalações do PowerShell podem existir lado a lado em um único computador. A execução Enable-PSRemoting configurará um ponto de extremidade remoto para a versão de instalação específica na qual você está executando o cmdlet. Portanto, se você executar Enable-PSRemoting durante a execução do PowerShell 6.2, será configurado um ponto de extremidade remoto que executa o PowerShell 6.2. Se você executar Enable-PSRemoting durante a execução do PowerShell 7-preview, será configurado um ponto de extremidade remoto que executa o PowerShell 7-preview.

Enable-PSRemoting Cria duas configurações de ponto de extremidade remoto conforme necessário. Se as configurações de ponto de extremidade já existirem, elas serão simplesmente garantidas para serem habilitadas. As configurações criadas são idênticas, mas têm nomes diferentes. Um deles terá um nome simples correspondente à versão do PowerShell que hospeda a sessão. O outro nome de configuração contém informações mais detalhadas sobre a versão do PowerShell que hospeda a sessão. Por exemplo, ao executar Enable-PSRemoting no PowerShell 6.2, você obterá dois pontos de extremidade configurados chamados PowerShell.6, PowerShell.6.2.2. Isso permite que você crie uma conexão com a versão mais recente do host do PowerShell 6 usando o nome simples PowerShell.6. Ou você pode se conectar a uma versão de host específica do PowerShell usando o nome mais longo PowerShell.6.2.2.

Para usar os pontos de extremidade de comunicação remota recém-habilitados, você deve especificá-los pelo nome com o parâmetro ConfigurationName ao criar uma conexão remota usando os Invoke-Commandcmdlets ,New-PSSession.Enter-PSSession Para obter mais informações, consulte o Exemplo 4.

O Enable-PSRemoting cmdlet executa as seguintes operações:

  • Executa o cmdlet Set-WSManQuickConfig , que executa as seguintes tarefas:
    • Inicia o serviço WinRM.
    • Define o tipo de inicialização no serviço WinRM como Automático.
    • Cria um ouvinte para aceitar solicitações em qualquer endereço IP.
    • Habilita uma exceção de firewall para comunicações WS-Management.
    • Cria as configurações de ponto de extremidade de sessão simples e de nome longo, se necessário.
    • Permite todas as configurações de sessão.
    • Altera o descritor de segurança de todas as configurações de sessão para permitir o acesso remoto.
  • Reinicia o serviço WinRM para tornar efetivas as alterações anteriores.

Para executar esse cmdlet na plataforma Windows, inicie o PowerShell usando a opção Executar como administrador. Este cmdlet não está disponível nas versões Linux ou MacOS do PowerShell.

Atenção

Este cmdlet não afeta as configurações de ponto de extremidade remoto criadas pelo Windows PowerShell. Ele afeta apenas os pontos de extremidade criados com o PowerShell versão 6 e superior. Para habilitar e desabilitar pontos de extremidade remotos do PowerShell hospedados pelo Windows PowerShell, execute o cmdlet de Enable-PSRemoting dentro de uma sessão do Windows PowerShell.

Exemplos

Exemplo 1: Configurar um computador para receber comandos remotos

Este comando configura o computador para receber comandos remotos.

Enable-PSRemoting

WARNING: PowerShell remoting has been enabled only for PowerShell Core configurations and
does not affect Windows PowerShell remoting configurations. Run this cmdlet in Windows
PowerShell to affect all PowerShell remoting configurations.

Exemplo 2: Configurar um computador para receber comandos remotos sem um prompt de confirmação

Este comando configura o computador para receber comandos remotos. O parâmetro Force suprime os prompts do usuário.

Enable-PSRemoting -Force

WARNING: PowerShell remoting has been enabled only for PowerShell Core configurations and
does not affect Windows PowerShell remoting configurations. Run this cmdlet in Windows
PowerShell to affect all PowerShell remoting configurations.

Exemplo 3: Permitir acesso remoto em clientes

Este exemplo mostra como permitir o acesso remoto de redes públicas em versões cliente do sistema operacional Windows. O nome da regra de firewall pode ser diferente para diferentes versões do Windows. Use Get-NetFirewallRule para ver uma lista de regras. Antes de habilitar a regra de firewall, exiba as configurações de segurança na regra para verificar se a configuração é apropriada para seu ambiente.

Get-NetFirewallRule -Name 'WINRM*' | Select-Object -Property Name

Name
----
WINRM-HTTP-In-TCP-NoScope
WINRM-HTTP-In-TCP
WINRM-HTTP-Compat-In-TCP-NoScope
WINRM-HTTP-Compat-In-TCP

Enable-PSRemoting -SkipNetworkProfileCheck -Force
Set-NetFirewallRule -Name 'WINRM-HTTP-In-TCP' -RemoteAddress Any

Por padrão, Enable-PSRemoting cria regras de rede que permitem o acesso remoto de redes privadas e de domínio. O comando usa o parâmetro SkipNetworkProfileCheck para permitir o acesso remoto de redes públicas na mesma sub-rede local. O comando especifica o parâmetro Force para suprimir mensagens de confirmação.

O parâmetro SkipNetworkProfileCheck não afeta as versões de servidor do sistema operacional Windows, que permitem o acesso remoto de redes públicas na mesma sub-rede local por padrão.

O Set-NetFirewallRule cmdlet no módulo NetSecurity adiciona uma regra de firewall que permite o acesso remoto de redes públicas a partir de qualquer local remoto. Isso inclui locais em diferentes sub-redes.

Exemplo 4: Criar uma sessão remota para a configuração de ponto de extremidade recém-habilitada

Este exemplo mostra como habilitar a comunicação remota do PowerShell em um computador, localizar os nomes de ponto de extremidade configurados e criar uma sessão remota para um dos pontos de extremidade.

O primeiro comando habilita a comunicação remota do PowerShell no computador.

O segundo comando lista as configurações de ponto de extremidade.

O terceiro comando cria uma sessão remota do PowerShell para a mesma máquina, especificando o ponto de extremidade PowerShell.7 pelo nome. A sessão remota será hospedada com a versão mais recente do PowerShell 7 (7.3.0).

O último comando acessa a $PSVersionTable variável na sessão remota para exibir a versão do PowerShell que está hospedando a sessão.

Enable-PSRemoting -Force

Get-PSSessionConfiguration

$session = New-PSSession -ComputerName localhost -ConfigurationName PowerShell.7

Invoke-Command -Session $session -ScriptBlock { $PSVersionTable }

WARNING: PowerShell remoting has been enabled only for PowerShell Core configurations and
does not affect Windows PowerShell remoting configurations. Run this cmdlet in Windows
PowerShell to affect all PowerShell remoting configurations.

Name          : PowerShell.7
PSVersion     : 7.3
StartupScript :
RunAsUser     :
Permission    : NT AUTHORITY\INTERACTIVE AccessAllowed,
                BUILTIN\Administrators AccessAllowed,
                BUILTIN\Remote Management Users AccessAllowed

Name          : PowerShell.7.3.0
PSVersion     : 7.3
StartupScript :
RunAsUser     :
Permission    : NT AUTHORITY\INTERACTIVE AccessAllowed,
                BUILTIN\Administrators AccessAllowed,
                BUILTIN\Remote Management Users AccessAllowed

Name                           Value
----                           -----
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSEdition                      Core
PSRemotingProtocolVersion      2.3
Platform                       Win32NT
SerializationVersion           1.1.0.1
GitCommitId                    6.2.2
WSManStackVersion              3.0
PSVersion                      6.2.2
OS                             Microsoft Windows 10.0.18363

Nota

O nome da regra de firewall pode ser diferente dependendo da versão do Windows. Use o Get-NetFirewallRule cmdlet para listar os nomes das regras em seu sistema.

Parâmetros

-Confirm

Solicita a sua confirmação antes de executar o cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Força o comando a ser executado sem pedir a confirmação do usuário.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipNetworkProfileCheck

Indica que esse cmdlet permite a comunicação remota em versões de cliente do sistema operacional Windows quando o computador está em uma rede pública. Este parâmetro permite uma regra de firewall para redes públicas que permite o acesso remoto apenas a partir de computadores na mesma sub-rede local.

Esse parâmetro não afeta as versões de servidor do sistema operacional Windows, que, por padrão, têm uma regra de firewall de sub-rede local para redes públicas. Se a regra de firewall de sub-rede local estiver desabilitada em uma versão do servidor, Enable-PSRemoting ela será reativada, independentemente do valor desse parâmetro.

Para remover a restrição de sub-rede local e habilitar o acesso remoto de todos os locais em redes públicas, use o Set-NetFirewallRulecmdlet no módulo NetSecurity .

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

String

Este cmdlet retorna cadeias de caracteres que descrevem seus resultados.

Notas

Este cmdlet só está disponível em plataformas Windows.

Nas versões de servidor do sistema operacional Windows, Enable-PSRemoting cria regras de firewall para redes privadas e de domínio que permitem acesso remoto e cria uma regra de firewall para redes públicas que permite acesso remoto somente de computadores na mesma sub-rede local.

Nas versões cliente do sistema operacional Windows, Enable-PSRemoting cria regras de firewall para redes privadas e de domínio que permitem acesso remoto irrestrito. Para criar uma regra de firewall para redes públicas que permita o acesso remoto a partir da mesma sub-rede local, use o parâmetro SkipNetworkProfileCheck .

Nas versões cliente ou servidor do sistema operacional Windows, para criar uma regra de firewall para redes públicas que remova a restrição de sub-rede local e permita acesso remoto, use o Set-NetFirewallRule cmdlet no módulo NetSecurity para executar o seguinte comando: Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any

Enable-PSRemoting habilita todas as configurações de sessão definindo o valor da propriedade Enabled de todas as configurações de sessão como $True.

Enable-PSRemoting Remove as configurações de Deny_All e Network_Deny_All . Isso fornece acesso remoto a configurações de sessão que foram reservadas para uso local.