Configuration manuelle du débogage du noyau réseau KDNET

  • Article

Les outils de débogage pour Windows prennent en charge le débogage du noyau sur un réseau. Cet article décrit comment configurer manuellement le débogage réseau.

Important

La configuration manuelle d’un débogage réseau est un processus complexe et sujette aux erreurs. Pour une configuration automatique du débogage réseau, consultez la configuration automatique du débogage réseau du noyau KDNET. Il est fortement recommandé à tous les utilisateurs du débogueur d’utiliser l’utilitaire KDNET.

L’ordinateur qui exécute le débogueur est appelé l’ordinateur hôte, et l’ordinateur en cours de débogage est appelé l’ordinateur cible. L’ordinateur hôte doit exécuter Windows 7 ou une version ultérieure, et l’ordinateur cible doit exécuter Windows 8 ou une version ultérieure.

Le débogage sur un réseau offre plusieurs avantages par rapport au débogage via d’autres types de connectivité.

  • Les ordinateurs hôte et cible peuvent se trouver n’importe où sur le réseau local.
  • Il est facile de déboguer de nombreux ordinateurs cibles à partir d’un seul ordinateur hôte.
  • Il est probable que deux ordinateurs disposent d’adaptateurs Ethernet. Il est moins probable qu’ils aient tous les deux des ports série ou 1394 ports.
  • Le débogage réseau est plus rapide que le débogage via un port série.

Adaptateurs réseau pris en charge

L’ordinateur hôte peut utiliser n’importe quelle carte réseau, mais l’ordinateur cible doit utiliser une carte réseau prise en charge par les outils de débogage pour Windows. Pour obtenir la liste des cartes réseau prises en charge, consultez les cartes réseau Ethernet prises en charge pour le débogage du noyau réseau dans Windows 10 et les cartes réseau Ethernet prises en charge pour le débogage du noyau réseau dans Windows 8.1.

Installation des outils de débogage pour Windows

Confirmez que les outils de débogage pour Windows sont installés sur le système hôte. Pour des informations sur le téléchargement et l’installation des outils de débogage, consultez la rubrique Outils de débogage pour Windows.

Déterminez les adresses IP de l’ordinateur hôte.

Utilisez l’une des procédures suivantes pour déterminer l’adresse IP de l’ordinateur hôte.

  1. Sur l’ordinateur hôte, ouvrez une invite de commande et entrez la commande suivante :

    ipconfig

    Notez l’adresse IPv4 de l’adaptateur réseau que vous avez l’intention d’utiliser pour le débogage.

  2. Sur l’ordinateur cible, ouvrez une invite de commande et entrez la commande suivante, où YourIPAddress est l’adresse IP de l’ordinateur hôte :

    ping -4 <YourIPAddress>

Choisissez un port pour le débogage réseau

Choisissez un numéro de port pour le débogage sur les ordinateurs hôte et cible. Vous pouvez choisir n’importe quel nombre de 49152 à 65535. La plage recommandée est de 50000 à 50039. Le port que vous choisissez est ouvert pour un accès exclusif par le débogueur fonctionnant sur l’ordinateur hôte. Faites attention à choisir un numéro de port qui n’est pas utilisé par d’autres applications fonctionnant sur l’ordinateur hôte.

Remarque

La plage de numéros de port pouvant être utilisée pour le débogage réseau peut être limitée par la politique réseau de votre entreprise. Il n’y a aucun moyen de le savoir depuis l’ordinateur hôte. Pour déterminer si la politique de votre entreprise limite la plage de ports qui peuvent être utilisés pour le débogage réseau, consultez vos administrateurs réseau.

Si vous connectez plusieurs ordinateurs cibles à un seul ordinateur hôte, chaque connexion doit avoir un numéro de port unique. Par exemple, si vous connectez 100 ordinateurs cibles à un seul ordinateur hôte, vous pouvez attribuer le port 50000 à la première connexion, le port 50001 à la seconde, et ainsi de suite.

Remarque

 Un autre ordinateur hôte pourrait utiliser la même plage de ports (50000 à 50099) pour se connecter à 100 autres ordinateurs cibles.

Configurez l’ordinateur cible

  1. Vérifiez que l’ordinateur cible dispose d’un adaptateur réseau pris en charge. Pour plus d’informations, consultez l’article suivant :

  2. Connectez l’adaptateur pris en charge à un hub ou commutateur réseau à l’aide d’un câble réseau approprié.

Important

Avant d’utiliser BCDEdit pour modifier les informations de démarrage, vous devrez peut-être suspendre temporairement les fonctionnalités de sécurité de Windows, telles que BitLocker et Secure Boot, sur l’ordinateur de test. Réactivez ces fonctionnalités de sécurité une fois les tests terminés et gérez de manière appropriée l’ordinateur de test lorsque les fonctionnalités de sécurité sont désactivées.

  1. Dans une invite de commande élevée, entrez les commandes suivantes, où w.x.y.z est l’adresse IP de l’ordinateur hôte et n est un numéro de port de votre choix :

    bcdedit /debug on

bcdedit /dbgsettings net hostip:w.x.y.z port:n

  2. BCDEdit affiche une clé générée automatiquement. Copiez la clé et stockez-la sur un périphérique de stockage amovible, comme une clé USB. Vous aurez besoin de la clé lorsque vous commencerez une session de débogage sur l’ordinateur hôte.

  3. Utilisez le Gestionnaire de périphériques pour déterminer les numéros de bus, de dispositif et de fonction de l’adaptateur que vous souhaitez utiliser pour le débogage. Ces valeurs sont affichées dans le Gestionnaire de périphériques sous Emplacement dans l’onglet Général. Ensuite, dans une invite de commande élevée, entrez la commande suivante, où b, d et f sont respectivement le numéro de bus, le numéro de dispositif et le numéro de fonction de l’adaptateur :

    bcdedit /set "{dbgsettings}" busparams b.d.f

  4. L’ordinateur cible sera redémarré après qu’un débogueur de noyau y soit attaché.

Remarque

Si vous avez l’intention d’installer le rôle Hyper-V sur l’ordinateur cible, consultez la section Configurer le débogage réseau d’un hôte de machine virtuelle.

Attention Si votre ordinateur cible est dans une station d’accueil et que vous avez activé le débogage réseau pour un adaptateur réseau faisant partie de la station d’accueil, ne retirez pas l’ordinateur de la station d’accueil. Si vous devez retirer l’ordinateur cible de la station d’accueil, désactivez d’abord le débogage du noyau. Pour désactiver le débogage du noyau sur l’ordinateur cible, ouvrez une invite de commande en tant qu’administrateur et entrez la commande bcdedit /debug off. Redémarrez l'ordinateur cible.

Démarrer la session de débogage

Confirmez que l’adaptateur réseau de l’ordinateur hôte est connecté à un hub ou commutateur réseau à l’aide d’un câble réseau approprié.

Sur l’ordinateur hôte, ouvrez WinDbg. Dans le menu Fichier, sélectionnez Débogage du noyau. Dans la boîte de dialogue de débogage du noyau, ouvrez l’onglet Réseau. Cliquez sur OK.

Saisissez votre numéro de port et votre clé. Vous pouvez également démarrer une session avec WinDbg en ouvrant une invite de commande et en entrant la commande suivante, où >n est votre numéro de port et MyKey est la clé qui a été générée automatiquement par BCDEdit lorsque vous avez configuré l’ordinateur cible :

windbg -k net:port=<n>,key=<MyKey>

Si une demande d’autorisation pour que WinDbg accède au port à travers le pare-feu apparaît, autorisez WinDbg à accéder au port pour les trois types de réseaux différents.

Utilisez KD

Sur l’ordinateur hôte, ouvrez une invite de commande. Saisissez la commande suivante, où n est votre numéro de port et MyKey est la clé qui a été générée automatiquement par BCDEdit lorsque vous avez configuré l’ordinateur cible :

kd -k net:port=<n>,key=<MyKey>

Si une demande d’autorisation pour que WinDbg accède au port à travers le pare-feu apparaît, autorisez WinDbg à accéder au port pour les trois types de réseaux différents.

Redémarrer le PC cible

Une fois le débogueur connecté et en attente de connexion, redémarrez l’ordinateur cible. Une façon de redémarrer l’ordinateur est d’utiliser cette commande à partir d’une invite de commande d’administrateur :

shutdown -r -t 0

Lorsque l’ordinateur cible est redémarré, le débogueur dans l’OS hôte devrait se connecter.

Après vous être connecté à la cible sur l’hôte, appuyez sur pause dans votre débogueur et vous pouvez commencer le débogage.

Autorisez le débogueur à travers le pare-feu

Lorsque vous tentez pour la première fois d’établir une connexion de débogage réseau, vous pourriez être invité à autoriser l’application de débogage (WinDbg ou KD) à accéder à travers le pare-feu. Les versions clientes de Windows affichent la demande, mais les versions serveur de Windows ne l’affichent pas. Vous devriez répondre à l’invite en cochant les cases pour les trois types de réseau : domaine, privé et public.

Si vous ne recevez pas la demande ou si vous n’avez pas coché les cases lorsque la demande était disponible, vous devez utiliser le Panneau de configuration pour autoriser l’accès à travers le pare-feu sur l’ordinateur hôte où le débogueur est en cours d’exécution. Ouvrez le Panneau de configuration > Système et sécurité et sélectionnez Autoriser une application via le pare-feu Windows.

  • (WinDbg) Dans la liste des applications, recherchez le processus du moteur WinDbg (TCP) (tout).

  • (WinDbg classique) Dans la liste des applications, recherchez le débogueur symbolique Windows GUI et le débogueur du noyau Windows.

Utilisez les cases à cocher pour autoriser ces applications à travers le pare-feu. Redémarrez votre application de débogage (WinDbg ou KD).

Clé de chiffrement

Pour sécuriser l’ordinateur cible, les paquets qui circulent entre les ordinateurs hôte et cible doivent être chiffrés. Vous devez utiliser une clé de chiffrement générée automatiquement (fournie par BCDEdit lorsque vous configurez l’ordinateur cible). Utiliser une clé de chiffrement générée automatiquement est recommandé car elle est plus sécurisée et fournit une valeur unique utilisée pour établir la connexion à une cible spécifique.

Le débogage réseau utilise une clé de 256 bits spécifiée comme quatre valeurs de 64 bits, en base 36, séparées par des points. Chaque valeur de 64 bits est spécifiée à l’aide de jusqu’à 13 caractères. Les caractères valides sont les lettres a à z et les chiffres de 0 à 9. Les caractères spéciaux ne sont pas autorisés.

Pour spécifier votre propre clé, ouvrez une invite de commande élevée sur l’ordinateur cible. Saisissez la commande suivante, où w.x.y.z est l’adresse IP de l’ordinateur hôte, n est votre numéro de port et Clé est votre clé :

bcdedit /dbgsettings net hostip:w.x.y.z port:n key:Key

L’ordinateur cible doit être redémarré chaque fois que les dbgsettings sont modifiés.

Conseils de dépannage

L’application de débogage doit être autorisée à travers les pare-feu

Lorsque vous tentez pour la première fois d’établir une connexion de débogage réseau, vous pourriez être invité à autoriser l’application de débogage (WinDbg ou KD) à accéder à travers le pare-feu. Les versions clientes de Windows affichent la demande, mais les versions serveur de Windows ne l’affichent pas. Vous devriez répondre à l’invite en cochant les cases pour les trois types de réseau : domaine, privé et public.

Si vous ne recevez pas la demande ou si vous n’avez pas coché les cases lorsque la demande était disponible, vous devez utiliser le Panneau de configuration pour autoriser l’accès à travers le pare-feu. Ouvrez le Panneau de configuration > Système et sécurité et sélectionnez Autoriser une application via le pare-feu Windows.

  • (WinDbg) Dans la liste des applications, recherchez le processus du moteur WinDbg (TCP) (tout).

  • (WinDbg classique) Dans la liste des applications, localisez Débogueur symbolique GUI Windows et Débogueur du noyau Windows.

Utilisez les cases à cocher pour autoriser ces applications à travers le pare-feu. Faites défiler vers le bas et sélectionnez OK pour enregistrer les modifications du pare-feu. Redémarrez le débogueur.

Le numéro de port doit être dans la plage autorisée par la politique réseau

La plage de numéros de port pouvant être utilisée pour le débogage réseau peut être limitée par la politique réseau de votre entreprise. Pour déterminer si la politique de votre entreprise limite la plage de ports qui peuvent être utilisés pour le débogage réseau, vérifiez auprès de votre administrateur réseau. Sur l’ordinateur cible, ouvrez une invite de commande en tant qu’administrateur et entrez la commande bcdedit /dbgsettings. Vous devez obtenir un résultat semblable à ce qui suit :

C:\> bcdedit /dbgsettings
key                     XXXXXX.XXXXX.XXXXX.XXXXX
debugtype               NET
hostip                  169.168.1.1
port                    50085
dhcp                    Yes
The operation completed successfully.

Dans la sortie précédente, la valeur du port est 50085. Si la valeur du port se trouve en dehors de la plage autorisée par votre administrateur réseau, entrez la commande suivante. La valeur w.x.y.z est l’adresse IP de l’ordinateur hôte, et YourDebugPort est un numéro de port dans la plage autorisée.

bcdedit /dbgsettings net hostip:w.x.y.z port:YourDebugPort

Après avoir modifié les paramètres de débogage de la machine cible, relancez le débogueur sur l’ordinateur hôte avec le nouveau paramètre de port, puis redémarrez l’ordinateur cible.

Utilisez le ping pour tester la connectivité.

Si le débogueur ne se connecte pas, utilisez la commande ping sur le PC cible pour vérifier la connectivité.

C:\>Ping <HostComputerIPAddress>

Remarque

Cela peut ne pas fonctionner si votre ordinateur hôte n’est pas configuré pour être découvrable sur le réseau, car le pare-feu peut bloquer les demandes de ping. Si le pare-feu bloque les demandes de ping, vous ne recevrez aucune réponse lorsque vous effectuez un test ping de l’hôte.

Comment le débogueur obtient une adresse IP pour l’ordinateur cible

KDNET sur l’ordinateur cible tente d’utiliser le Protocole de Configuration Dynamique des Hôtes (DHCP) pour obtenir une adresse IP routable pour l’adaptateur réseau utilisé pour le débogage. Si KDNET obtient une adresse attribuée par DHCP, l’ordinateur cible peut être débogué par des ordinateurs hôtes situés n’importe où sur le réseau. Si KDNET échoue à obtenir une adresse attribuée par DHCP, il utilise l’adressage IP privé automatique (APIPA) pour obtenir une adresse IP de lien local. Les adresses IP de lien local ne peuvent pas être routées, donc un hôte et une cible ne peuvent pas utiliser une adresse IP de lien local pour communiquer à travers un routeur. Dans ce cas, le débogage réseau fonctionnera si vous branchez les ordinateurs hôte et cible sur le même concentrateur ou commutateur réseau.

Toujours spécifier les busparams lors de la configuration de KDNET sur une machine physique avec un NIC basé sur PCI

Si vous configurez KDNET sur une machine physique avec un NIC basé sur PCI ou PCIe, vous devez toujours spécifier les busparams pour le NIC que vous souhaitez utiliser pour KDNET. Pour spécifier les paramètres du bus, ouvrez le Gestionnaire de périphériques et localisez l’adaptateur réseau que vous souhaitez utiliser pour le débogage. Ouvrez la page des propriétés de l’adaptateur réseau et notez le numéro de bus, le numéro de périphérique et le numéro de fonction affichés sous Emplacement dans l’onglet Général. Dans une invite de commande élevée, entrez la commande suivante, où b, d et f sont les numéros de bus, de périphérique et de fonction au format décimal :

bcdedit /set "{dbgsettings}" busparams b.d.f

Lorsque le débogueur fonctionne sur la machine hôte et attend de se connecter, redémarrez l’ordinateur cible en utilisant la commande suivante :

shutdown -r -t 0

Suppression manuelle des entrées BCDEdit

La suppression manuelle n’est normalement pas requise mais est fournie ici comme procédure de dépannage pour des situations inhabituelles.

La suppression manuelle des entrées n’est pas nécessaire lors de l’utilisation de l’utilitaire kdnet. Pour plus d’informations, consultez la rubrique Configuration automatique du débogage réseau du noyau KDNET.

Lorsque vous utilisez bcdedit –deletevalue, vous devez fournir un nom d’élément bcd valide. Pour plus d’informations, voir BCDEdit /deletevalue.

Pour supprimer manuellement les entrées bcdedit, suivez les étapes suivantes :

  1. Sur l’ordinateur cible, ouvrez une invite de commande en tant qu’administrateur.

  2. Par exemple, entrez la commande suivante pour supprimer l’entrée de débogage BCDEdit pour l’adresse IP de l’hôte :

    bcdedit -deletevalue {dbgsettings} hostip

Lorsque vous supprimez l’hostip, vous devez spécifier target= sur la ligne de commande du débogueur.

  1. Comme autre exemple, supprimez l’entrée de port en utilisant la commande suivante :

    bcdedit -deletevalue {dbgsettings} port

Lorsque vous supprimez l’entrée de port, KDNET utilise le port de débogueur enregistré par l’ICANN par défaut de 5364.

Configurer Hyper-V

Si vous avez l’intention d’installer le rôle Hyper-V sur l’ordinateur cible, consultez la section Configurer le débogage réseau d’un hôte de machine virtuelle.

Pour obtenir des informations sur le débogage d’une machine virtuelle Hyper-V (VM), consultez la rubrique Configuration du débogage réseau d’un hôte de machine virtuelle - KDNET.

Activer KDNET sur un hôte Hyper-V exécutant des VM avec connectivité réseau externe

Parfois, une situation se produit qui fait que le réseau dans les VM cesse de fonctionner :

  • Hyper-V a été activé sur le PC, un commutateur réseau externe a été créé et est pointé sur un NIC physique dans la machine, et les VM ont été configurées pour utiliser ce commutateur externe pour leur réseau.

  • KDNET est ensuite activé sur l’OS hôte Hyper-V en utilisant le même NIC physique pointé par le commutateur réseau externe. L’hôte est redémarré.

  • Toutes les VM qui utilisaient le commutateur externe précédemment configuré, perdent leur connectivité réseau après le redémarrage.

Cet arrêt est conçu ainsi et se produit parce que KDNET prend le contrôle exclusif sur le NIC qu’il est configuré pour utiliser. Le miniport NDIS natif pour ce NIC n’est pas chargé par l’OS. Le commutateur réseau externe ne peut alors plus communiquer avec le pilote miniport NDIS natif et cesse de fonctionner. Pour contourner cette situation, faites ce qui suit :

  1. Ouvrez le Gestionnaire de commutateurs virtuels depuis le Gestionnaire Hyper-V, et sélectionnez votre commutateur virtuel existant. Changez le NIC réseau externe pour l’Adaptateur réseau de débogage du noyau Microsoft en le sélectionnant dans le menu déroulant puis en sélectionnant OK dans la boîte de dialogue du Gestionnaire de commutateurs virtuels.

  2. Après avoir mis à jour votre NIC de commutateur virtuel, éteignez et redémarrez vos VM.

Quand le débogage KDNET est désactivé, la même procédure doit être suivie pour repointer le commutateur externe vers le miniport NDIS natif pour le NIC. Sinon, la connectivité VM est perdue lorsque la machine est redémarrée après que le débogage est désactivé.

IPv6

Le support IPv6 a été ajouté dans la version 1809 de Windows.

Pour utiliser IPv6 avec le débogueur, suivez les étapes suivantes :

  1. Effectuez un test ping sur votre <debughostname> et notez l’adresse IPv6 qui est rapportée dans les lignes de réponse de sortie. Utilisez cette adresse IPv6 à la place de x:y:z:p:d:q:r:n.

  2. Utilisez BCDEdit pour supprimer toutes les valeurs d’adresse IP existantes dans dbgsettings.

    bcdedit -deletevalue {dbgsettings} hostip

  3. Définissez l’adresse IPv6 de l’hôte. Il ne doit pas y avoir d’espaces dans la chaîne hostipv6=s:t:u:v:w:x:y:z. <YourPort> est le numéro de port réseau à utiliser pour cette machine cible. <YourKey> est la clé de sécurité en quatre parties. <b.d.f> sont les numéros de localisation de bus, de périphérique et de fonction pour le NIC que vous souhaitez utiliser pour KDNET.

    bcdedit /dbgsettings net hostipv6:s:t:u:v:w:x:y:z port:<YourPort> key:<YourKey> busparams:<b.d.f>

  4. Saisissez cette commande pour confirmer que les dbgsettings sont correctement définis.

    C:\> bcdedit /dbgsettings
busparams               0.25.0
key                     2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
debugtype               NET
hostipv6                  2001:db8:0:0:ff00:0:42:8329
port                    50010
dhcp                    Yes
The operation completed successfully.

  5. Sur la machine hôte, utilisez la commande suivante pour démarrer le débogueur :

    Windbg -k net:port=<yournetworkportnumber>,key=<key_output_from_kdnet>,target=::<YourIPv6Address>

  6. Lorsque le débogueur fonctionne sur la machine hôte et attend de se connecter, redémarrez l’ordinateur cible.

  7. Le débogueur devrait se connecter au débogueur hôte tôt pendant le démarrage. Vous pouvez voir que KDNET utilise une connexion IPv6 car les adresses IP rapportées dans le message de connexion sont des adresses IPv6 au lieu d’adresses IPv4.

Notes

  • Chaque paramètre bcd de débogueur qui permet de spécifier le hostip a un élément correspondant hostipv6. Il y en a trois.

    IPv4 IPv6 Utilisation
    hostip hostipv6 Pour le débogage de démarrage et de noyau
    targethostip targethostipv6 Spécifique au débogage du noyau
    hypervisorhostip hypervisorhostipv6 Pour le débogage hyper-v

  • Si vous définissez l’adresse de style hostipv6 pour l’un de ces types de débogage, cela signifie que vous voulez et obtiendrez IPv6.

  • Si vous définissez l’adresse de style hostip pour l’un de ces types de débogage, cela signifie que vous voulez et obtiendrez IPv4.

  • La cible ne fera qu’IPv4 ou IPv6, pas les deux en même temps. La version du protocole IP utilisée est contrôlée par les dbgsettings de la machine cible. Si hostip est défini, la cible utilise IPv4. Si hostipv6 est défini, la cible utilise IPv6.

  • Le débogueur hôte sélectionne normalement automatiquement l’utilisation d’IPv4 ou d’IPv6. Par défaut, le débogueur écoute à la fois sur une socket IPv4 et une socket IPv6 et se connecte automatiquement sur l’une ou l’autre à la machine cible.

  • Si vous souhaitez forcer l’utilisation d’IPv6 dans le débogueur sur l’hôte, mais que vous souhaitez que le débogueur écoute une connexion de la cible, vous pouvez ajouter target=:: à la ligne de commande du débogueur. :: est une adresse IPv6 de 0.

  • Si vous souhaitez forcer le débogage IPv4 dans le débogueur sur l’hôte, mais que vous souhaitez que le débogueur écoute une connexion de la cible, vous pouvez ajouter target=0.0.0.0 à la ligne de commande du débogueur. 0.0.0.0 est une adresse IPv4 de 0.

  • Si vous spécifiez target= sur la ligne de commande du débogueur et utilisez un nom de machine, le débogueur convertit ce nom de machine en une adresse IPv4 et une adresse IPv6. Le débogueur tente ensuite de se connecter sur les deux.

  • Lorsque vous spécifiez target= sur la ligne de commande du débogueur et utilisez une adresse IP, si l’adresse IP contient des caractères :, le débogueur suppose qu’il s’agit d’une adresse IPv6 et force l’utilisation d’IPv6 pour cette connexion. Si l’adresse IP contient des caractères ., le débogueur suppose qu’il s’agit d’une adresse IPv4 et force l’utilisation d’IPv4 pour cette connexion.

  • Si vous configurez IPv6 sur la cible et forcez l’utilisation d’IPv4 sur la ligne de commande du débogueur, vous n’obtenez pas de connexion.

  • Si vous configurez IPv4 sur la cible et forcez l’utilisation d’IPv6 sur la ligne de commande du débogueur, vous n’obtenez pas non plus de connexion.

Voir aussi