DotNetCurry Logo

Configure WinRM to execute PowerShell Script on a remote Azure machine with ARM

Posted by: Subodh Sohoni , on 6/16/2016, in Category Microsoft Azure
Views: 5274
Abstract: Use the WinRM service to execute PowerShell script on a remote machine in Azure that is under ARM

Microsoft has introduced Azure Resource Manager (ARM) to make it easier for managing Azure resources. It creates Resource Groups which are a collection of cloud services of virtual machines, virtual networks, network interfaces, network security rules, public IP address, storage accounts, etc. A virtual machine added to the resource group can be accessed in the build or release management task using a combination of the name of the resource group and fully qualified name (FQDN) of the virtual machine.

 

WinRM is a service that allows remote execution of PowerShell scripts over the HTTP or HTTPS connection. For running a PowerShell script from a remote machine, the virtual machine where the script has to run (we will call it as host) has to have WinRM listeners on HTTP and HTTPS protocols. These listeners use the port 5985 and 5986 respectively. Build service and Release Management service of TFS 2015 and Visual Studio Team Services (VSTS) have many tasks that use the WinRM service to execute PowerShell script on a remote machine in Azure that is under ARM.

release-management-task-powershell

Figure 1: Release Management task that runs a PowerShell script on target machine

A virtual machine that is created in the resource group of ARM can be easily configured to have listeners for WinRM service. WinRM Service listeners are already installed on those virtual machines. Those listeners are not accessible because, in Azure, communication endpoints for the ports 5985 and 5986 are not created by default for those VMs. For a VM that is in the workgroup, it is essential to bind the WinRM service to secure transport that uses HTTPS protocol. To enable access to WinRM HTTPS listener, we need to create an Inbound Rule to allow traffic on port 5986. For VMs under the Resource Group in ARM, port 5986 is already opened in the firewall.

inbound-rule-port-5986

Figure 2: Create Inbound Rule for Port 5986

When we configure a task that uses WinRM for executing a PowerShell script, it is expected to configure WinRM listener for HTTPS transport protocol on the target machine. The Fully Qualified Domain Name (FQDN) of the target machine is used to set up these tasks. Unfortunately, when executing such a task, it fails with an error “The SSL certificate contains a common name (CN) that does not match the hostname”. This error occurs because the WinRM listener configured on the target server does not have the SSL certificate that has the FQDN in the name. We can check the WinRM listeners in the configuration on the machine that is created by ARM by running the following command in the developer command prompt.

winrm e winrm/config/listener

Running this command may show the following configuration:

winrm-listeners-original

Figure 3: WinRM Listeners (as original)

You may observe that for a listener configured for HTTPS, the Hostname parameter has a value that is the IP address of the machine and not the FQDN. Let us now check if we do have an SSL certificate that has an FQDN as CN. For that run the command mmc.exe and select the snap-in for Certificates and select Computer account as the scope.

certificates-snapin-mmc

Figure 4: Certificates Snap-In to MMC

 

In the MMC snap-in for certificates, we will notice that no certificate is created for FQDN but there is one created for IP address.

certificates-on-target-machine

Figure 5: Certificates on Target machine

What we need to do is to create a certificate for FQDN and bind it to HTTPS transport protocol WinRM listener. Let us now check the FQDN of the target virtual machine. In the Azure portal, if we select the virtual machine and then Public IP Address / DNS Name, it will show us the FQDN as DNS name if that is configured. You can configure it if not already configured.

fqdn-target-machine

Figure 6: FQDN of Target Machine

Our next step is to create a certificate on the target machine that has FQDN as the hostname. For that, we can run a PowerShell cmdlet on that machine.

New-SelfSignedCertificate –DnsName ssrmdvm3.southeastasia.cloudapp.azure.com –CertStoreLocation Cert:\LocalMachine\My

This step will create a self-signed certificate for testing purposes. The output of the command will show a thumbprint of the certificate. That thumbprint is a 40 digit number.

self-signed-certificate-thumbprint

Figure 7: New Self Signed Certificate and its thumbprint

We will now delete the existing WinRM listener that is linked to SSL certificate with IP address and create a new listener that is linked to FQDN. To do so, we will execute two cmdlets in succession:

winrm delete winrm/config/listener?Address=*+Transport=HTTPS

winrm create winrm/config/listener?Address=*+Transport=HTTPS ‘@{Hostname=ssrmdvrm3.southeastasia.cloudapp.azure.com”; CertificateThumbprint=”Copy the thumbprint from earlier cmdlet output”;port=”5986”}’

delete-old-listener

Figure 8: Delete old listener and Create new listener

new-winrm-listener-created

Figure 9: New WinRM listener created

If we now check the listeners of WinRM by running the following command:

winrm e winrm/config/listeners

..we will see that Hostname of the HTTPS listeners reflects the FQDN.

winrm-listener-configuration-new

Figure 10: WinRM Listener Configuration (new)

If we run the same release with the task that needs to execute a PowerShell script remotely using WinRM, it works without any error.

Was this article worth reading? Share it with fellow developers too. Thanks!
Share on Google+
Further Reading - Articles You May Like!
Author
Subodh is a consultant and corporate trainer. He has overall 28+ years of experience. His specialization is Application Lifecycle Management and Team Foundation Server. He is Microsoft MVP – VS ALM, MCSD – ALM and MCT. He has conducted more than 300 corporate trainings and consulting assignments. He is also a Professional SCRUM Master. He guides teams to become Agile and implement SCRUM. Subodh is authorized by Microsoft to do ALM Assessments on behalf of Microsoft. Follow him on twitter @subodhsohoni


Page copy protected against web site content infringement 	by Copyscape




Feedback - Leave us some adulation, criticism and everything in between!