Overview
If you're new to WinRM (or an oldtimer), this is a good time to refresh the knowledge :) PowershellOrg has a very nice tutorial on WinRM called Secrets of Powershell Remoting. We suggest to read through the second and third chapters (~15 minutes read).
WinRM over HTTPS
Here's the summary of configuration steps in the order of execution:
On Agent Machine (local) | On Target Machine (remote) |
---|---|
(3) Test WinRM connection | (1) Create or install SSL certificate for remote machine |
(2) Configure WinRM server to listen over HTTPS connection |
Run the following commands on the Target machine:
# Modify these variables
$WinRMPort = 5986
$HostName = mycloudvm.cloudapp.net # or the public IP address
# Create Self Signed certificate
# For Windows server 2008, check this blog for a powershell based approach:
# http://blogs.technet.com/b/vishalagarwal/archive/2009/08/22/generating-a-certificate-self-signed-using-powershell-and-certenroll-interfaces.aspx
# Or use the following makecert.exe command line:
# makecert.exe -r -pe -n "CN=$HostName,O=Fabrikam Fiber Inc" -e mm/dd/yyyy -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 ~\Downloads\winrmcert.cer
# For Windows server 2012 onwards
# New-SelfSignedCertificate is available on Windows Server 2012 or Windows 8.1 onwards
$cert = New-SelfSignedCertificate -DnsName $HostName -CertStoreLocation Cert:\LocalMachine\My
# Now setup WinRM (long commands are broken with a trailing ` for readability)
# Enable-WinRM will enable WinRM setup for HTTP only
Enable-PSRemoting -SkipNetworkProfileCheck
New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * `
-CertificateThumbPrint $cert.Thumbprint –Force -Verbose
New-NetFirewallRule -DisplayName "Windows Remote Management (HTTPS-In)"`
-Name "Windows Remote Management (HTTPS-In)" -Profile Any -LocalPort $WinRMPort -Protocol TCP
# This command requires Windows 2012 or above
# Export the certificate to import in the Agent machine
Export-Certificate -Cert $cert -FilePath ~\Downloads\winrmcert.cer
Run the following commands on the Agent machine:
# Download the certificate generated in Target machine to
# ~\Downloads\winrmcert.cer
Import-Certificate -FilePath .\Downloads\winrmcert.cer -CertStoreLocation Cert:\LocalMachine\Root
WinRM over HTTP
Run the following command on the Target machine:
# SkipNetworkProfileCheck enables clients in public network to access
# the target machine.
# Read more: https://technet.microsoft.com/en-us/library/hh849694.aspx
Enable-PSRemoting -SkipNetworkProfileCheck
Set-NetFirewallRule –Name "WINRM-HTTP-In-TCP-PUBLIC" –RemoteAddress Any
Configure WinRM for Azure Machines
Configure endpoints for WinRM
On classic Azure VMs: https://azure.microsoft.com/en-in/documentation/articles/virtual-machines-set-up-endpoints/
On Azure Resource Manager based VMs: https://azure.microsoft.com/en-in/documentation/articles/virtual-networks-nsg/
Create an inbound rule which can allow TCP traffic on port 5986.
Please check out Pre-requisites for using Azure VMs in WinRM based Tasks in Build and Release management workflows.
Troubleshooting WinRM Connections
Use the following commands in the Agent or client machine to test winrm connection:
# Replace 11.2.7.194 with the FQDN or IP address of the Target machine
Test-WSMan -ComputerName 11.2.7.194 -Credential (Get-Credential) -UseSSL -Verbose -Authentication Negotiate
Use the following commands to view current WinRM settings (on Target or server machine):
Get-ChildItem TODO
Get-NetFirewallPortFilter -Protocol TCP | Where-Object { $_.LocalPort -eq 5985 -or $_.LocalPort -eq 5986 }
We will cover a few common error scenarios below.
Error Message: No line of sight
Test-WSMan : <f:WSManFault
xmlns:f="http://schemas.microsoft.com/wbem/wsman/1/wsmanfault"
Code="2150859046"Machine="ws2012-agent"> <f:Message>WinRM cannot complete the
operation. Verify that the specified computer name isvalid, that the computer is
accessible over the network, and that a firewall exception for the WinRM service
isenabled and allows access from this computer. By default, the WinRM firewall
exception for public profiles limitsaccess to remote computers within the same
local subnet. </f:Message></f:WSManFault>At line:1 char:1+ Test-WSMan
-ComputerName 192.1.168.23 -Credential (Get-Credential) -UseSSL -Ve ...+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
CategoryInfo : InvalidOperation: (192.1.168.23:String) [Test-WSMan],
InvalidOperationException+ FullyQualifiedErrorId :
WsManError,Microsoft.WSMan.Management.TestWSManCommand
Troubleshooting
Let's run through the various possible hypothesis here.
- Client (Agent) machine can't see the Server (Target) machine
# Try the regular networking toolset
TODO
Error Message: Invalid SSL configuration
Test-WSMan : <f:WSManFault
xmlns:f="http://schemas.microsoft.com/wbem/wsman/1/wsmanfault"
Code="12175"Machine="ws2012-agent"><f:Message>The server certificate on the
destination computer (192.1.168.23:5986) has thefollowing errors:The SSL
certificate is signed by an unknown certificate authority.
</f:Message></f:WSManFault>At line:1 char:1+ Test-WSMan -ComputerName
192.1.168.23 -Credential (Get-Credential) -UseSSL -Ve ...+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
CategoryInfo : InvalidOperation: (192.1.168.23:String) [Test-WSMan],
InvalidOperationException+ FullyQualifiedErrorId :
WsManError,Microsoft.WSMan.Management.TestWSManCommand
Error Message: Invalid client side configuration
Test-WSMan : <f:WSManFault
xmlns:f="http://schemas.microsoft.com/wbem/wsman/1/wsmanfault"
Code="5"Machine="ws2012-agent"><f:Message>The WinRM client cannot process the
request. The authentication mechanism requestedby the client is not supported by
the server or unencrypted traffic is disabled in the service configuration.
Verifythe unencrypted traffic setting in the service configuration or specify
one of the authentication mechanisms supportedby the server. To use Kerberos,
specify the computer name as the remote destination. Also verify that the
client computer and the destination computer are joined to a domain. To use
Basic, specify the computer name as the remotedestination, specify Basic
authentication and provide user name and password. Possible authentication
mechanisms reported by server: Negotiate </f:Message></f:WSManFault>At
line:1 char:1+ Test-WSMan -ComputerName 192.1.168.23 -Credential
(Get-Credential) -UseSSL -Ve ...+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
CategoryInfo : InvalidOperation: (192.1.168.23:String) [Test-WSMan],
InvalidOperationException+ FullyQualifiedErrorId :
WsManError,Microsoft.WSMan.Management.TestWSManCommand
Try Negotiate NTLM