Depuración del kernel para instancias Windows a través de la red

El módulo de extensibilidad de KDNET para Elastic Network Adapter (ENA) es una capa de hardware para el soporte del controlador que permite la depuración del kernel en Windows mediante la red con ENA en las instancias de Amazon Elastic Compute Cloud. Puede usar el módulo de extensibilidad con el depurador de Windows (WinDbg) para realizar una depuración en el nivel del kernel en las instancias de EC2 que usan Windows.

La depuración del kernel ayuda a diagnosticar y solucionar problemas de bajo nivel del sistema operativo, como los errores de pantalla azul (BSOD), fallos en los controladores y problemas de arranque de las instancias de EC2 Windows.

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

Dos instancias de EC2 Windows en la misma subred:

Para obtener más información acerca de cómo iniciar instancias, consulte Introducción a Amazon EC2.

Los grupos de seguridad de las instancias de host y destino deben permitir el tráfico UDP entrante y saliente en el puerto utilizado para la depuración de KDNET (rango recomendado: 50 000–50 039). La forma más sencilla de configurarlo es crear un grupo de seguridad con una regla de entrada que permita el tráfico UDP desde sí mismo como origen y, a continuación, adjuntar ese grupo de seguridad a ambas instancias. Para obtener más información, consulte Reglas del grupo de seguridad en la Guía del usuario de Amazon VPC.

La instancia de destino de depuración debe ejecutar una de las siguientes versiones de Windows (o una posterior):

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

Paso 1: instale las herramientas de depuración de Windows en el host de depuración

Instale las herramientas de depuración de Windows en la instancia del host de depuración; para hacerlo, ejecute el siguiente comando en una sesión de PowerShell:

winget install microsoft.windbg

Para obtener instrucciones de instalación detalladas, consulte Cómo instalar el depurador de Windows en la documentación de Microsoft.

Tras la instalación, ejecute el siguiente comando en una sesión de PowerShell para verificar que el depurador funcione:

windbgx

Debería abrirse la ventana de WinDbg. En ese caso, la instalación se ha realizado correctamente y puede cerrar la ventana.

Paso 2: configure el destino de depuración

En el destino de depuración, abra una sesión elevada de PowerShell y siga los pasos a continuación para configurar la depuración del kernel:

Ejecute el siguiente comando para ver el número de bus, dispositivo y función del adaptador ENA asociado a la instancia:

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

Anote los valores de BusNumber, DeviceNumber y FunctionNumber del adaptador ENA que se va a utilizar para la depuración desde la salida.

Ejecute los siguientes comandos para configurar la depuración del kernel. Reemplace los valores de marcador de posición con su configuración específica:

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"

Donde:

bcdedit /bootdebug on

Paso 3: inicie la sesión de depuración en el host de depuración

Para permitir el tráfico de depuración en el host, puede crear una regla de firewall para la aplicación de WinDbg o para un puerto UDP específico.

Opción 1: permita la aplicación de WinDbg

Ejecute los siguientes comandos para autorizar el ejecutable de WinDbg:

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

Opción 2: permita un puerto UDP específico

Como alternativa, puede permitir que el tráfico UDP entrante llegue al puerto configurado para la depuración del kernel. Sustituya port-number con el puerto KDNET de su elección:

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

Inicie WinDBG con el puerto y la clave que coincidan con la configuración del destino de depuración. Puede especificar opciones adicionales para la depuración del kernel que se documentan en la referencia de la línea de comandos de WinDbg de Microsoft que se adapten a su caso de uso.

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

WinDbg se abre y espera a que el destino de depuración se conecte.

Paso 4: reinicie el destino de depuración

En el destino de depuración, reinicie la instancia para iniciar la conexión de depuración:

shutdown -r -t 0

Una vez reiniciado el destino de depuración, WinDbg se conecta a él automáticamente desde el host. Ya puede usar WinDbg para inspeccionar el estado del kernel, establecer puntos de interrupción y diagnosticar problemas.

Al terminar, elimine la configuración de depuración

En el destino de depuración

Cuando termine de depurar, elimine la configuración de depuración del kernel del destino de depuración para restablecer el comportamiento de arranque normal. En el destino de depuración, abra una sesión elevada de PowerShell y ejecute los siguientes comandos:

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

Si tiene una configuración loadoptions diferente a FORCEHVTONOTSHAREDEBUGDEVICE, debe restaurar la configuración ejecutando bcdedit /set loadoptions con la loadoptions original.

Si ha activado la depuración de arranque, también debe ejecutar:

bcdedit /bootdebug off

Reinicie la instancia para que los cambios surtan efecto.

En el host de depuración

Elimine la regla de firewall con la ejecución de:

Remove-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection"

Limitaciones

Por el momento, el módulo de extensibilidad de KDNET para ENA no admite:

Por el momento, el módulo no admite instancias con el arranque seguro activado. Para verificar el estado, ejecute Confirm-SecureBootUEFI en una sesión elevada de PowerShell. Si el resultado es True, entonces el arranque seguro está activado. Tenga en cuenta que todas las imágenes proporcionadas por Amazon que tengan el prefijo “TPM” tienen activado el arranque seguro de forma predeterminada.

Notas adicionales

Si tiene problemas para conectar el depurador a la instancia de destino, verifique lo siguiente:

Para obtener instrucciones adicionales, consulte Cómo configurar manualmente la depuración del kernel de red de KDNET en la documentación de Microsoft.