Depuração de kernel para instâncias do Windows pela rede

O KDNET Extensibility Module for Elastic Network Adapter (ENA) é uma camada de suporte de driver de hardware que permite fazer a depuração de kernel do Windows pela rede por meio do ENA nas instâncias do Amazon Elastic Compute Cloud. Use o módulo de extensibilidade com o Windows Debugger (WinDbg) para realizar a depuração em nível de kernel em instâncias do Amazon EC2 executando o Windows.

A depuração do kernel ajuda a diagnosticar e solucionar problemas de baixo nível do sistema operacional, como erros de tela azul (BSODs), falhas de driver e problemas de inicialização em instâncias do EC2 Windows.

Pré-requisitos

Antes de começar, você deve ter o seguinte:

Duas instâncias do EC2 Windows, na mesma sub-rede:

Para saber mais sobre inicialização de instâncias, consulte Comece a usar o Amazon EC2.

Os grupos de segurança da instância host e da instância de destino devem permitir tráfego UDP de entrada e saída na porta usada para depuração com KDNET (intervalo recomendado: 50.000 a 50.039). A maneira mais simples de configurar isso é criar um grupo de segurança com uma regra de entrada que permita o tráfego UDP tendo a si mesmo como origem e anexar esse grupo de segurança a ambas as instâncias. Para ter mais informações, consulte Security group rules no Guia do usuário da Amazon VPC.

A instância de destino da depuração deve executar uma dessas versões do Windows (ou posterior):

Test-Path C:\Windows\system32\kd_02_1d0f.dll

Etapa 1: instalar as ferramentas de depuração do Windows na instância host da depuração

Instale as ferramentas de depuração do Windows na instância host da depuração executando o seguinte comando em uma sessão do PowerShell:

winget install microsoft.windbg

Para obter instruções de instalação detalhadas, consulte Instalar o Windows Debugger na documentação da Microsoft.

Após a instalação, verifique se o depurador está funcionando, executando o seguinte comando em uma sessão do PowerShell:

windbgx

A janela do WinDbg deve se abrir. Se isso acontecer, a instalação foi bem-sucedida e você pode fechar a janela.

Etapa 2: Configurar o destino da depuração

No destino da depuração, abra uma sessão elevada do PowerShell e configure a depuração do kernel usando as etapas a seguir.

Execute o seguinte comando para listar o número do barramento, dispositivo e função do adaptador ENA conectado à instância:

Get-NetAdapter -Physical |
    Where-Object -Property PnPDeviceID -Match -Value '^PCI\\VEN_1D0F&DEV_EC2[01]&' |
    Get-NetAdapterHardwareInfo |
    Select-Object InterfaceDescription, BusNumber, DeviceNumber, FunctionNumber |
    Format-List

Get-NetAdapter -Physical |
    Where-Object PnPDeviceID -Match '^PCI\\VEN_1D0F&DEV_EC2[01]&' |
    ForEach-Object {
        $adapter = $_
        $hwInfo = $adapter | Get-NetAdapterHardwareInfo
        $ipInfo = Get-NetIPAddress -InterfaceIndex $adapter.InterfaceIndex -AddressFamily IPv4
        [PSCustomObject]@{
            InterfaceDescription = $adapter.InterfaceDescription
            IPAddress            = $ipInfo.IPAddress
            BusNumber            = $hwInfo.BusNumber
            DeviceNumber         = $hwInfo.DeviceNumber
            FunctionNumber       = $hwInfo.FunctionNumber
        }
    } | Format-List

Observe os valores BusNumber, DeviceNumber e FunctionNumber do adaptador ENA para serem usados para depuração da saída.

Execute os comandos a seguir para configurar a depuração do kernel. Substitua os valores dos espaços reservados por suas informações específicas:

bcdedit /debug on
bcdedit /set loadoptions FORCEHVTONOTSHAREDEBUGDEVICE
bcdedit /dbgsettings net hostip:host-private-ip port:port-number key:encryption-key busparams:b.d.f

(bcdedit /enum) -match "loadoptions"

Em que:

bcdedit /bootdebug on

Etapa 3: iniciar a sessão de depuração no host da depuração

Para permitir o tráfego da depuração no host, crie uma regra de firewall para a aplicação WinDbg ou para uma porta UDP específica.

Opção 1: permitir a aplicação WinDbg

Execute os seguintes comandos para autorizar o executável WinDbg:

$WinDbgxPath = "$env:LocalAppData\Microsoft\WindowsApps\WinDbgX.exe"
New-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection" -Action Allow -Program $WinDbgxPath

Opção 2: permitir uma porta UDP específica

Como alternativa, permita tráfego de UDP de entrada na porta configurada para depuração do kernel. Substitua o número da porta pela porta KDNET escolhida:

$DebugPort = port-number
New-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection" -Direction Inbound -LocalPort $DebugPort -Protocol UDP -Action Allow

Inicie o WinDbg com a porta e a chave que correspondem à configuração do destino da depuração. Você pode especificar as opções adicionais de depuração do kernel documentadas na Microsoft WinDbg command line reference para atender ao seu caso de uso.

windbgx -k net:port=port-number,key=encryption-key

O WinDbg é aberto e espera que o destino da depuração se conecte.

Etapa 4: inicializar o destino da depuração

No destino da depuração, reinicie a instância para iniciar a conexão de depuração:

shutdown -r -t 0

Depois que o destino da depuração é reiniciado, o WinDbg no host da depuração se conecta automaticamente ao destino. Você já pode usar o WinDbg para inspecionar o estado do kernel, definir pontos de interrupção e diagnosticar problemas.

Após a depuração, limpe as configurações de depuração

No destino da depuração

Depois de concluir a depuração, remova a configuração de depuração de kernel do destino da depuração para restaurar o comportamento de inicialização normal. No destino da depuração, abra uma sessão elevada do PowerShell e execute os seguintes comandos:

bcdedit /debug off
bcdedit /dbgsettings LOCAL
bcdedit /deletevalue loadoptions

Se suas loadoptions não forem FORCEHVTONOTSHAREDEBUGDEVICE, restaure a configuração executando bcdedit /set loadoptions com as loadoptions originais.

Se você ativou a depuração de inicialização, execute também:

bcdedit /bootdebug off

Reinicie a instância do RDS para que as alterações entrem em vigor.

No host da depuração

Remova a regra de firewall executando:

Remove-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection"

Limitações

O módulo de extensibilidade KDNET para ENA atualmente não é compatível com:

Atualmente, o módulo não é compatível com instâncias com o Secure Boot habilitado. Você pode verificar o status executando Confirm-SecureBootUEFI em uma sessão elevada do PowerShell. Se a saída for True, Secure Boot estará habilitado. Observe que todas as imagens fornecidas pela Amazon com o prefixo 'TPM' têm Secure Boot habilitado por padrão.

Notas adicionais

Se você tiver problemas ao conectar o depurador à instância de destino, verifique o seguinte:

Para obter orientação adicional, consulte Configurar a depuração do kernel de rede KDNET manualmente na documentação da Microsoft.