Configurar a depuração do kernel da rede KDNET manualmente

As Ferramentas de Depuração para Windows suportam a depuração do kernel através de uma rede. Este artigo descreve como configurar a depuração de rede manualmente.

O computador que executa o depurador é chamado de computador hoste o computador que está sendo depurado é chamado de computador de destino. O computador host deve estar executando o Windows 7 ou posterior e o computador de destino deve estar executando o Windows 8 ou posterior.

A depuração numa rede tem as seguintes vantagens em comparação com a depuração noutros tipos de conectividade.

• Os computadores host e de destino podem estar em qualquer lugar na rede local.
• É fácil depurar muitos computadores-alvo a partir de um computador anfitrião.
• Dado quaisquer dois computadores, é provável que ambos tenham adaptadores Ethernet. É menos provável que ambos tenham portas seriais ou 1394 portas.
• A depuração de rede é mais rápida do que a depuração de porta serial.

Adaptadores de rede suportados

O computador host pode usar qualquer adaptador de rede, mas o computador de destino deve usar um adaptador de rede suportado pelas Ferramentas de Depuração para Windows. Para obter uma lista de adaptadores de rede suportados, consulte NICs Ethernet suportadas para depuração de kernel de rede no Windows 11 e NICs Ethernet suportadas para depuração de kernel de rede no Windows 10.

Instalar ferramentas de depuração para Windows

Confirme se as Ferramentas de Depuração para Windows estão instaladas no sistema host. Para obter informações sobre como baixar e instalar as ferramentas de depurador, consulte Ferramentas de depuração para Windows.

Determinar o endereço IP do computador host

Use um dos procedimentos a seguir para determinar o endereço IP do computador host.

1. No computador host, abra um prompt de comando e digite o seguinte comando:

   ipconfig
   

   Anote o endereço IPv4 do adaptador de rede que você pretende usar para depuração.

2. No computador de destino, abra um prompt de comando e digite o seguinte comando, onde YourIPAddress é o endereço IP do computador host:

   ping -4 <YourIPAddress>
   

Escolha uma porta para depuração de rede

Escolha um número de porta para depuração tanto no computador host como no de destino. Você pode escolher qualquer número de 49152 a 65535. O intervalo recomendado é 50000 - 50039. A porta que escolher é aberta para acesso exclusivo pelo depurador que está a correr no computador anfitrião. Tenha cuidado para escolher um número de porta que não seja usado por nenhum outro aplicativo executado no computador host.

Se você conectar vários computadores de destino a um único computador host, cada conexão deverá ter um número de porta exclusivo. Por exemplo, se você conectar 100 computadores de destino a um único computador host, poderá atribuir a porta 50000 à primeira conexão, a porta 50001 à segunda conexão e assim por diante.

Configurar o computador de destino

1. Verifique se o computador de destino tem um adaptador de rede suportado. Para mais informações, consulte:

   • NICs Ethernet suportadas para depuração do kernel de rede no Windows 8.1

   • NICs Ethernet suportadas para depuração do kernel de rede no Windows 10

2. Conecte o adaptador suportado a um hub ou switch de rede usando um cabo de rede apropriado.

3. Em um prompt de comando elevado, digite os seguintes comandos, onde w.x.y.z é o endereço IP do computador host e n é um número de porta de sua escolha:

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

4. O BCDEdit exibe uma chave gerada automaticamente. Copie a chave e armazene-a em um dispositivo de armazenamento removível, como uma unidade flash USB. Você precisa da chave quando inicia uma sessão de depuração no computador host.

5. Use o Gerenciador de Dispositivos para determinar o barramento PCI, o dispositivo e os números de função do adaptador que você deseja usar para depuração. Esses valores são exibidos no Gestor de Dispositivos em Localização na guia Geral. Em seguida, num prompt de comando elevado, introduza o seguinte comando, onde b, de f são o número do barramento, o número do dispositivo e o número da função do adaptador:

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

6. O PC de destino será reiniciado depois que um depurador do kernel for anexado.

Cuidado Se o computador de destino estiver numa estação de acoplamento e tiver a depuração de rede ativada para um adaptador de rede que faz parte da estação de acoplamento, não remova o computador da estação de acoplamento. Se você precisar remover o computador de destino da estação de ancoragem, desative a depuração do kernel primeiro. Para desativar a depuração do kernel no computador de destino, abra um prompt de comando como administrador e digite o comando bcdedit /debug off. Reinicie o computador de destino.

Iniciar a sessão de depuração

Confirme se o adaptador de rede do computador host está conectado a um hub ou switch de rede usando um cabo de rede apropriado.

No computador host, abra o WinDbg. No menu File, selecione Kernel Debug. Na caixa de diálogo de Depuração do Kernel, abra a guia Net. Insira o número da porta e a chave. Selecione OK.

Você também pode iniciar uma sessão com o WinDbg abrindo um prompt de comando e digitando o seguinte comando, onde n é o número da porta e MyKey é a chave que foi gerada automaticamente pelo BCDEdit quando você configurou o computador de destino:

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

Se você for solicitado a permitir que o WinDbg acesse a porta através do firewall, permita que o WinDbg acesse a porta para todos os três dos diferentes tipos de rede.

Usar KD

No computador host, abra um prompt de comando. Digite o seguinte comando, onde n é o número da porta e MyKey é a chave que foi gerada automaticamente pelo BCDEdit quando você configurou o computador de destino:

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

Se você for solicitado a permitir que o WinDbg acesse a porta através do firewall, permita que o WinDbg acesse a porta para todos os três dos diferentes tipos de rede.

Reinicie o PC de destino

Quando o depurador estiver conectado e aguardando para se conectar, reinicie o computador de destino. Uma maneira de reiniciar o PC é usar este comando no prompt de comando de um administrador:

shutdown -r -t 0

Quando o destino é reiniciado, o depurador no sistema operativo anfitrião deve se conectar.

Depois de se conectar ao destino no host, pressione break no seu depurador e você pode começar a depuração.

Permitir que o depurador passe pelo firewall

Quando você tenta estabelecer uma conexão de depuração de rede pela primeira vez, você pode ser solicitado a permitir o acesso ao aplicativo de depuração (WinDbg ou KD) através do firewall. As versões de cliente do Windows exibem o prompt, mas as versões de servidor do Windows não exibem o prompt. Você deve responder ao prompt marcando as caixas para todos os três tipos de rede: domínio, privado e público.

Se não receber o prompt ou não marcou as opções quando o prompt estava disponível, deve usar o Painel de Controlo para permitir o acesso pelo firewall no computador anfitrião onde o depurador está a ser executado. Abra Painel de Controle > Sistema e Segurança e selecione Permitir um aplicativo através do Firewall do Windows.

• (WinDbg) Na lista de aplicações, localize processo do motor WinDbg (TCP) (todos).

• (WinDbg clássico) Na lista de aplicativos, localize Windows GUI Symbolic Debugger e Windows Kernel Debugger.

Use as caixas de seleção para permitir que esses aplicativos passem pelo firewall. Reinicie o aplicativo de depuração (WinDbg ou KD).

Chave de encriptação

Para manter o computador de destino seguro, os pacotes que viajam entre o host e os computadores de destino devem ser criptografados. Você deve usar uma chave de criptografia gerada automaticamente (fornecida pelo BCDEdit ao configurar o computador de destino). O uso de uma chave de criptografia gerada automaticamente é recomendado, pois é mais seguro e fornece um valor exclusivo que é usado para estabelecer a conexão com um destino específico.

A depuração de rede usa uma chave de 256 bits especificada como quatro valores de 64 bits, na base 36, separados por pontos. Cada valor de 64 bits é especificado usando até 13 caracteres. Os caracteres válidos são as letras de a até z e os dígitos de 0 a 9. Não são permitidos caracteres especiais.

Para especificar sua própria chave, abra um prompt de comando elevado no computador de destino. Digite o seguinte comando, onde w.x.y.z é o endereço IP do computador host, n é o número da porta e chave é a sua chave:

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

O computador de destino precisa ser reinicializado sempre que as dbgsettings são alteradas.

Dicas de solução de problemas

O aplicativo de depuração deve ser permitido através de firewalls

Quando você tenta estabelecer uma conexão de depuração de rede pela primeira vez, você pode ser solicitado a permitir o acesso ao aplicativo de depuração (WinDbg ou KD) através do firewall. As versões de cliente do Windows exibem o prompt, mas as versões de servidor do Windows não exibem o prompt. Você deve responder ao prompt marcando as caixas para todos os três tipos de rede: domínio, privado e público.

Se você não receber o prompt ou se não marcou as caixas quando o prompt estava disponível, você deve usar o Painel de Controle para permitir o acesso através do firewall. Abra Painel de Controle > Sistema e Segurança e selecione Permitir um aplicativo através do Firewall do Windows.

• (WinDbg) Na lista de aplicações, localize o processo do motor WinDbg (TCP) (todos).

• (WinDbg (Clássico)) Na lista de aplicativos, localize Windows GUI Symbolic Debugger e Windows Kernel Debugger.

Use as caixas de seleção para permitir que esses aplicativos passem pelo firewall. Role para baixo e selecione OK para salvar as alterações do firewall. Reinicie o depurador.

O número da porta deve estar no intervalo permitido pela diretiva de rede

O intervalo de números de porta que podem ser usados para depuração de rede pode ser limitado pela política de rede da sua empresa. Para determinar se a política da sua empresa limita o intervalo de portas que podem ser usadas para depuração de rede, consulte o administrador da rede. No computador de destino, abra um prompt de comando como administrador e digite o comando bcdedit /dbgsettings. A saída será semelhante à seguinte:

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

Na saída anterior, o valor da porta é 50085. Se o valor da porta estiver fora do intervalo permitido pelo administrador da rede, digite o seguinte comando. O valor w.x.y.z é o endereço IP do computador host e YourDebugPort é um número de porta no intervalo permitido.

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

Depois de alterar as configurações do depurador da máquina de destino, execute novamente o depurador na máquina host com a nova configuração de porta e, em seguida, reinicie o computador de destino.

Usar ping para testar a conectividade

Se o depurador não se conectar, use o comando ping no PC de destino para verificar a conectividade.

C:\>Ping <HostComputerIPAddress>

Como o depurador obtém um endereço IP para o computador de destino

KDNET no computador de destino tenta usar o protocolo DHCP (Dynamic Host Configuration Protocol) para obter um endereço IP roteável para o adaptador de rede que está sendo usado para depuração. Se o KDNET obtiver um endereço atribuído pelo DHCP, o computador de destino poderá ser depurado por computadores de anfitrião localizados em qualquer lugar da rede. Se o KDNET não conseguir obter um endereço atribuído pelo DHCP, ele usará o endereçamento IP privado automático (APIPA) para obter um endereço IP de link local. Os endereços IP de link local não são roteáveis, portanto, um host e um destino não podem usar um endereço IP de link local para se comunicar por meio de um roteador. Nesse caso, a depuração de rede funcionará se você conectar o host e os computadores de destino ao mesmo hub ou switch de rede.

Sempre especifique busparams ao configurar o KDNET em uma máquina física com uma NIC baseada em PCI

Se estiver a configurar o KDNET numa máquina física com uma placa de rede PCI ou PCIe, deve sempre especificar os busparams para a NIC que pretende utilizar para o KDNET. Para especificar os parâmetros de barramento, abra o Gerenciador de dispositivos e localize o adaptador de rede que você deseja usar para depuração. Abra a página de propriedades do adaptador de rede e anote o número do barramento, o número do dispositivo e o número da função que estão exibidos sob Localização na aba Geral. Numa linha de comandos com privilégios elevados, insira o seguinte comando, onde b, de f são os números de barramento, dispositivo e função no formato decimal:

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

Quando o depurador estiver em execução na máquina host e aguardando para se conectar, reinicie o computador de destino usando o seguinte comando:

shutdown -r -t 0

Excluir manualmente entradas BCDEdit

A exclusão manual normalmente não é necessária, mas é fornecida aqui como um procedimento de solução de problemas para situações incomuns.

A exclusão manual de entradas não é necessária ao usar o utilitário kdnet. Para obter mais informações, consulte Configurando a depuração do kernel de rede KDNET automaticamente.

Ao usar bcdedit –deletevalue, você deve fornecer um nome de elemento bcd válido. Para obter mais informações, consulte BCDEdit /deletevalue.

Para excluir manualmente as entradas bcdedit, conclua as seguintes etapas:

1. No computador de destino, abra um prompt de comando como administrador.

2. Como exemplo, digite o seguinte comando para excluir a entrada de depuração BCDEdit para o endereço IP do host:

   bcdedit -deletevalue {dbgsettings} hostip
   

Ao excluir o hostip, você precisa especificar target= na linha de comando do depurador.

3. Como outro exemplo, exclua a entrada de porta usando o seguinte comando:

   bcdedit -deletevalue {dbgsettings} port
   

Quando excluis a entrada de porta, o KDNET usa a porta padrão do depurador registada na ICANN de 5364.

Configurar Hyper-V

Se você pretende instalar a função Hyper-V no computador de destino, consulte Configurando a depuração de rede de um host de máquina virtual.

Para obter informações sobre como depurar uma máquina virtual (VM) Hyper-V, consulte Configurando a depuração de rede de uma máquina virtual - KDNET.

Habilite o KDNET em um host Hyper-V que esteja executando VMs com conectividade de rede externa

Às vezes, ocorre uma situação que faz com que a rede em VMs pare de funcionar:

• Hyper-V foi ativado no PC, um comutador de rede externo foi criado e está ligado a uma placa de rede física na máquina, e as VMs foram configuradas para usar esse comutador externo para a sua rede.

• O KDNET é então ativado no SO host Hyper-V usando a mesma NIC física apontada pelo switch de rede externo. O host é reinicializado.

• Todas as VMs que usaram o switch externo configurado anteriormente perdem sua conectividade de rede após a reinicialização.

Esta paragem é intencional e acontece porque o KDNET assume o controlo exclusivo sobre a NIC que está configurado para utilizar. A miniporta NDIS nativa para essa NIC não é carregada pelo sistema operacional. O switch de rede externo não pode mais se comunicar com o driver de miniporta NDIS nativo e para de funcionar. Para contornar essa situação, faça o seguinte:

1. Abra o Virtual Switch Manager a partir do Hyper-V Manager e selecione o seu Comutador Virtual existente. Altere a NIC da rede externa para o Microsoft Kernel Debug Network Adapter selecionando-a no menu suspenso e, em seguida, selecionando OK no diálogo do Virtual Switch Manager.

2. Depois de atualizar a NIC do Comutador Virtual, desligue e reinicie as VMs.

Quando a depuração KDNET está desativada, é necessário seguir o mesmo procedimento para redirecionar o comutador externo de volta para a miniporta NDIS nativa da NIC. Caso contrário, a conectividade da VM será perdida quando a máquina for reinicializada após a depuração ser desabilitada.

IPv6

O suporte a IPv6 foi adicionado na versão 1809 do Windows.

Para usar o IPv6 com o depurador, conclua as seguintes etapas:

1. Execute o comando ping no seu <debughostname> e anote o endereço IPv6 que é relatado nas linhas de resposta de saída. Use este endereço IPv6 no lugar de x:y:z:p:d:q:r:n.

2. Use BCDEdit para excluir quaisquer valores de endereço IP existentes em dbgsettings.

   bcdedit -deletevalue {dbgsettings} hostip
   

3. Defina o endereço IPv6 do host. Não deve haver espaços na cadeia de hostipv6=s:t:u:v:w:x:y:z. <YourPort> é o número da porta de rede a ser usado para esta máquina de destino. <YourKey> é a chave de segurança de quatro partes. <b.d.f> são os números de localização da função do dispositivo de barramento para a NIC que você deseja usar para o KDNET.

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

4. Digite este comando para confirmar se o dbgsettings está definido corretamente.

   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. Na máquina host, use o seguinte comando para iniciar o depurador:

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

6. Quando o depurador estiver em execução na máquina host e aguardando para se conectar, reinicie o computador de destino.

7. O depurador deve se conectar ao depurador host no início da inicialização. Você pode ver que o KDNET está usando uma conexão IPv6 porque os endereços IP relatados na mensagem conectada são endereços IPv6 em vez de endereços IPv4.

Observações

• Cada definição bcd do depurador que permite que o hostip seja especificado tem um elemento hostipv6 correspondente. São três.

  IPv4	IPv6	Utilização
  endereço IP do host	hostipv6	Para inicialização e depuração do kernel
  targethostip (endereço IP do host alvo)	targethostipv6	Específico para depuração do kernel
  Hypervisorhostip	hipervisorhostipv6	Para depuração do hyper-v

• Se você definir o endereço de estilo hostipv6 para qualquer um desses tipos de depuração, isso significa que você quer e obterá IPv6.

• Se você definir o endereço de estilo hostip para qualquer um desses tipos de depuração, isso significa que você deseja e obterá IPv4.

• O alvo só fará IPv4 ou IPv6, não os dois ao mesmo tempo. A versão do protocolo IP usada é controlada pela máquina de destino dbgsettings. Se hostip estiver definido, o destino usará IPv4. Se hostipv6 estiver definido, o destino usa IPv6.

• O depurador de host normalmente seleciona automaticamente o uso de IPv4 ou IPv6. Por padrão, o depurador escuta em um soquete IPv4 e em um soquete IPv6 e se conecta automaticamente em qualquer um deles à máquina de destino.

• Se quiser forçar o uso de IPv6 no depurador no host, mas quiser que o depurador espere por uma conexão do alvo, pode adicionar target=:: à linha de comando do depurador. :: é um endereço IPv6 de 0.

• Se você quiser forçar a depuração IPv4 no depurador no host, mas quiser que o depurador escute uma conexão do destino, então você pode adicionar target=0.0.0.0 à linha de comando do depurador. 0.0.0.0 é um endereço IPv4 de 0.

• Se você especificar target= na linha de comando do depurador e usar um nome de máquina, o depurador converterá esse nome de máquina em um endereço IPv4 e um endereço IPv6. Em seguida, o depurador tenta conectar-se a ambos.

• Quando você especifica target= na linha de comando do depurador e usa um endereço IP, se o endereço IP contiver caracteres :, o depurador assume que é um endereço IPv6 e força o uso do IPv6 para essa conexão. Se o endereço IP contiver algum . caracteres, o depurador assume que é um endereço IPv4 e força o uso do IPv4 para essa conexão.

• Se você configurar o IPv6 no destino e forçar o uso do IPv4 na linha de comando do depurador, não obterá uma conexão.

• Se você configurar o IPv4 no destino e forçar o uso do IPv6 na linha de comando do depurador, também não obterá uma conexão.

Ver também

• Configuração automática da depuração do kernel da rede KDNET

• NICs Ethernet suportadas para depuração do kernel de rede no Windows 10

• NICs Ethernet suportadas para depuração do kernel de rede no Windows 8.1