Kernel-Debugging für Windows-Instanzen über das Netzwerk

Das KDNET Extensibility Module for Elastic Network Adapter (ENA) ist eine Schicht zur Unterstützung von Hardwaretreibern, die das Windows-Kernel-Debugging über das Netzwerk über ENA auf Amazon Elastic Compute Cloud-Instances ermöglicht. Sie können das Erweiterbarkeitsmodul mit dem Windows Debugger (WinDbg) verwenden, um Debugging auf Kernelebene auf EC2-Instances durchzuführen, auf denen Windows ausgeführt wird.

Mit dem Kernel-Debugging können Sie grundlegende Betriebssystemprobleme wie Bluescreen-Fehler (BSODs), Treiberfehler und Startprobleme auf Ihren EC2-Windows-Instances diagnostizieren und beheben.

Voraussetzungen

Stellen Sie vor dem Beginn sicher, dass Sie über das Folgende verfügen:

Zwei EC2-Windows-Instances im selben Subnetz:

Weitere Informationen zum Starten von Instances finden Sie unter. Erste Schritte mit Amazon EC2

Sicherheitsgruppen für die Host- und Ziel-Instances müssen eingehenden und ausgehenden UDP-Verkehr auf dem Port zulassen, der für das KDNET-Debugging verwendet wird (empfohlener Bereich: 50000—50039). Die einfachste Methode, dies einzurichten, besteht darin, eine Sicherheitsgruppe mit einer eingehenden Regel zu erstellen, die UDP-Verkehr von sich selbst als Quelle zulässt, und diese Sicherheitsgruppe dann beiden Instanzen zuzuordnen. Weitere Informationen finden Sie unter Sicherheitsgruppenregeln im Benutzerhandbuch für Amazon VPC.

Auf der Debug-Zielinstanz muss eine der folgenden Windows-Versionen (oder höher) ausgeführt werden:

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

Schritt 1: Installieren Sie die Windows-Debugging-Tools auf dem Debug-Host

Installieren Sie die Windows-Debugging-Tools auf der Debug-Host-Instanz, indem Sie den folgenden Befehl in einer Sitzung ausführen: PowerShell

winget install microsoft.windbg

Ausführliche Installationsanweisungen finden Sie in der Microsoft-Dokumentation unter Installieren des Windows-Debuggers.

Stellen Sie nach der Installation sicher, dass der Debugger funktioniert, indem Sie den folgenden Befehl in einer PowerShell Sitzung ausführen:

windbgx

Das WinDbg Fenster sollte sich öffnen. Ist dies der Fall, war die Installation erfolgreich und Sie können das Fenster schließen.

Schritt 2: Richten Sie das Debug-Ziel ein

Öffnen Sie auf dem Debug-Ziel eine PowerShell Sitzung mit erhöhten Rechten und konfigurieren Sie das Kernel-Debugging mithilfe der folgenden Schritte.

Führen Sie den folgenden Befehl aus, um die Bus-, Geräte- und Funktionsnummer des ENA-Adapters aufzulisten, der an die Instanz angeschlossen ist:

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

Notieren Sie sich die FunctionNumber Werte BusNumberDeviceNumber, und des ENA-Adapters, der für das Debuggen von der Ausgabe aus verwendet werden soll.

Führen Sie die folgenden Befehle aus, um das Kernel-Debugging zu konfigurieren. Ersetzen Sie die Platzhalterwerte durch Ihre spezifische Konfiguration:

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"

Wobei Folgendes gilt:

bcdedit /bootdebug on

Schritt 3: Starten Sie die Debugging-Sitzung auf dem Debug-Host

Um das Debuggen von Datenverkehr auf dem Host zu ermöglichen, können Sie eine Firewallregel entweder für die WinDbg Anwendung oder einen bestimmten UDP-Port erstellen.

Option 1: Die WinDbg Anwendung zulassen

Führen Sie die folgenden Befehle aus, um die WinDbg ausführbare Datei zu autorisieren:

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

Option 2: Erlauben Sie einen bestimmten UDP-Port

Alternativ können Sie eingehenden UDP-Verkehr zu dem für das Kernel-Debugging konfigurierten Port zulassen. Ersetzen Sie port-number durch den ausgewählten KDNET-Port:

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

Beginnen Sie WinDbg mit dem Port und dem Schlüssel, die der Debug-Zielkonfiguration entsprechen. Sie können je nach Anwendungsfall zusätzliche Kernel-Debugging-Optionen angeben, die in der WinDbg Microsoft-Befehlszeilenreferenz dokumentiert sind.

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

WinDbg öffnet und wartet darauf, dass das Debug-Ziel eine Verbindung herstellt.

Schritt 4: Starten Sie das Debug-Ziel neu

Starten Sie die Instanz auf dem Debug-Ziel neu, um die Debugging-Verbindung zu initiieren:

shutdown -r -t 0

Nach dem Neustart des Debug-Ziels stellt der Debug-Host automatisch eine Verbindung zum Ziel her. WinDbg Sie können es jetzt verwenden WinDbg , um den Kernelstatus zu überprüfen, Breakpoints zu setzen und Probleme zu diagnostizieren.

Bereinigen Sie die Debug-Einstellungen nach dem Debuggen

Auf dem Debug-Ziel

Wenn Sie mit dem Debuggen fertig sind, entfernen Sie die Kernel-Debugging-Konfiguration aus dem Debug-Ziel, um das normale Startverhalten wiederherzustellen. Öffnen Sie auf dem Debug-Ziel eine PowerShell Sitzung mit erhöhten Rechten und führen Sie die folgenden Befehle aus:

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

Wenn Sie bereits loadoptions andere als habenFORCEHVTONOTSHAREDEBUGDEVICE, sollten Sie die Einstellung wiederherstellen, indem Sie bcdedit /set loadoptions mit dem Original loadoptions arbeiten.

Wenn Sie das Boot-Debugging aktiviert haben, führen Sie außerdem Folgendes aus:

bcdedit /bootdebug off

Starten Sie die Instanz neu, damit die Änderungen wirksam werden.

Auf dem Debug-Host

Entfernen Sie die Firewallregel, indem Sie Folgendes ausführen:

Remove-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection"

Einschränkungen

Das KDNET-Erweiterbarkeitsmodul für ENA unterstützt derzeit nicht:

Das Modul unterstützt derzeit keine Instanzen mit aktiviertem Secure Boot. Sie können den Status überprüfen, indem Sie eine PowerShell Sitzung mit erhöhten Rechten ausführenConfirm-SecureBootUEFI. Wenn die Ausgabe lautetTrue, ist Secure Boot aktiv. Beachten Sie, dass für alle von Amazon bereitgestellten Images mit einem „TPM“ -Präfix Secure Boot standardmäßig aktiviert ist.

Weitere Hinweise

Wenn beim Verbinden des Debuggers mit der Ziel-Instance Probleme auftreten, überprüfen Sie Folgendes:

Weitere Hinweise finden Sie in der Microsoft-Dokumentation unter Manuelles Einrichten des KDNET-Netzwerkkernel-Debuggings.