This document discusses the setup that is required before Ansible can communicate with a Microsoft Windows host.
..contents::
:local:
Host Requirements
`````````````````
For Ansible to communicate to a Windows host and use Windows modules, the
Windows host must meet these requirements:
* Ansible can generally manage Windows versions under current
and extended support from Microsoft. Ansible can manage desktop OSs including
Windows 8.1, and 10, and server OSs including Windows Server 2012, 2012 R2,
2016, 2019, and 2022.
* Ansible requires PowerShell 3.0 or newer and at least .NET 4.0 to be
installed on the Windows host.
* A WinRM listener should be created and activated. More details for this can be
found below.
..Note:: While these are the base requirements for Ansible connectivity, some Ansible
modules have additional requirements, such as a newer OS or PowerShell
version. Please consult the module's documentation page
to determine whether a host meets those requirements.
Upgrading PowerShell and .NET Framework
---------------------------------------
Ansible requires PowerShell version 3.0 and .NET Framework 4.0 or newer to function on older operating systems like Server 2008 and Windows 7. The base image does not meet this
requirement. You can use the `Upgrade-PowerShell.ps1 <https://github.com/jborean93/ansible-windows/blob/master/scripts/Upgrade-PowerShell.ps1>`_ script to update these.
This is an example of how to run this script from PowerShell:
The script works by checking to see what programs need to be installed
(such as .NET Framework 4.5.2) and what PowerShell version is required. If a reboot
is required and the ``username`` and ``password`` parameters are set, the
script will automatically reboot and logon when it comes back up from the
reboot. The script will continue until no more actions are required and the
PowerShell version matches the target version. If the ``username`` and
``password`` parameters are not set, the script will prompt the user to
manually reboot and logon when required. When the user is next logged in, the
script will continue where it left off and the process continues until no more
actions are required.
..Note:: If running on Server 2008, then SP2 must be installed. If running on
Server 2008 R2 or Windows 7, then SP1 must be installed.
..Note:: Windows Server 2008 can only install PowerShell 3.0; specifying a
newer version will result in the script failing.
..Note:: The ``username`` and ``password`` parameters are stored in plain text
in the registry. Make sure the cleanup commands are run after the script finishes
to ensure no credentials are still stored on the host.
WinRM Memory Hotfix
-------------------
When running on PowerShell v3.0, there is a bug with the WinRM service that
limits the amount of memory available to WinRM. Without this hotfix installed,
Ansible will fail to execute certain commands on the Windows host. These
hotfixes should be installed as part of the system bootstrapping or
imaging process. The script `Install-WMF3Hotfix.ps1 <https://github.com/jborean93/ansible-windows/blob/master/scripts/Install-WMF3Hotfix.ps1>`_ can be used to install the hotfix on affected hosts.
The following PowerShell command will install the hotfix:
For more details, please refer to the `Hotfix document <https://support.microsoft.com/en-us/help/2842230/out-of-memory-error-on-a-computer-that-has-a-customized-maxmemorypersh>`_ from Microsoft.
WinRM Setup
```````````
Once Powershell has been upgraded to at least version 3.0, the final step is to
configure the WinRM service so that Ansible can connect to it. There are two
main components of the WinRM service that governs how Ansible can interface with
the Windows host: the ``listener`` and the ``service`` configuration settings.
WinRM Listener
--------------
The WinRM services listens for requests on one or more ports. Each of these ports must have a
listener created and configured.
To view the current listeners that are running on the WinRM service, run the
If this fails, the issue is probably related to the WinRM setup. If it works, the issue may not be related to the WinRM setup; please continue reading for more troubleshooting suggestions.
HTTP 401/Credentials Rejected
+++++++++++++++++++++++++++++
A HTTP 401 error indicates the authentication process failed during the initial
connection. Some things to check for this are:
* Verify that the credentials are correct and set properly in your inventory with
``ansible_user`` and ``ansible_password``
* Ensure that the user is a member of the local Administrators group or has been explicitly
granted access (a connection test with the ``winrs`` command can be used to
rule this out).
* Make sure that the authentication option set by ``ansible_winrm_transport`` is enabled under
``Service\Auth\*``
* If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp``
with ``ansible_winrm_message_encryption: auto`` to enable message encryption.
If using another authentication option or if the installed pywinrm version cannot be
upgraded, the ``Service\AllowUnencrypted`` can be set to ``true`` but this is
only recommended for troubleshooting
* Ensure the downstream packages ``pywinrm``, ``requests-ntlm``,
``requests-kerberos``, and/or ``requests-credssp`` are up to date using ``pip``.
* If using Kerberos authentication, ensure that ``Service\Auth\CbtHardeningLevel`` is
not set to ``Strict``.
* When using Basic or Certificate authentication, make sure that the user is a local account and
not a domain account. Domain accounts do not work with Basic and Certificate
authentication.
HTTP 500 Error
++++++++++++++
These indicate an error has occurred with the WinRM service. Some things
to check for include:
* Verify that the number of current open shells has not exceeded either
``WinRsMaxShellsPerUser`` or any of the other Winrs quotas haven't been
exceeded.
Timeout Errors
+++++++++++++++
These usually indicate an error with the network connection where
Ansible is unable to reach the host. Some things to check for include:
* Make sure the firewall is not set to block the configured WinRM listener ports
* Ensure that a WinRM listener is enabled on the port and path set by the host vars
* Ensure that the ``winrm`` service is running on the Windows host and configured for
automatic start
Connection Refused Errors
+++++++++++++++++++++++++
These usually indicate an error when trying to communicate with the
WinRM service on the host. Some things to check for:
* Ensure that the WinRM service is up and running on the host. Use
``(Get-Service -Name winrm).Status`` to get the status of the service.
* Check that the host firewall is allowing traffic over the WinRM port. By default
this is ``5985`` for HTTP and ``5986`` for HTTPS.
Sometimes an installer may restart the WinRM or HTTP service and cause this error. The
best way to deal with this is to use ``win_psexec`` from another
Windows host.
Failure to Load Builtin Modules
+++++++++++++++++++++++++++++++
If powershell fails with an error message similar to ``The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded.``
then there could be a problem trying to access all the paths specified by the ``PSModulePath`` environment variable.
A common cause of this issue is that the ``PSModulePath`` environment variable contains a UNC path to a file share and
because of the double hop/credential delegation issue the Ansible process cannot access these folders. The way around
this problems is to either:
* Remove the UNC path from the ``PSModulePath`` environment variable, or
* Use an authentication option that supports credential delegation like ``credssp`` or ``kerberos`` with credential delegation enabled
See `KB4076842 <https://support.microsoft.com/en-us/help/4076842>`_ for more information on this problem.
Windows SSH Setup
`````````````````
Ansible 2.8 has added an experimental SSH connection for Windows managed nodes.
..warning::
Use this feature at your own risk!
Using SSH with Windows is experimental, the implementation may make
backwards incompatible changes in feature releases. The server side
components can be unreliable depending on the version that is installed.
Installing OpenSSH using Windows Settings
-----------------------------------------
OpenSSH can be used to connect Window 10 clients to Windows Server 2019.
OpenSSH Client is available to install on Windows 10 build 1809 and later, while OpenSSH Server is available to install on Windows Server 2019 and later.