winrm.md

Troubleshooting winrm usually involves running the automation (Packer build / Terraform apply) until winrm fails, then inspecting the system to see where the failure is occurring. To do so please try the following steps.

If you have destroyed the infrastructure, please spin it back up with the automation tool (Packer or Terraform) and let the provisioner or build fail.

Establish that you have connectivity to the network that the VM is hosted on. This can be done by checking the IP address(es) and using a tool like route.

Open a Powershell session on your Windows workstation. The winrm connectivity tools are not available on other operating systems. You can skip some steps or try to substitute for them, but it's best to use a Windows workstation. A Windows 10 VM can be spun up using Vagrant, for example.

Establish that a raw connection can be made to the winrm service from your workstation. Run the command Test-netConnection <IP address> -Port 5985, providing the IP address that Packer or Terraform is attempting to use to connect. The output should look like the following:

PS C:\Users\brent> Test-netConnection 40.85.185.16 -Port 5985


ComputerName     : 40.85.185.16
RemoteAddress    : 40.85.185.16
RemotePort       : 5985
InterfaceAlias   : Ethernet0
SourceAddress    : 172.16.83.129
TcpTestSucceeded : True

If you are using a certificate that is installed properly on both the workstation and the remote computer, you can also try port 5986, the HTTPS port. This will not work if the CAs are not correctly installed.

Establish that your local workstation can make a connection using the winrm protocol to the winrm service on the remote machine. Run the command Test-WSMan -ComputerName <IP address>. The output should be similar to the following:

PS C:\Users\brent> Test-WSMan -ComputerName 40.85.185.16


wsmid           : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor   : Microsoft Corporation
ProductVersion  : OS: 0.0.0 SP: 0.0 Stack: 3.0

Attempt to open a winrm session using the credentials specified in the Packer or Terraform configuration. Run the commands:

$options=New-PSSessionOption -SkipCACheck -SkipCNCheck

Enter-PSSession -ComputerName <IP address> -Credential <username> -UseSSL -SessionOption $options

Note that you will need to replace <username> with the admin username that was set on the instance. When executed, a login prompt will be displayed for the password, and once that is supplied a remote powershell prompt will be displayed at the terminal, as shown:

PS C:\Users\brent> $options=New-PSSessionOption -SkipCACheck -SkipCNCheck
>> Enter-PSSession -ComputerName 40.85.185.16 -Credential testadmin -UseSSL -SessionOption $options
>>
[40.85.185.16]: PS C:\Users\testadmin\Documents>

If the previous step does succeed, run the following two commandlets to get some additional information about the network and firewall:

Get-NetConnectionProfile
Get-NetFirewallProfile

If the previous steps did not succeed, please log into the VM using RDP and run the above two commands to obtain the output. Additionally, the winrm configuration and listener status can be viewed with the commands:

winrm get winrm/config
winrm enumerate winrm/config/listener

The most important items with the winrm config and listener status is to ensure that basic authentication is enabled and that the listener being attempted is enabled and functioning. The HTTPS listener will not start if the system does not have a valid certificate, for example.

One common issue is that the network interface is not set to the correct category. It should be set to Private, similar to the following:

Name             : Network
InterfaceAlias   : Ethernet
InterfaceIndex   : 3
NetworkCategory  : Private
IPv4Connectivity : Internet
IPv6Connectivity : NoTraffic

Another, less common issue, is that the winrm ports are not open in the firewall.

Here is a Powershell script from a Terraform provisioner example that works to set all required options for winrm to function:

$profiles = Get-NetConnectionProfile
Foreach ($i in $profiles) {
    Write-Host ("Updating Interface ID {0} to be Private.." -f $profiles.InterfaceIndex)
    Set-NetConnectionProfile -InterfaceIndex $profiles.InterfaceIndex -NetworkCategory Private
}

Write-Host "Obtaining the Thumbprint of the Certificate from KeyVault"
$Thumbprint = (Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.Subject -match "$ComputerName"}).Thumbprint

Write-Host "Enable HTTPS in WinRM.."
winrm create winrm/config/Listener?Address=*+Transport=HTTPS "@{Hostname=`"$ComputerName`"; CertificateThumbprint=`"$Thumbprint`"}"

Write-Host "Enabling Basic Authentication.."
winrm set winrm/config/service/Auth "@{Basic=`"true`"}"

Write-Host "Re-starting the WinRM Service"
net stop winrm
net start winrm

Write-Host "Open Firewall Ports"
netsh advfirewall firewall add rule name="Windows Remote Management (HTTPS-In)" dir=in action=allow protocol=TCP localport=5986

To summarize:

• Check connectivity and network configuration
• Check certificates
• Check winrm service
• Check network category
• Check firewall

Hopefully this helps you to locate the source of the issue.