Débogage du noyau pour les instances Windows sur le réseau

Le module d'extensibilité KDNET pour Elastic Network Adapter (ENA) est une couche de support des pilotes matériels qui permet le débogage du noyau Windows sur le réseau via ENA sur les instances Amazon Elastic Compute Cloud. Vous pouvez utiliser le module d'extensibilité avec le Windows Debugger (WinDbg) pour effectuer un débogage au niveau du noyau sur des instances EC2 exécutant Windows.

Le débogage du noyau vous aide à diagnostiquer et à résoudre les problèmes de bas niveau du système d'exploitation tels que les erreurs d'écran bleu (BSOD), les défaillances de pilotes et les problèmes de démarrage sur vos instances Windows EC2.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

Deux instances Windows EC2, dans le même sous-réseau :

Pour plus d'informations sur le lancement d'instances, consultezCommencez avec Amazon EC2.

Les groupes de sécurité pour les instances hôte et cible doivent autoriser le trafic UDP entrant et sortant sur le port utilisé pour le débogage de KDNET (plage recommandée : 50000—50039). Le moyen le plus simple de configurer cela consiste à créer un groupe de sécurité avec une règle entrante qui autorise le trafic UDP à partir de lui-même comme source, puis à associer ce groupe de sécurité aux deux instances. Pour plus d’informations, consultez Règles des groupes de sécurité dans le Guide de l’utilisateur Amazon VPC.

L'instance cible de débogage doit exécuter l'une des versions Windows suivantes (ou une version ultérieure) :

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

Étape 1 : Installation des outils de débogage Windows sur l'hôte de débogage

Installez les outils de débogage Windows sur l'instance hôte de débogage en exécutant la commande suivante dans une PowerShell session :

winget install microsoft.windbg

Pour obtenir des instructions d'installation détaillées, voir Installer le débogueur Windows dans la documentation Microsoft.

Après l'installation, vérifiez que le débogueur fonctionne en exécutant la commande suivante dans une PowerShell session :

windbgx

La WinDbg fenêtre devrait s'ouvrir. Si c'est le cas, l'installation est réussie et vous pouvez fermer la fenêtre.

Étape 2 : Configuration de la cible de débogage

Sur la cible de débogage, ouvrez une PowerShell session élevée et configurez le débogage du noyau en suivant les étapes ci-dessous.

Exécutez la commande suivante pour répertorier le bus, le périphérique et le numéro de fonction de l'adaptateur ENA connecté à l'instance :

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

Notez les FunctionNumber valeurs BusNumberDeviceNumber, et de l'adaptateur ENA à utiliser pour le débogage à partir de la sortie.

Exécutez les commandes suivantes pour configurer le débogage du noyau. Remplacez les valeurs d'espace réservé par votre configuration spécifique :

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"

Où :

bcdedit /bootdebug on

Étape 3 : démarrer la session de débogage sur l'hôte de débogage

Pour autoriser le débogage du trafic sur l'hôte, vous pouvez créer une règle de pare-feu pour l' WinDbg application ou pour un port UDP spécifique.

Option 1 : Autoriser l' WinDbg application

Exécutez les commandes suivantes pour autoriser l' WinDbg exécutable :

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

Option 2 : autoriser un port UDP spécifique

Vous pouvez également autoriser le trafic UDP entrant vers le port configuré pour le débogage du noyau. port-numberRemplacez-le par le port KDNET de votre choix :

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

WinDbg Commencez par le port et la clé correspondant à la configuration de la cible de débogage. Vous pouvez spécifier des options supplémentaires de débogage du noyau documentées dans la référence de ligne de WinDbg commande Microsoft en fonction de votre cas d'utilisation.

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

WinDbg s'ouvre et attend que la cible de débogage se connecte.

Étape 4 : redémarrez la cible de débogage

Sur la cible de débogage, redémarrez l'instance pour initier la connexion de débogage :

shutdown -r -t 0

Après le redémarrage de la cible de débogage, l'hôte WinDbg de débogage se connecte automatiquement à la cible. Vous pouvez désormais l'utiliser WinDbg pour inspecter l'état du noyau, définir des points d'arrêt et diagnostiquer les problèmes.

Nettoyer les paramètres de débogage après le débogage

Sur la cible de débogage

Une fois le débogage terminé, supprimez la configuration de débogage du noyau de la cible de débogage pour rétablir le comportement de démarrage normal. Sur la cible de débogage, ouvrez une PowerShell session élevée et exécutez les commandes suivantes :

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

Si vous en avez un loadoptions autreFORCEHVTONOTSHAREDEBUGDEVICE, vous devez restaurer le paramètre bcdedit /set loadoptions en utilisant l'originalloadoptions.

Si vous avez activé le débogage au démarrage, exécutez également :

bcdedit /bootdebug off

Redémarrez l'instance pour que les modifications prennent effet.

Sur l'hôte de débogage

Supprimez la règle de pare-feu en exécutant :

Remove-NetFirewallRule -DisplayName "Allow Inbound KDNET Connection"

Limitations

Le module d'extensibilité KDNET pour ENA ne prend actuellement pas en charge :

Le module ne prend actuellement pas en charge les instances pour lesquelles le démarrage sécurisé est activé. Vous pouvez vérifier le statut Confirm-SecureBootUEFI en exécutant une PowerShell session élevée. Si le résultat est le casTrue, Secure Boot est actif. Notez que le démarrage sécurisé est activé par défaut sur toutes les images fournies par Amazon avec le préfixe « TPM ».

Informations complémentaires

Si vous rencontrez des problèmes pour connecter le débogueur à l'instance cible, vérifiez les points suivants :

Pour obtenir des instructions supplémentaires, voir Configurer le débogage manuel du noyau du réseau KDNET dans la documentation Microsoft.