Setting up machines for Windows Remote Management (WinRM) deployment tasks
Applies to:
Release Management 2013 Update 3 and later: Run PS DSC action.
Release Management 2015: Run PS DSC action.
Team Foundation Server 2015: Windows Remote Management based tasks in Build Hub wiz. PowerShell on Target Machines, Visual Studio Test Agent Deployment, Windows Machine File Copy.
Visual Studio Online: Windows Remote Management based tasks in Build and Release Management Hub wiz. PowerShell on Remote Machines, Azure File Copy to Azure VMs, SQL Server Database Deployment, IIS Web Application Deployment, Visual Studio Test Agent Deployment
The tasks as described above use Windows Remote Management (WinRM) to access domain-joined/workgroup machines or Azure virtual machines. WinRM is Microsoft’s implementation of WS-Management Protocol that is firewall-friendly and provides a common way for systems to access and exchange management information across on-premises or Cloud IT infrastructure. The automation agent that runs the deployment tasks uses WinRM to communicate with the target machines. It is important to setup WinRM properly on the target machines else the tasks will fail. The configuration of WinRM is described in detail on the MSDN site. For the target machines the following will ensure that the WinRM has been setup properly on them:
- Azure virtual machines only work with the WinRM HTTPS protocol. When creating classic or resource manager virtual machine from the Azure preview portal or Azure portal, the virtual machine is already setup for WinRM HTTPS, with the default port 5986 already open in Firewall, and a test certificate installed on the machine. These virtual machines can be directly added to a machine group, with the WinRM protocol selected as HTTPS, and the Skip CA Check (or Test Certificate) option selected. The Skip CA Check means that the certificate is a test certificate and the client should skip the validation of the certificate by a trusted certification authority.
- To dynamically deploy Azure resource groups with virtual machines in them use the Azure Resource Group Deployment task. The task has a sample template that can setup the WinRM HTTPS protocol on the virtual machines, open the 5986 port in the Firewall, and install the test certificate.After this the virtual machines are ready for use in the deployment task.
- For pre-existing on-premises machines, domain-joined or workgroup, and whether they are physical machines or virtual machines, set them up as per the table below to ensure that the deployment tasks work fine with them:
Target Machine State: Domain joined machine in a corporate network.
Target Machine Trust with Automation Agent: Trusted.
Machine Identity: DNS name.
Authentication Account: Domain account.
Authentication Mode: Kerberos.
Authentication Account Permission on Target Machine: Machine Administrator.
Connection Type: WinRM HTTP .
Pre-requisites in target machine for WinRM deployment tasks to succeed: In the target machine, the WinRM HTTP port (default 5985) should be open in the Firewall and File & Printer sharing should be enabled.
Target Machine State: Domain joined machine in a corporate network.
Target Machine Trust with Automation Agent: Trusted.
Machine Identity: DNS name.
Authentication Account: Domain account.
Authentication Mode: Kerberos.
Authentication Account Permission on Target Machine: Machine Administrator.
Connection Type: WinRM HTTPS.
Pre-requisites in target machine for WinRM deployment tasks to succeed: In the target machine, the WinRM HTTPS port (default 5986) should be open in the Firewall and the File & Printer sharing should be enabled. The trusted certificate should be installed in the Automation agent, and if the trusted certificate is not installed in the Automation agent, then ensure that the skip CA check (or Test Certificate) option is selected in the tasks/machines hub for the application deployment to work.
Target Machine State: Domain joined machine, or workgroup machine in a corporate network.
Target Machine Trust with Automation Agent: Trusted or untrusted.
Machine Identity: DNS name.
Authentication Account: Local machine
account.
Authentication Mode: NTLM.
Authentication Account Permission on Target Machine: Machine Administrator.
Connection Type: WinRM HTTP.
Pre-requisites in target machine for WinRM deployment tasks to succeed: In the target machine, the WinRM HTTP port (default 5985) should be opened in the Firewall, and UAC remote restrictions should be disabled, and the File & Printer sharing should be enabled. The target machine credentials should be provided in the format of domain\accountname or machine\accountname. Set the "AllowUnencrypted" option in the target machine, and add the remote machine in the "Trusted Host" list in the Automation Agent as shown in the command below:
Automation Agent -
winrm qc
cd wsman:localhost\Client;Set-Item TrustedHosts -Value “machine name” -force
Target Machine -
Winrm qc
cd wsman:localhost\Client;Set-Item AllowUnencrypted -Value $true -force
Target Machine State: Domain joined machine, or workgroup machine in a corporate network.
Target Machine Trust with Automation Agent: Trusted or untrusted.
Machine Identity: DNS name.
Authentication Account: Local machine
account.
Authentication Mode: NTLM.
Authentication Account Permission on Target Machine: Machine Administrator.
Connection Type: WinRM HTTPS.
Pre-requisites in target machine for WinRM deployment tasks to succeed: In the target machine, the WinRM HTTP port (default 5985) should be opened in the Firewall, and UAC remote restrictions should be disabled, and the File & Printer sharing should be enabled. The target machine credentials should be provided in the format of domain\accountname or machine\accountname. The trusted certificate should be installed in the Automation agent, and if the trusted certificate is not installed in the Automation agent, then ensure that the skip CA check (or Test Certificate) option is selected in the tasks/machines hub for the application deployment to work.