Windows Remote Management (WinRM) troubleshooting guide for remote sessions on the target machines

  • Article

Applies to:

Release Management 2013 Update 3 and later: Run PS DSC action.

Release Management 2015: Run PS DSC action.

Team Foundation Server 2015: PowerShell on Target Machines task in Build hub.

 

Most common causes:

The reasons for PowerShell session on the target machine to fail are:

  1. The remote machine does not have WinRM service running.
  2. The remote Machine is not configured to listen on the port which you specified (HTTP/HTTPS).
  3. The inbound firewall connection is not open for the WinRM port(HTTP/HTTPS) on the remote machine.
  4. If it is an Azure IaaS machine, you would need to configure its endpoints to open the required PowerShell port(HTTP/HTTPS). Check this link for how to do that: https://azure.microsoft.com/en-in/documentation/articles/virtual-machines-set-up-endpoints/.

By default in cases 1, 2 and 3 above if you are remoting over an HTTP port(5985 is the default) you can solve the problem by running this PowerShell command in the machine:

 Winrm quickconfig 

The above command will perform the following steps:

  • Start the WinRM service.
  • Set the WinRM service type to auto start.
  • Create an HTTP listener on port 5985 to accept requests on any IP address.
  • Enable firewall exception for WS-Management traffic (for http only).

 

For HTTPS, if you have provisioned your machine on Azure portal, you would just need to open the PowerSHell HTTPS endpoint 5986 as it would be configured already. If you want to establish HTTPS remote PowerShell session on some standard/on-prem machine you would need to install a self-signed or a CA authority certificate in the remote machine's Local Machine Personal certificate store and configure the WinRM HTTPS listener against that certificate.

 

Another useful cmdlet for configuring WinRM service for Remote PowerShell on the remote machine would be:

 Enable-PSRemoting

You need to run this PowerShell command on the remote machine. You can read more about it here: https://technet.microsoft.com/en-us/library/hh849694.aspx. This cmdlet can solve some issues, if winrm quickconfig does not seem to solve your problems.

 

Note: If you are using a workgroup machine or Azure machine or any machine outside the domain of the machine establishing remote connection where there is no trust or an IP address as the target machine name for remote PowerShell, it would use NTLM authentication instead of Kerberos Authentication. There if you are using HTTP you would need to add the remote host in the trusted hosts of the client machine establishing the remote PowerShell connection. Here is how to do it: https://winintro.ru/windowspowershell2corehelp.en/html/f23b65e2-c608-485d-95f5-a8c20e00f1fc.htm. Or else you can remote over HTTPS to these type of machines where you would not need to add it to the Trusted Hosts of the client.