Windows Remote Management

Unlike Linux/Unix hosts, which use SSH by default, Windows hosts areconfigured with WinRM. This topic covers how to configure and use WinRM with Ansible.

What is WinRM?

WinRM is a management protocol used by Windows to remotely communicate withanother server. It is a SOAP-based protocol that communicates over HTTP/HTTPS, and isincluded in all recent Windows operating systems. Since WindowsServer 2012, WinRM has been enabled by default, but in most cases extraconfiguration is required to use WinRM with Ansible.

Ansible uses the pywinrm package tocommunicate with Windows servers over WinRM. It is not installed by defaultwith the Ansible package, but can be installed by running the following:

  1. pip install "pywinrm>=0.3.0"

Note

on distributions with multiple python versions, use pip2 or pip2.x,where x matches the python minor version Ansible is running under.

Authentication Options

When connecting to a Windows host, there are several different options that can be usedwhen authenticating with an account. The authentication type may be set on inventoryhosts or groups with the ansible_winrm_transport variable.

The following matrix is a high level overview of the options:

OptionLocal AccountsActive Directory AccountsCredential DelegationHTTP Encryption
BasicYesNoNoNo
CertificateYesNoNoNo
KerberosNoYesYesYes
NTLMYesYesNoYes
CredSSPYesYesYesYes

Basic

Basic authentication is one of the simplest authentication options to use, but isalso the most insecure. This is because the username and password are simplybase64 encoded, and if a secure channel is not in use (eg, HTTPS) then it can bedecoded by anyone. Basic authentication can only be used for local accounts (not domain accounts).

The following example shows host vars configured for basic authentication:

  1. ansible_user: LocalUsername
  2. ansible_password: Password
  3. ansible_connection: winrm
  4. ansible_winrm_transport: basic

Basic authentication is not enabled by default on a Windows host but can beenabled by running the following in PowerShell:

  1. Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true

Certificate

Certificate authentication uses certificates as keys similar to SSH keypairs, but the file format and key generation process is different.

The following example shows host vars configured for certificate authentication:

  1. ansible_connection: winrm
  2. ansible_winrm_cert_pem: /path/to/certificate/public/key.pem
  3. ansible_winrm_cert_key_pem: /path/to/certificate/private/key.pem
  4. ansible_winrm_transport: certificate

Certificate authentication is not enabled by default on a Windows host but canbe enabled by running the following in PowerShell:

  1. Set-Item -Path WSMan:\localhost\Service\Auth\Certificate -Value $true

Note

Encrypted private keys cannot be used as the urllib3 library thatis used by Ansible for WinRM does not support this functionality.

Generate a Certificate

A certificate must be generated before it can be mapped to a local user.This can be done using one of the following methods:

  • OpenSSL
  • PowerShell, using the New-SelfSignedCertificate cmdlet
  • Active Directory Certificate Services

Active Directory Certificate Services is beyond of scope in this documentation but may bethe best option to use when running in a domain environment. For more information,see the Active Directory Certificate Services documentation).

Note

Using the PowerShell cmdlet New-SelfSignedCertificate to generatea certificate for authentication only works when being generated from aWindows 10 or Windows Server 2012 R2 host or later. OpenSSL is still required toextract the private key from the PFX certificate to a PEM file for Ansibleto use.

To generate a certificate with OpenSSL:

  1. # set the name of the local user that will have the key mapped to
  2. USERNAME="username"
  3.  
  4. cat > openssl.conf << EOL
  5. distinguished_name = req_distinguished_name
  6. [req_distinguished_name]
  7. [v3_req_client]
  8. extendedKeyUsage = clientAuth
  9. subjectAltName = otherName:1.3.6.1.4.1.311.20.2.3;UTF8:[email protected]
  10. EOL
  11.  
  12. export OPENSSL_CONF=openssl.conf
  13. openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -out cert.pem -outform PEM -keyout cert_key.pem -subj "/CN=$USERNAME" -extensions v3_req_client
  14. rm openssl.conf

To generate a certificate with New-SelfSignedCertificate:

  1. # set the name of the local user that will have the key mapped
  2. $username = "username"
  3. $output_path = "C:\temp"
  4.  
  5. # instead of generating a file, the cert will be added to the personal
  6. # LocalComputer folder in the certificate store
  7. $cert = New-SelfSignedCertificate -Type Custom `
  8. -Subject "CN=$username" `
  9. -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.2","2.5.29.17={text}[email protected]") `
  10. -KeyUsage DigitalSignature,KeyEncipherment `
  11. -KeyAlgorithm RSA `
  12. -KeyLength 2048
  13.  
  14. # export the public key
  15. $pem_output = @()
  16. $pem_output += "-----BEGIN CERTIFICATE-----"
  17. $pem_output += [System.Convert]::ToBase64String($cert.RawData) -replace ".{64}", "$&`n"
  18. $pem_output += "-----END CERTIFICATE-----"
  19. [System.IO.File]::WriteAllLines("$output_path\cert.pem", $pem_output)
  20.  
  21. # export the private key in a PFX file
  22. [System.IO.File]::WriteAllBytes("$output_path\cert.pfx", $cert.Export("Pfx"))

Note

To convert the PFX file to a private key that pywinrm can use, runthe following command with OpenSSLopenssl pkcs12 -in cert.pfx -nocerts -nodes -out cert_key.pem -passin pass: -passout pass:

Import a Certificate to the Certificate Store

Once a certificate has been generated, the issuing certificate needs to beimported into the Trusted Root Certificate Authorities of theLocalMachine store, and the client certificate public key must be presentin the Trusted People folder of the LocalMachine store. For this example,both the issuing certificate and public key are the same.

Following example shows how to import the issuing certificate:

  1. $cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2
  2. $cert.Import("cert.pem")
  3.  
  4. $store_name = [System.Security.Cryptography.X509Certificates.StoreName]::Root
  5. $store_location = [System.Security.Cryptography.X509Certificates.StoreLocation]::LocalMachine
  6. $store = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $store_name, $store_location
  7. $store.Open("MaxAllowed")
  8. $store.Add($cert)
  9. $store.Close()

Note

If using ADCS to generate the certificate, then the issuingcertificate will already be imported and this step can be skipped.

The code to import the client certificate public key is:

  1. $cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2
  2. $cert.Import("cert.pem")
  3.  
  4. $store_name = [System.Security.Cryptography.X509Certificates.StoreName]::TrustedPeople
  5. $store_location = [System.Security.Cryptography.X509Certificates.StoreLocation]::LocalMachine
  6. $store = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $store_name, $store_location
  7. $store.Open("MaxAllowed")
  8. $store.Add($cert)
  9. $store.Close()

Mapping a Certificate to an Account

Once the certificate has been imported, it needs to be mapped to the local user account.

This can be done with the following PowerShell command:

  1. $username = "username"
  2. $password = ConvertTo-SecureString -String "password" -AsPlainText -Force
  3. $credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password
  4.  
  5. # this is the issuer thumbprint which in the case of a self generated cert
  6. # is the public key thumbprint, additional logic may be required for other
  7. # scenarios
  8. $thumbprint = (Get-ChildItem -Path cert:\LocalMachine\root | Where-Object { $_.Subject -eq "CN=$username" }).Thumbprint
  9.  
  10. New-Item -Path WSMan:\localhost\ClientCertificate `
  11. -Subject "[email protected]" `
  12. -URI * `
  13. -Issuer $thumbprint `
  14. -Credential $credential `
  15. -Force

Once this is complete, the hostvar ansible_winrm_cert_pem should be set tothe path of the public key and the ansible_winrm_cert_key_pem variable should be set tothe path of the private key.

NTLM

NTLM is an older authentication mechanism used by Microsoft that can supportboth local and domain accounts. NTLM is enabled by default on the WinRMservice, so no setup is required before using it.

NTLM is the easiest authentication protocol to use and is more secure thanBasic authentication. If running in a domain environment, Kerberos should be usedinstead of NTLM.

Kerberos has several advantages over using NTLM:

  • NTLM is an older protocol and does not support newer encryptionprotocols.
  • NTLM is slower to authenticate because it requires more round trips to the host inthe authentication stage.
  • Unlike Kerberos, NTLM does not allow credential delegation.

This example shows host variables configured to use NTLM authentication:

  1. ansible_user: LocalUsername
  2. ansible_password: Password
  3. ansible_connection: winrm
  4. ansible_winrm_transport: ntlm

Kerberos

Kerberos is the recommended authentication option to use when running in adomain environment. Kerberos supports features like credential delegation andmessage encryption over HTTP and is one of the more secure options thatis available through WinRM.

Kerberos requires some additional setup work on the Ansible host before it can beused properly.

The following example shows host vars configured for Kerberos authentication:

  1. ansible_user: [email protected]
  2. ansible_password: Password
  3. ansible_connection: winrm
  4. ansible_winrm_transport: kerberos

As of Ansible version 2.3, the Kerberos ticket will be created based onansible_user and ansible_password. If running on an older version ofAnsible or when ansible_winrm_kinit_mode is manual, a Kerberosticket must already be obtained. See below for more details.

There are some extra host variables that can be set:

  1. ansible_winrm_kinit_mode: managed/manual (manual means Ansible will not obtain a ticket)
  2. ansible_winrm_kinit_cmd: the kinit binary to use to obtain a Kerberos ticket (default to kinit)
  3. ansible_winrm_service: overrides the SPN prefix that is used, the default is ``HTTP`` and should rarely ever need changing
  4. ansible_winrm_kerberos_delegation: allows the credentials to traverse multiple hops
  5. ansible_winrm_kerberos_hostname_override: the hostname to be used for the kerberos exchange

Installing the Kerberos Library

Some system dependencies that must be installed prior to using Kerberos. The script below lists the dependencies based on the distro:

  1. # Via Yum (RHEL/Centos/Fedora)
  2. yum -y install python-devel krb5-devel krb5-libs krb5-workstation
  3.  
  4. # Via Apt (Ubuntu)
  5. sudo apt-get install python-dev libkrb5-dev krb5-user
  6.  
  7. # Via Portage (Gentoo)
  8. emerge -av app-crypt/mit-krb5
  9. emerge -av dev-python/setuptools
  10.  
  11. # Via Pkg (FreeBSD)
  12. sudo pkg install security/krb5
  13.  
  14. # Via OpenCSW (Solaris)
  15. pkgadd -d http://get.opencsw.org/now
  16. /opt/csw/bin/pkgutil -U
  17. /opt/csw/bin/pkgutil -y -i libkrb5_3
  18.  
  19. # Via Pacman (Arch Linux)
  20. pacman -S krb5

Once the dependencies have been installed, the python-kerberos wrapper canbe install using pip:

  1. pip install pywinrm[kerberos]

Configuring Host Kerberos

Once the dependencies have been installed, Kerberos needs to be configured sothat it can communicate with a domain. This configuration is done through the/etc/krb5.conf file, which is installed with the packages in the script above.

To configure Kerberos, in the section that starts with:

  1. [realms]

Add the full domain name and the fully qualified domain names of the primaryand secondary Active Directory domain controllers. It should look somethinglike this:

  1. [realms]
  2. MY.DOMAIN.COM = {
  3. kdc = domain-controller1.my.domain.com
  4. kdc = domain-controller2.my.domain.com
  5. }

In the section that starts with:

  1. [domain_realm]

Add a line like the following for each domain that Ansible needs access for:

  1. [domain_realm]
  2. .my.domain.com = MY.DOMAIN.COM

You can configure other settings in this file such as the default domain. Seekrb5.conffor more details.

Automatic Kerberos Ticket Management

Ansible version 2.3 and later defaults to automatically managing Kerberos ticketswhen both ansible_user and ansible_password are specified for a host. Inthis process, a new ticket is created in a temporary credential cache for eachhost. This is done before each task executes to minimize the chance of ticketexpiration. The temporary credential caches are deleted after each taskcompletes and will not interfere with the default credential cache.

To disable automatic ticket management, set ansible_winrm_kinit_mode=manualvia the inventory.

Automatic ticket management requires a standard kinit binary on the controlhost system path. To specify a different location or binary name, set theansible_winrm_kinit_cmd hostvar to the fully qualified path to a MIT krbv5kinit-compatible binary.

Manual Kerberos Ticket Management

To manually manage Kerberos tickets, the kinit binary is used. Toobtain a new ticket the following command is used:

  1. kinit [email protected]

Note

The domain must match the configured Kerberos realm exactly, and must be in upper case.

To see what tickets (if any) have been acquired, use the following command:

  1. klist

To destroy all the tickets that have been acquired, use the following command:

  1. kdestroy

Troubleshooting Kerberos

Kerberos is reliant on a properly-configured environment towork. To troubleshoot Kerberos issues, ensure that:

  • The hostname set for the Windows host is the FQDN and not an IP address.

  • The forward and reverse DNS lookups are working properly in the domain. Totest this, ping the windows host by name and then use the ip address returnedwith nslookup. The same name should be returned when using nslookupon the IP address.

  • The Ansible host’s clock is synchronized with the domain controller. Kerberosis time sensitive, and a little clock drift can cause the ticket generationprocess to fail.

  • Ensure that the fully qualified domain name for the domain is configured inthe krb5.conf file. To check this, run:

  1. kinit -C [email protected]
  2. klist

If the domain name returned by klist is different from the one requested,an alias is being used. The krb5.conf file needs to be updated so thatthe fully qualified domain name is used and not an alias.

  • If the default kerberos tooling has been replaced or modified (some IdM solutions may do this), this may cause issues when installing or upgrading the Python Kerberos library. As of the time of this writing, this library is called pykerberos and is known to work with both MIT and Heimdal Kerberos libraries. To resolve pykerberos installation issues, ensure the system dependencies for Kerberos have been met (see: Installing the Kerberos Library), remove any custom Kerberos tooling paths from the PATH environment variable, and retry the installation of Python Kerberos library package.

CredSSP

CredSSP authentication is a newer authentication protocol that allowscredential delegation. This is achieved by encrypting the username and passwordafter authentication has succeeded and sending that to the server using theCredSSP protocol.

Because the username and password are sent to the server to be used for doublehop authentication, ensure that the hosts that the Windows host communicates with arenot compromised and are trusted.

CredSSP can be used for both local and domain accounts and also supportsmessage encryption over HTTP.

To use CredSSP authentication, the host vars are configured like so:

  1. ansible_user: Username
  2. ansible_password: Password
  3. ansible_connection: winrm
  4. ansible_winrm_transport: credssp

There are some extra host variables that can be set as shown below:

  1. ansible_winrm_credssp_disable_tlsv1_2: when true, will not use TLS 1.2 in the CredSSP auth process

CredSSP authentication is not enabled by default on a Windows host, but canbe enabled by running the following in PowerShell:

  1. Enable-WSManCredSSP -Role Server -Force

Installing CredSSP Library

The requests-credssp wrapper can be installed using pip:

  1. pip install pywinrm[credssp]

CredSSP and TLS 1.2

By default the requests-credssp library is configured to authenticate overthe TLS 1.2 protocol. TLS 1.2 is installed and enabled by default for Windows Server 2012and Windows 8 and more recent releases.

There are two ways that older hosts can be used with CredSSP:

  • Install and enable a hotfix to enable TLS 1.2 support (recommendedfor Server 2008 R2 and Windows 7).
  • Set ansible_winrm_credssp_disable_tlsv1_2=True in the inventory to runover TLS 1.0. This is the only option when connecting to Windows Server 2008, whichhas no way of supporting TLS 1.2

To enable TLS 1.2 support on Server 2008 R2 and Windows 7, the optional updateKRB3080079needs to be installed.

Once the update has been applied and the Windows host rebooted, run the followingPowerShell commands to enable TLS 1.2:

  1. $reg_path = "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProvider\SCHANNEL\Protocols\TLS 1.2"
  2. New-Item -Path $reg_path
  3. New-Item -Path "$reg_path\Server"
  4. New-Item -Path "$reg_path\Client"
  5.  
  6. New-ItemProperty -Path "$reg_path\Server" -Name "Enabled" -Value 1 -PropertyType DWord
  7. New-ItemProperty -Path "$reg_path\Server" -Name "DisabledByDefault" -Value 0 -PropertyType DWord
  8. New-ItemProperty -Path "$reg_path\Client" -Name "Enabled" -Value 1 -PropertyType DWord
  9. New-ItemProperty -Path "$reg_path\Client" -Name "DisabledByDefault" -Value 0 -PropertyType DWord

Set CredSSP Certificate

CredSSP works by encrypting the credentials through the TLS protocol and uses a self-signed certificate by default. The CertificateThumbprint option under the WinRM service configuration can be used to specify the thumbprint ofanother certificate.

Note

This certificate configuration is independent of the WinRM listenercertificate. With CredSSP, message transport still occurs over the WinRM listener,but the TLS-encrypted messages inside the channel use the service-level certificate.

To explicitly set the certificate to use for CredSSP:

  1. # note the value $certificate_thumbprint will be different in each
  2. # situation, this needs to be set based on the cert that is used.
  3. $certificate_thumbprint = "7C8DCBD5427AFEE6560F4AF524E325915F51172C"
  4.  
  5. # set the thumbprint value
  6. Set-Item -Path WSMan:\localhost\Service\CertificateThumbprint -Value $certificate_thumbprint

Non-Administrator Accounts

WinRM is configured by default to only allow connections from accounts in the localAdministrators group. This can be changed by running:

  1. winrm configSDDL default

This will display an ACL editor, where new users or groups may be added. To run commandsover WinRM, users and groups must have at least the Read and Execute permissionsenabled.

While non-administrative accounts can be used with WinRM, most typical server administrationtasks require some level of administrative access, so the utility is usually limited.

WinRM Encryption

By default WinRM will fail to work when running over an unencrypted channel.The WinRM protocol considers the channel to be encrypted if using TLS over HTTP(HTTPS) or using message level encryption. Using WinRM with TLS is therecommended option as it works with all authentication options, but requiresa certificate to be created and used on the WinRM listener.

The ConfigureRemotingForAnsible.ps1 creates a self-signed certificate andcreates the listener with that certificate. If in a domain environment, ADCScan also create a certificate for the host that is issued by the domain itself.

If using HTTPS is not an option, then HTTP can be used when the authenticationoption is NTLM, Kerberos or CredSSP. These protocols will encryptthe WinRM payload with their own encryption method before sending it to theserver. The message-level encryption is not used when running over HTTPS because theencryption uses the more secure TLS protocol instead. If both transport andmessage encryption is required, set ansible_winrm_message_encryption=alwaysin the host vars.

A last resort is to disable the encryption requirement on the Windows host. Thisshould only be used for development and debugging purposes, as anything sentfrom Ansible can viewed by anyone on the network. To disable the encryptionrequirement, run the following from PowerShell on the target host:

  1. Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true

Note

Do not disable the encryption check unless it isabsolutely required. Doing so could allow sensitive information likecredentials and files to be intercepted by others on the network.

Inventory Options

Ansible’s Windows support relies on a few standard variables to indicate theusername, password, and connection type of the remote hosts. These variablesare most easily set up in the inventory, but can be set on the host_vars/group_vars level.

When setting up the inventory, the following variables are required:

  1. # it is suggested that these be encrypted with ansible-vault:
  2. # ansible-vault edit group_vars/windows.yml
  3. ansible_connection: winrm
  4.  
  5. # may also be passed on the command-line via --user
  6. ansible_user: Administrator
  7.  
  8. # may also be supplied at runtime with --ask-pass
  9. ansible_password: SecretPasswordGoesHere

Using the variables above, Ansible will connect to the Windows host with Basicauthentication through HTTPS. If ansible_user has a UPN value likeusername@MY.DOMAIN.COM then the authentication option will automatically attemptto use Kerberos unless ansible_winrm_transport has been set to something other thankerberos.

The following custom inventory variables are also supportedfor additional configuration of WinRM connections:

  • ansible_port: The port WinRM will run over, HTTPS is 5986 which isthe default while HTTP is 5985
  • ansible_winrm_scheme: Specify the connection scheme (http orhttps) to use for the WinRM connection. Ansible uses https by defaultunless ansible_port is 5985
  • ansible_winrm_path: Specify an alternate path to the WinRM endpoint,Ansible uses /wsman by default
  • ansible_winrm_realm: Specify the realm to use for Kerberosauthentication. If ansible_user contains @, Ansible will use the partof the username after @ by default
  • ansible_winrm_transport: Specify one or more authentication transportoptions as a comma-separated list. By default, Ansible will use kerberos,basic if the kerberos module is installed and a realm is defined,otherwise it will be plaintext
  • ansible_winrm_server_cert_validation: Specify the server certificatevalidation mode (ignore or validate). Ansible defaults tovalidate on Python 2.7.9 and higher, which will result in certificatevalidation errors against the Windows self-signed certificates. Unlessverifiable certificates have been configured on the WinRM listeners, thisshould be set to ignore
  • ansible_winrm_operation_timeout_sec: Increase the default timeout forWinRM operations, Ansible uses 20 by default
  • ansible_winrm_read_timeout_sec: Increase the WinRM read timeout, Ansibleuses 30 by default. Useful if there are intermittent network issues andread timeout errors keep occurring
  • ansible_winrm_message_encryption: Specify the message encryptionoperation (auto, always, never) to use, Ansible uses auto bydefault. auto means message encryption is only used whenansible_winrm_scheme is http and ansible_winrm_transport supportsmessage encryption. always means message encryption will always be usedand never means message encryption will never be used
  • ansible_winrm_ca_trust_path: Used to specify a different cacert containerthan the one used in the certifi module. See the HTTPS CertificateValidation section for more details.
  • ansible_winrm_send_cbt: When using ntlm or kerberos over HTTPS,the authentication library will try to send channel binding tokens tomitigate against man in the middle attacks. This flag controls whether thesebindings will be sent or not (default: True).
  • ansiblewinrm: Any additional keyword arguments supported bywinrm.Protocol may be provided in place of

In addition, there are also specific variables that need to be setfor each authentication option. See the section on authentication above for more information.

Note

Ansible 2.0 has deprecated the “ssh” from ansiblessh_user,ansible_ssh_pass, ansible_ssh_host, and ansible_ssh_port tobecome ansible_user, ansible_password, ansible_host, andansible_port. If using a version of Ansible prior to 2.0, the olderstyle (ansible_ssh*) should be used instead. The shorter variablesare ignored, without warning, in older versions of Ansible.

Note

ansible_winrm_message_encryption is different from transportencryption done over TLS. The WinRM payload is still encrypted with TLSwhen run over HTTPS, even if ansible_winrm_message_encryption=never.

IPv6 Addresses

IPv6 addresses can be used instead of IPv4 addresses or hostnames. This optionis normally set in an inventory. Ansible will attempt to parse the addressusing the ipaddresspackage and pass to pywinrm correctly.

When defining a host using an IPv6 address, just add the IPv6 address as youwould an IPv4 address or hostname:

  1. [windows-server]
  2. 2001:db8::1
  3.  
  4. [windows-server:vars]
  5. ansible_user=username
  6. ansible_password=password
  7. ansible_connection=winrm

Note

The ipaddress library is only included by default in Python 3.x. Touse IPv6 addresses in Python 2.7, make sure to run pip install ipaddress which installsa backported package.

HTTPS Certificate Validation

As part of the TLS protocol, the certificate is validated to ensure the hostmatches the subject and the client trusts the issuer of the server certificate.When using a self-signed certificate or settingansible_winrm_server_cert_validation: ignore these security mechanisms arebypassed. While self signed certificates will always need the ignore flag,certificates that have been issued from a certificate authority can still bevalidated.

One of the more common ways of setting up a HTTPS listener in a domainenvironment is to use Active Directory Certificate Service (AD CS). AD CS isused to generate signed certificates from a Certificate Signing Request (CSR).If the WinRM HTTPS listener is using a certificate that has been signed byanother authority, like AD CS, then Ansible can be set up to trust thatissuer as part of the TLS handshake.

To get Ansible to trust a Certificate Authority (CA) like AD CS, the issuercertificate of the CA can be exported as a PEM encoded certificate. Thiscertificate can then be copied locally to the Ansible controller and used as asource of certificate validation, otherwise known as a CA chain.

The CA chain can contain a single or multiple issuer certificates and eachentry is contained on a new line. To then use the custom CA chain as part ofthe validation process, set ansible_winrm_ca_trust_path to the path of thefile. If this variable is not set, the default CA chain is used instead whichis located in the install path of the Python packagecertifi.

Note

Each HTTP call is done by the Python requests library which does notuse the systems built-in certificate store as a trust authority.Certificate validation will fail if the server’s certificate issuer isonly added to the system’s truststore.

Limitations

Due to the design of the WinRM protocol , there are a few limitationswhen using WinRM that can cause issues when creating playbooks for Ansible.These include:

  • Credentials are not delegated for most authentication types, which causesauthentication errors when accessing network resources or installing certainprograms.
  • Many calls to the Windows Update API are blocked when running over WinRM.
  • Some programs fail to install with WinRM due to no credential delegation orbecause they access forbidden Windows API like WUA over WinRM.
  • Commands under WinRM are done under a non-interactive session, which can preventcertain commands or executables from running.
  • You cannot run a process that interacts with DPAPI, which is used by someinstallers (like Microsoft SQL Server).

Some of these limitations can be mitigated by doing one of the following:

  • Set ansible_winrm_transport to credssp or kerberos (withansible_winrm_kerberos_delegation=true) to bypass the double hop issueand access network resources
  • Use become to bypass all WinRM restrictions and run a command as it wouldlocally. Unlike using an authentication transport like credssp, this willalso remove the non-interactive restriction and API restrictions like WUA andDPAPI
  • Use a scheduled task to run a command which can be created with thewin_scheduled_task module. Like become, this bypasses all WinRMrestrictions but can only run a command and not modules.

See also