Partager via

Configurer manuellement le 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 explique 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 configurer automatiquement le débogage du noyau réseau KDNET, consultez Configuration du débogage du noyau réseau KDNET. L’utilisation de l’utilitaire KDNET est fortement recommandée pour tous les utilisateurs du débogueur.

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

Le débogage sur un réseau présente les avantages suivants par rapport au débogage sur d’autres types de connectivité.

  • L’hôte et les ordinateurs cibles peuvent se trouver n’importe où sur le réseau local.
  • Il est facile de déboguer de nombreux ordinateurs cibles à partir d’un ordinateur hôte.
  • Compte tenu de deux ordinateurs, il est probable qu’ils disposent tous deux d’adaptateurs Ethernet. Il est moins probable qu’ils aient à la fois des ports série et des ports 1394.
  • Le débogage réseau est plus rapide que le débogage de 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 11 et les cartes réseau Ethernet prises en charge pour le débogage du noyau réseau dans Windows 10.

Installer les outils de débogage pour Windows

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

Déterminer l’adresse 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 commandes et entrez la commande suivante :

    ipconfig

    Notez l'adresse IPv4 de la carte réseau que vous prévoyez d'utiliser pour le débogage.

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

    ping -4 <YourIPAddress>

Choisir un port pour le débogage réseau

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

Remarque

La plage de numéros de port qui peuvent être utilisés pour le débogage réseau peut être limitée par la stratégie réseau de votre entreprise. Il n’existe aucun moyen de savoir à partir de l’ordinateur hôte quelles sont les limitations. Pour déterminer si la stratégie de votre entreprise limite la plage de ports qui peuvent être utilisés pour le débogage réseau, vérifiez auprès de 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 affecter le port 50000 à la première connexion, le port 50001 à la deuxième connexion, et ainsi de suite.

Remarque

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

Configurer l’ordinateur cible

  1. Vérifiez que l’ordinateur cible dispose d’une carte réseau prise en charge. Pour plus d’informations, consultez :

  2. Connectez l'adaptateur pris en charge à un hub réseau ou un commutateur à 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é Windows, telles que BitLocker et Le démarrage sécurisé, sur le PC de test. Réactivez ces fonctionnalités de sécurité lorsque le test est terminé et gérez correctement le PC de test lorsque les fonctionnalités de sécurité sont désactivées.

  1. Dans une invite de commandes avec élévation de privilèges, 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 un lecteur flash USB. Vous avez besoin de la clé lorsque vous démarrez une session de débogage sur l’ordinateur hôte.

  3. Utilisez Device Manager pour déterminer les numéros de fonction, d’appareil et de bus PCI 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 sous l’onglet général . Ensuite, dans une invite de commandes avec élévation de privilèges, entrez la commande suivante, où b, det f sont le numéro de bus, le numéro d’appareil et le numéro de fonction de l’adaptateur :

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

  4. Le PC cible est redémarré une fois qu’un débogueur de noyau est attaché.

Remarque

Si vous envisagez d’installer le rôle Hyper-V sur l’ordinateur cible, consultez Configuration du débogage réseau d’un hôte de machine virtuelle.

Attention Si votre ordinateur cible se trouve dans une station d’ancrage et que le débogage réseau est activé pour une carte réseau qui fait partie de la station d’ancrage, ne supprimez pas l’ordinateur de la station d’ancrage. Si vous devez supprimer l’ordinateur cible de la station d’ancrage, 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 commandes en tant qu’administrateur et entrez la commande bcdedit /debug off. Redémarrez l’ordinateur cible.

Démarrer la session de débogage

Vérifiez que la carte réseau de l’ordinateur hôte est connectée à un hub réseau ou à un commutateur à 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 Débogage du noyau, ouvrez l’onglet Net. Entrez votre numéro de port et votre clé. Sélectionnez OK.

Vous pouvez également démarrer une session avec WinDbg en ouvrant une invite de commandes et en entrant la commande suivante, où n est votre numéro de port et MyKey est la clé générée automatiquement par BCDEdit lorsque vous configurez 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.

Utiliser KD

Sur l’ordinateur hôte, ouvrez une invite de commande. Entrez la commande suivante, où n correspond à votre numéro de port et MyKey est la clé générée automatiquement par BCDEdit lorsque vous configurez 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 le PC consiste à utiliser cette commande à partir de l’invite de commandes d’un administrateur :

shutdown -r -t 0

Lorsque la cible est redémarrée, le débogueur dans le système d’exploitation hôte doit 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.

Autoriser le débogueur via le pare-feu

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

Si vous n’obtenez pas l’invite ou si vous n’avez pas coché les cases lorsque l’invite était disponible, vous devez utiliser le Panneau de configuration pour autoriser l’accès via le pare-feu sur le PC hôte où le débogueur est en cours d’exécution. Ouvrez Panneau de configuration > système et sécurité, puis 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 via 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 transitent entre l’hôte et les ordinateurs cibles 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). L’utilisation d’une clé de chiffrement générée automatiquement est recommandée, 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 formatée sous forme de quatre valeurs de 64 bits, en base 36, séparées par des points. Chaque valeur 64 bits est spécifiée en utilisant jusqu’à 13 caractères. Les caractères valides sont les lettres a à z et les chiffres 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. Entrez la commande suivante, où w.x.y.z est l’adresse IP de l’ordinateur hôte, n correspond à 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 par le biais de pare-feu

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

Si vous n’obtenez pas l’invite ou si vous n’avez pas coché les cases lorsque l’invite était disponible, vous devez utiliser le Panneau de configuration pour autoriser l’accès via le pare-feu. Ouvrez Panneau de configuration > système et sécurité, puis 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 via 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 figurer dans la plage autorisée par la stratégie réseau

La plage de numéros de port qui peuvent être utilisés pour le débogage réseau peut être limitée par la stratégie réseau de votre entreprise. Pour déterminer si la stratégie 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 commandes en tant qu’administrateur et entrez la commande bcdedit /dbgsettings. La sortie est similaire à 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 VotreDebugPort 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 du débogueur de l’ordinateur cible, réexécutez le débogueur sur l’ordinateur hôte avec le nouveau paramètre de port, puis redémarrez l’ordinateur cible.

Utiliser 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étectable sur le réseau, car le pare-feu peut bloquer les requêtes ping. Si le pare-feu bloque les requêtes ping, vous n’obtiendrez aucune réponse lorsque vous effectuez un test ping sur 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 DHCP (Dynamic Host Configuration Protocol) pour obtenir une adresse IP routable pour la carte réseau utilisée pour le débogage. Si KDNET obtient une adresse affecté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 ne parvient pas à obtenir une adresse affectée par DHCP, il utilise l’adressage IP privé automatique (APIPA) pour obtenir une adresse IP de liaison locale. Les adresses IP des liens locaux ne sont pas routables. Par conséquent, un hôte et une cible ne peuvent pas utiliser d’adresse IP de liaison locale pour communiquer via un routeur. Dans ce cas, le débogage réseau fonctionnera si vous branchez les ordinateurs hôtes et cibles dans le même hub réseau ou commutateur.

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 une carte réseau PCI ou PCIe, vous devez toujours spécifier les busparams pour la carte réseau 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 de propriétés de la carte réseau et notez le numéro de bus, le numéro d’appareil et le numéro de fonction affichés sous Emplacement sous l’onglet Général. Dans une invite de commandes avec élévation de privilèges, entrez la commande suivante, où b, det f sont les numéros de bus, d’appareil et de fonction au format décimal :

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

Lorsque le débogueur s’exécute sur l’ordinateur hôte et attend de se connecter, redémarrez l’ordinateur cible à l’aide de la commande suivante :

shutdown -r -t 0

Supprimer manuellement les entrées BCDEdit

La suppression manuelle n’est normalement pas nécessaire, mais elle 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, procédez comme suit :

  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 le hostip, vous devez spécifier target= sur la ligne de commande du débogueur.

  1. Comme autre exemple, supprimez l’entrée de port à l’aide de 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 envisagez d’installer le rôle Hyper-V sur l’ordinateur cible, consultez Configuration du débogage réseau d’un hôte de machine virtuelle.

Pour plus d’informations sur le débogage d’une machine virtuelle Hyper-V, consultez Configuration du débogage réseau d’une machine virtuelle - KDNET.

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

Parfois, une situation se produit, ce qui entraîne l’arrêt du fonctionnement de la mise en réseau dans les machines virtuelles :

  • Hyper-V a été activé sur le PC, un commutateur de mise en réseau externe a été créé et pointe vers une carte réseau physique sur la machine, et les machines virtuelles ont été configurées pour utiliser ce commutateur externe pour leur mise en réseau.

  • KDNET est ensuite activé sur le système d’exploitation hôte Hyper-V à l’aide de la même carte réseau physique que celle vers laquelle pointe le commutateur réseau externe. L’hôte est redémarré.

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

Cette interruption est intentionnelle et se produit parce que KDNET prend un contrôle exclusif sur la carte réseau qui lui est destinée. Le miniport NDIS natif pour cette carte réseau n’est pas chargé par le système d’exploitation. Le commutateur de mise en réseau externe ne peut alors plus communiquer avec le pilote miniport NDIS natif et cesse de fonctionner. Pour contourner cette situation, procédez comme suit :

  1. Ouvrez le Gestionnaire de commutateur virtuel à partir de Hyper-V Manager, puis 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 carte réseau de commutateur virtuel, arrêtez et redémarrez vos machines virtuelles.

Lorsque 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 la carte réseau. Sinon, la connectivité de la machine virtuelle est perdue après avoir désactivé le débogage et que la machine est redémarrée.

IPv6

La prise en charge IPv6 a été ajoutée dans Windows version 1809.

Pour utiliser IPv6 avec le débogueur, procédez comme suit :

  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 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 y avoir aucun espace dans la chaîne hostipv6=s:t:u:v:w:x:y:z. <Votreport> est le numéro de port réseau à utiliser pour cet ordinateur cible. <> YourKey est la clé de sécurité à quatre éléments. <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. Tapez 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 l’ordinateur 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 s’exécute sur l’ordinateur hôte et attend de se connecter, redémarrez l’ordinateur cible.

  7. Le débogueur doit 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 signalées dans le message connecté 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 souhaitez et obtiendrez IPv4.

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

  • Le débogueur hôte sélectionne normalement automatiquement l’utilisation d’IPv4 ou 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 à partir 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 d’ordinateur, le débogueur convertit ce nom d’ordinateur en adresse IPv4 et une adresse IPv6. Le débogueur tente ensuite de se connecter sur les deux systèmes.

  • 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 de connexion.

Voir aussi