* add ansible 7 porting guide to index page (#79254)
(cherry picked from commit 44f7ca4645)
* communication.rst: add Ansible MySQL WG information (#79269)
(cherry picked from commit 1c80209422)
* #59449: Removes translatable words from code blocks (#79193)
Co-authored-by: Jaroslav Klech <jklech@redhat.com>
(cherry picked from commit 65e725f08f)
* Add more documentation for InventoryData methods (#79288)
* Add more documentation for InventoryData methods
Reword some constructed documention and mention fetch_hostvars
* describe use cases for default strict behavior
Co-Authored-By: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
(cherry picked from commit a12a9b409f)
* blockinfile - document multiline marker behavior (#79292)
(cherry picked from commit f700047e69)
Co-authored-by: Andrew Klychkov <aklychko@redhat.com>
Co-authored-by: JaroslavKlech <klechh@gmail.com>
Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
@ -118,6 +118,7 @@ Many of our community `Working Groups <https://github.com/ansible/community/wiki
- `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.com <https://matrix.to:/#/#kubernetes:ansible.com>`_ | IRC: ``#ansible-kubernetes``
- `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.com <https://matrix.to:/#/#linode:ansible.com>`_ | IRC: ``#ansible-linode``
- `Molecule Working Group <https://github.com/ansible/community/wiki/Molecule>`_ (`testing platform for Ansible playbooks and roles <https://molecule.readthedocs.io>`_) - Matrix: `#molecule:ansible.im <https://matrix.to:/#/#molecule:ansible.im>`_ | IRC: ``#ansible-molecule``
- `MySQL Working Group <https://github.com/ansible-collections/community.mysql/wiki/MySQL-Working-Group>`_ - Matrix: `#mysql:ansible.com <https://matrix.to:/#/#mysql:ansible.com>`_
- `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.com <https://matrix.to:/#/#network:ansible.com>`_ | IRC: ``#ansible-network``
- `PostgreSQL Working Group <https://github.com/ansible-collections/community.postgresql/wiki/PostgreSQL-Working-Group>`_ - Matrix: `#postgresql:ansible.com <https://matrix.to:/#/#postgresql:ansible.com>`_
- `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel``
The ``inventory`` object passed to ``parse`` has helpful methods for populating inventory.
``add_group`` adds a group to inventory if it doesn't already exist. It takes the group name as the only positional argument.
``add_child`` adds a group or host that exists in inventory to a parent group in inventory. It takes two positional arguments, the name of the parent group and the name of the child group or host.
``add_host`` adds a host to inventory if it doesn't already exist, optionally to a specific group. It takes the host name as the first argument and accepts two optional keyword arguments, ``group`` and ``port``. ``group`` is the name of a group in inventory, and ``port`` is an integer.
``set_variable`` adds a variable to a group or host in inventory. It takes three positional arguments: the name of the group or host, the name of the variable, and the value of the variable.
To create groups and variables using Jinja2 expressions, see the section on implementing ``constructed`` features below.
To see other inventory object methods, see the source code here:
@ -286,7 +306,19 @@ Inventory plugins can create host variables and groups from Jinja2 expressions a
NAME = 'ns.coll.myplugin'
The three main options from the ``constructed`` documentation fragment are ``compose``, ``keyed_groups``, and ``groups``. See the ``constructed`` inventory plugin for examples on using these. ``compose`` is a dictionary of variable names and Jinja2 expressions. Once a host is added to inventory and any initial variables have been set, call the method ``_set_composite_vars`` to add composed host variables. If this is done before adding ``keyed_groups`` and ``groups``, the group generation will be able to use the composed variables.
There are three main options in the ``constructed`` documentation fragment:
``compose`` creates variables using Jinja2 expressions. This is implemented by calling the ``_set_composite_vars`` method.
``keyed_groups`` creates groups of hosts based on variable values. This is implemented by calling the ``_add_host_to_keyed_groups`` method.
``groups`` creates groups based on Jinja2 conditionals. This is implemented by calling the ``_add_host_to_composed_groups`` method.
Each method should be called for every host added to inventory. Three positional arguments are required: the constructed option, a dictionary of variables, and a host name. Calling the method ``_set_composite_vars`` first will allow ``keyed_groups`` and ``groups`` to use the composed variables.
By default, undefined variables are ignored. This is permitted by default for ``compose`` so you can make the variable definitions depend on variables that will be populated later in a play from other sources. For groups, it allows using variables that are not always present without having to use the ``default`` filter. To support configuring undefined variables to be an error, pass the constructed option ``strict`` to each of the methods as a keyword argument.
``keyed_groups`` and ``groups`` use any variables already associated with the host (for example, from an earlier inventory source). ``_add_host_to_keyed_groups`` and ``add_host_to_composed_groups`` can turn this off by passing the keyword argument ``fetch_hostvars``.
Here is an example using all three methods:
..code-block:: python
@ -296,14 +328,12 @@ The three main options from the ``constructed`` documentation fragment are ``com
@ -10,23 +10,15 @@ This document discusses the setup that is required before Ansible can communicat
Host Requirements
`````````````````
For Ansible to communicate to a Windows host and use Windows modules, the
Windows host must meet these requirements:
Windows host must meet these base requirements for connectivity:
* 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.
* With Ansible you can generally manage Windows versions under the current and extended support from Microsoft. You can also 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.
* You need to install PowerShell 3.0 or newer and at least .NET 4.0 on the Windows host.
* A WinRM listener should be created and activated. More details for this can be
found below.
* You need to create and activate a WinRM listener. More details, see `WinRM Setup <https://docs.ansible.com/ansible/latest//user_guide/windows_setup.html#winrm-listener>`_.
..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.
..Note:: Some Ansible modules have additional requirements, such as a newer OS or PowerShell version. Consult the module documentation page to determine whether a host meets those requirements.
Upgrading PowerShell and .NET Framework
---------------------------------------
@ -46,53 +38,44 @@ 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
The script determines what programs you need to install (such as .NET Framework 4.5.2) and what PowerShell version needs to be present. If a reboot is needed and the ``username`` and ``password`` parameters are set, the script will automatically reboot the machine and then logon. 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:: If you run the script on Server 2008, then you need to install SP2. For Server 2008 R2 or Windows 7 you need SP1.
On Windows Server 2008 you can install only PowerShell 3.0. A newer version will result in the script failure.
..Note:: Windows Server 2008 can only install PowerShell 3.0; specifying a
newer version will result in the script failing.
The ``username`` and ``password`` parameters are stored in plain text in the registry. Run the cleanup commands after the script finishes to ensure no credentials are stored on the host.
..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.
On PowerShell v3.0, there is a bug that limits the amount of memory available to the WinRM service. Use the `Install-WMF3Hotfix.ps1 <https://github.com/jborean93/ansible-windows/blob/master/scripts/Install-WMF3Hotfix.ps1>`_ script to install a hotfix on affected hosts as part of the system bootstrapping or imaging process. Without this hotfix, Ansible fails to execute certain commands on the Windows host.
The following PowerShell command will install the hotfix:
To install the hotfix:
..code-block:: powershell
@ -103,22 +86,17 @@ 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.
For more details, refer to the `"Out of memory" error on a computer that has a customized MaxMemoryPerShellMB quota set and has WMF 3.0 installed<https://support.microsoft.com/en-us/help/2842230/out-of-memory-error-on-a-computer-that-has-a-customized-maxmemorypersh>`_article.
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.
You need 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.
The WinRM services listen 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
following command:
To view the current listeners that are running on the WinRM service:
..code-block:: powershell
@ -150,26 +128,15 @@ This will output something like:
In the example above there are two listeners activated; one is listening on
port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of
the key options that are useful to understand are:
In the example above there are two listeners activated. One is listening on port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of the key options that are useful to understand are:
* ``Transport``: Whether the listener is run over HTTP or HTTPS, it is
recommended to use a listener over HTTPS as the data is encrypted without
any further changes required.
* ``Transport``: Whether the listener is run over HTTP or HTTPS. We recommend you use a listener over HTTPS because the data is encrypted without any further changes required.
* ``Port``: The port the listener runs on, by default it is ``5985`` for HTTP
and ``5986`` for HTTPS. This port can be changed to whatever is required and
corresponds to the host var ``ansible_port``.
* ``Port``: The port the listener runs on. By default it is ``5985`` for HTTP and ``5986`` for HTTPS. This port can be changed to whatever is required and corresponds to the host var ``ansible_port``.
* ``URLPrefix``: The URL prefix to listen on, by default it is ``wsman``. If
this is changed, the host var ``ansible_winrm_path`` must be set to the same
value.
* ``URLPrefix``: The URL prefix to listen on. By default it is ``wsman``. If you change this option, you need to set the host var ``ansible_winrm_path`` to the same value.
* ``CertificateThumbprint``: If running over an HTTPS listener, this is the
thumbprint of the certificate in the Windows Certificate Store that is used
in the connection. To get the details of the certificate itself, run this
command with the relevant certificate thumbprint in PowerShell:
* ``CertificateThumbprint``: If you use an HTTPS listener, this is the thumbprint of the certificate in the Windows Certificate Store that is used in the connection. To get the details of the certificate itself, run this command with the relevant certificate thumbprint in PowerShell:
..code-block:: powershell
@ -180,19 +147,11 @@ Setup WinRM Listener
++++++++++++++++++++
There are three ways to set up a WinRM listener:
* Using ``winrm quickconfig`` for HTTP or
``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option
to use when running outside of a domain environment and a simple listener is
required. Unlike the other options, this process also has the added benefit of
opening up the Firewall for the ports required and starts the WinRM service.
* Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option to use when running outside of a domain environment and a simple listener is required. Unlike the other options, this process also has the added benefit of opening up the firewall for the ports required and starts the WinRM service.
* Using Group Policy Objects. This is the best way to create a listener when the
host is a member of a domain because the configuration is done automatically
without any user input. For more information on group policy objects, see the
* Using Group Policy Objects (GPO). This is the best way to create a listener when the host is a member of a domain because the configuration is done automatically without any user input. For more information on group policy objects, see the `Group Policy Objects documentation <https://msdn.microsoft.com/en-us/library/aa374162(v=vs.85).aspx>`_.
* Using PowerShell to create the listener with a specific configuration. This
can be done by running the following PowerShell commands:
* Using PowerShell to create a listener with a specific configuration. This can be done by running the following PowerShell commands:
..code-block:: powershell
@ -206,36 +165,32 @@ There are three ways to set up a WinRM listener:
..Note:: The ``Keys`` object is an array of strings, so it can contain different
values. By default it contains a key for ``Transport=`` and ``Address=``
which correspond to the values from winrm enumerate winrm/config/Listeners.
..Note:: The ``Keys`` object is an array of strings, so it can contain different values. By default, it contains a key for ``Transport=`` and ``Address=`` which correspond to the values from the ``winrm enumerate winrm/config/Listeners`` command.
WinRM Service Options
---------------------
There are a number of options that can be set to control the behavior of the WinRM service component,
including authentication options and memory settings.
You can control the behavior of the WinRM service component, including authentication options and memory settings.
To get an output of the current service configuration options, run the
following command:
To get an output of the current service configuration options, run the following command:
..code-block:: powershell
@ -280,79 +235,71 @@ This will output something like:
MaxMemoryPerShellMB = 2147483647
MaxShellsPerUser = 2147483647
While many of these options should rarely be changed, a few can easily impact
the operations over WinRM and are useful to understand. Some of the important
options are:
You do not need to change the majority of these options. However, some of the important ones to know about are:
* ``Service\AllowUnencrypted``: This option defines whether WinRM will allow
traffic that is run over HTTP without message encryption. Message level
encryption is only possible when ``ansible_winrm_transport`` is ``ntlm``,
``kerberos`` or ``credssp``. By default this is ``false`` and should only be
set to ``true`` when debugging WinRM messages.
* ``Service\AllowUnencrypted`` - specifies whether WinRM will allow HTTP traffic without message encryption. Message level encryption is only possible when the ``ansible_winrm_transport`` variable is ``ntlm``, ``kerberos`` or ``credssp``. By default, this is ``false`` and you should only set it to ``true`` when debugging WinRM messages.
* ``Service\Auth\*``: These flags define what authentication
options are allowed with the WinRM service. By default, ``Negotiate (NTLM)``
and ``Kerberos`` are enabled.
* ``Service\Auth\*`` - defines what authentication options you can use with the WinRM service. By default, ``Negotiate (NTLM)`` and ``Kerberos`` are enabled.
* ``Service\Auth\CbtHardeningLevel``: Specifies whether channel binding tokens are
not verified (None), verified but not required (Relaxed), or verified and
required (Strict). CBT is only used when connecting with NTLM or Kerberos
over HTTPS.
* ``Service\Auth\CbtHardeningLevel`` - specifies whether channel binding tokens are not verified (None), verified but not required (Relaxed), or verified and required (Strict). CBT is only used when connecting with NT LAN Manager (NTLM) or Kerberos over HTTPS.
* ``Service\CertificateThumbprint``: This is the thumbprint of the certificate
used to encrypt the TLS channel used with CredSSP authentication. By default
this is empty; a self-signed certificate is generated when the WinRM service
starts and is used in the TLS process.
* ``Service\CertificateThumbprint`` - thumbprint of the certificate for encrypting the TLS channel used with CredSSP authentication. By default, this is empty. A self-signed certificate is generated when the WinRM service starts and is used in the TLS process.
* ``Winrs\MaxShellRunTime``: This is the maximum time, in milliseconds, that a
remote command is allowed to execute.
* ``Winrs\MaxShellRunTime`` - maximum time, in milliseconds, that a remote command is allowed to execute.
* ``Winrs\MaxMemoryPerShellMB``: This is the maximum amount of memory allocated
per shell, including the shell's child processes.
* ``Winrs\MaxMemoryPerShellMB`` - maximum amount of memory allocated per shell, including its child processes.
To modify a setting under the ``Service`` key in PowerShell:
To modify a setting under the ``Service`` key in PowerShell, you need to provide a path to the option after ``winrm/config/Service``:
..code-block:: powershell
# substitute {path} with the path to the option after winrm/config/Service
..Note:: If running in a domain environment, some of these options are set by
GPO and cannot be changed on the host itself. When a key has been
configured with GPO, it contains the text ``[Source="GPO"]`` next to the value.
..Note:: If you run the command in a domain environment, some of these options are set by
GPO and cannot be changed on the host itself. When you configured a key with GPO, it contains the text ``[Source="GPO"]`` next to the value.
Common WinRM Issues
-------------------
Because WinRM has a wide range of configuration options, it can be difficult
to setup and configure. Because of this complexity, issues that are shown by Ansible
could in fact be issues with the host setup instead.
WinRM has a wide range of configuration options, which makes its configuration complex. As a result, errors that Ansible displays could in fact be problems with the host setup instead.
One easy way to determine whether a problem is a host issue is to
run the following command from another Windows host to connect to the
target Windows host:
To identify a host issue, run the following command from another Windows host to connect to the target Windows host.
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.
If any of the above commands fail, the issue is probably related to the WinRM setup.
HTTP 401/Credentials Rejected
+++++++++++++++++++++++++++++
A HTTP 401 error indicates the authentication process failed during the initial
connection. Some things to check for this are:
An HTTP 401 error indicates the authentication process failed during the initial
connection. You can check the following to troubleshoot:
* Verify that the credentials are correct and set properly in your inventory with
``ansible_user`` and ``ansible_password``
* The credentials are correct and set properly in your inventory with the ``ansible_user`` and ``ansible_password`` variables.
* 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).
* The user is a member of the local Administrators group, or has been explicitly granted access. You can perform a connection test with the ``winrs`` command to rule this out.
* Make sure that the authentication option set by ``ansible_winrm_transport`` is enabled under
``Service\Auth\*``
* The authentication option set by the ``ansible_winrm_transport`` variable 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
* If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp`` with the ``ansible_winrm_message_encryption: auto`` custom inventory variable to enable message encryption. If you use another authentication option, or if it is not possible to upgrade the installed ``pywinrm`` package, you can set ``Service\AllowUnencrypted`` to ``true``. This is recommended only for troubleshooting.
* Ensure the downstream packages ``pywinrm``, ``requests-ntlm``,
``requests-kerberos``, and/or ``requests-credssp`` are up to date using ``pip``.
* 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``.
* For 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.
* For Basic or Certificate authentication, make sure that the user is a local 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:
An HTTP 500 error indicates a problem with the WinRM service. You can check the following to troubleshoot:
* Verify that the number of current open shells has not exceeded either
``WinRsMaxShellsPerUser`` or any of the other Winrs quotas haven't been
exceeded.
* The number of your currently open shells has not exceeded either ``WinRsMaxShellsPerUser``. Alternatively, you did not exceed any of the other Winrs quotas.
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:
Sometimes Ansible is unable to reach the host. These instances usually indicate a problem with the network connection. You can check the following to troubleshoot:
* 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
* The firewall is not set to block the configured WinRM listener ports.
* A WinRM listener is enabled on the port and path set by the host vars.
* The ``winrm`` service is running on the Windows host and is configured for the 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:
When you communicate with the WinRM service on the host you can encounter some problems. Check the following to help the troubleshooting:
* 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.
* The WinRM service is up and running on the host. Use the ``(Get-Service -Name winrm).Status`` command to get the status of the service.
* 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.
Sometimes an installer may restart the WinRM or HTTP service and cause this error. The best way to deal with this is to use the ``win_psexec`` module 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:
Sometimes PowerShell fails with an error message similar to:
..code-block:: powershell
The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded.
In that case, there could be a problem when trying to access all the paths specified by the ``PSModulePath`` environment variable.
A common cause of this issue is that ``PSModulePath`` contains a Universal Naming Convention (UNC) path to a file share. Additionally, the double hop/credential delegation issue causes that the Ansible process cannot access these folders. To work around this problem is to either:
* Remove the UNC path from ``PSModulePath``.
or
* 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
* Use an authentication option that supports credential delegation like ``credssp`` or ``kerberos``. You need to have the credential delegation enabled.
See `KB4076842 <https://support.microsoft.com/en-us/help/4076842>`_ for more information on this problem.
@ -444,36 +376,29 @@ 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.
Use this feature at your own risk! Using SSH with Windows is experimental. This implementation may make
backwards incompatible changes in future releases. The server-side components can be unreliable depending on your installed version.
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.
You can use OpenSSH to connect Window 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later.
For more information, refer to `Get started with OpenSSH for Windows<https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse>`_.
Installing Win32-OpenSSH
------------------------
The first step to using SSH with Windows is to install the `Win32-OpenSSH <https://github.com/PowerShell/Win32-OpenSSH>`_
service on the Windows host. Microsoft offers a way to install ``Win32-OpenSSH`` through a Windows
capability but currently the version that is installed through this process is
too old to work with Ansible. To install ``Win32-OpenSSH`` for use with
To install the `Win32-OpenSSH <https://github.com/PowerShell/Win32-OpenSSH>`_ service for use with
Ansible, select one of these installation options:
* Manually install the service, following the `install instructions <https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH>`_
from Microsoft.
* Manually install ``Win32-OpenSSH``, following the `install instructions <https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH>`_ from Microsoft.
* Install the `openssh <https://chocolatey.org/packages/openssh>`_ package using Chocolatey:
@ -483,16 +408,16 @@ Ansible, select one of these installation options:
package_params: /SSHServerFeature
state: present
* Use an existing Ansible Galaxy role like `jborean93.win_openssh <https://galaxy.ansible.com/jborean93/win_openssh>`_:
* Install an Ansible Galaxy role for example `jborean93.win_openssh <https://galaxy.ansible.com/jborean93/win_openssh>`_:
..code-block:: powershell
# Make sure the role has been downloaded first
ansible-galaxy install jborean93.win_openssh
* Use the role in your playbook:
..code-block:: yaml
# main.yml
- name: install Win32-OpenSSH service
hosts: windows
gather_facts: false
@ -500,16 +425,14 @@ Ansible, select one of these installation options:
- role: jborean93.win_openssh
opt_openssh_setup_service: True
..note::``Win32-OpenSSH`` is still a beta product and is constantly
being updated to include new features and bugfixes. If you are using SSH as
a connection option for Windows, it is highly recommend you install the
latest release from one of the 3 methods above.
..note::``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new features and bugfixes. If you use SSH as a connection option for Windows, we highly recommend you install the latest version.
Configuring the Win32-OpenSSH shell
-----------------------------------
By default ``Win32-OpenSSH`` will use ``cmd.exe`` as a shell. To configure a
different shell, use an Ansible task to define the registry setting:
By default ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell.
* To configure a different shell, use an Ansible playbook with a task to define the registry setting:
..code-block:: yaml
@ -521,7 +444,10 @@ different shell, use an Ansible task to define the registry setting:
type: string
state: present
# Or revert the settings back to the default, cmd
* To revert the settings back to the default shell:
..code-block:: yaml
- name: set the default shell to cmd
win_regedit:
path: HKLM:\SOFTWARE\OpenSSH
@ -530,20 +456,18 @@ different shell, use an Ansible task to define the registry setting:
Win32-OpenSSH Authentication
----------------------------
Win32-OpenSSH authentication with Windows is similar to SSH
authentication on Unix/Linux hosts. You can use a plaintext password or
SSH public key authentication, add public keys to an ``authorized_key`` file
in the ``.ssh`` folder of the user's profile directory, and configure the
service using the ``sshd_config`` file used by the SSH service as you would on
a Unix/Linux host.
Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hosts. You can use a plaintext password or SSH public key authentication.
For the key-based authentication:
* Add your public keys to an ``authorized_key`` file in the ``.ssh`` folder of the user's profile directory.
* Configure the SSH service using the ``sshd_config`` file.
When using SSH key authentication with Ansible, the remote session won't have access to the
user's credentials and will fail when attempting to access a network resource.
This is also known as the double-hop or credential delegation issue. There are
two ways to work around this issue:
When using SSH key authentication with Ansible, the remote session will not have access to user credentials and will fail when attempting to access a network resource. This is also known as the double-hop or credential delegation issue. To work around this problem:
* Use plaintext password auth by setting ``ansible_password``
* Use ``become`` on the task with the credentials of the user that needs access to the remote resource
* Use plaintext password authentication by setting the ``ansible_password`` variable.
* Use the ``become`` directive on the task with the credentials of the user that needs access to the remote resource.
Configuring Ansible for SSH on Windows
--------------------------------------
@ -552,17 +476,14 @@ To configure Ansible to use SSH for Windows hosts, you must set two connection v
* set ``ansible_connection`` to ``ssh``
* set ``ansible_shell_type`` to ``cmd`` or ``powershell``
The ``ansible_shell_type`` variable should reflect the ``DefaultShell``
configured on the Windows host. Set to ``cmd`` for the default shell or set to
``powershell`` if the ``DefaultShell`` has been changed to PowerShell.
The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configured on the Windows host. Set ``ansible_shell_type`` to ``cmd`` for the default shell. Alternatively, set ``ansible_shell_type`` to ``powershell`` if you changed ``DefaultShell`` to PowerShell.
Known issues with SSH on Windows
--------------------------------
Using SSH with Windows is experimental, and we expect to uncover more issues.
Here are the known ones:
Using SSH with Windows is experimental. Currently existing issues are:
* Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type
* While SCP should work, SFTP is the recommended SSH file transfer mechanism to use when copying or fetching a file
* Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type.
* While Secure Copy Protocol (SCP) should work, SSH File Transfer Protocol (SFTP) is the recommended mechanism to use when copying or fetching a file.
To make an escaped string that will work on all versions you have two options::
@ -48,7 +58,11 @@ uses key=value escaping which has not changed. The other option is to check for
relied on the trailing newline being stripped, you can change your playbook
using the following as an example::
# Syntax in 1.9.x
* Syntax in 1.9.x
..code-block:: yaml
vars:
message: >
Testing
@ -57,7 +71,11 @@ uses key=value escaping which has not changed. The other option is to check for
- debug:
msg: "{{ message }}"
# Syntax in 2.0.x
* Syntax in 2.0.x
..code-block:: yaml
vars:
old_message: >
Testing
@ -65,7 +83,12 @@ uses key=value escaping which has not changed. The other option is to check for
message: "{{ old_message[:-1] }}"
- debug:
msg: "{{ message }}"
# Output
* Output
..code-block:: yaml
"msg": "Testing some things"
* Behavior of templating DOS-type text files changes with Ansible v2.
@ -75,7 +98,9 @@ uses key=value escaping which has not changed. The other option is to check for
* When specifying complex args as a variable, the variable must use the full jinja2
variable syntax (```{{var_name}}```) - bare variable names there are no longer accepted.
In fact, even specifying args with variables has been deprecated, and will not be
allowed in future versions::
allowed in future versions:
..code-block:: yaml
---
- hosts: localhost
@ -87,7 +112,7 @@ uses key=value escaping which has not changed. The other option is to check for
- { path: /tmp/3b, state: directory, mode: 0700 }
tasks:
- file:
args: "{{item}}" # <- args here uses the full variable syntax
args: "{{item}}"
with_items: "{{my_dirs}}"
* porting task includes
@ -111,7 +136,9 @@ While all items listed here will show a deprecation warning message, they still
* Bare variables in ``with_`` loops should instead use the ``"{{ var }}"`` syntax, which helps eliminate ambiguity.
* The ansible-galaxy text format requirements file. Users should use the YAML format for requirements instead.
* Undefined variables within a ``with_`` loop's list currently do not interrupt the loop, but they do issue a warning; in the future, they will issue an error.
* Using dictionary variables to set all task parameters is unsafe and will be removed in a future version. For example::
* Using dictionary variables to set all task parameters is unsafe and will be removed in a future version. Example of a deprecated variant:
..code-block:: yaml
- hosts: localhost
gather_facts: no
@ -119,14 +146,22 @@ While all items listed here will show a deprecation warning message, they still
debug_params:
msg: "hello there"
tasks:
# These are both deprecated:
- debug: "{{debug_params}}"
- debug:
args: "{{debug_params}}"
# Use this instead:
Example of a recommended variant:
..code-block:: yaml
- hosts: localhost
gather_facts: no
vars:
debug_params:
msg: "hello there"
tasks:
- debug:
msg: "{{debug_params['msg']}}"
msg: "{{debug_params['msg']}}"
* Host patterns should use a comma (,) or colon (:) instead of a semicolon (;) to separate hosts/groups in the pattern.
* Ranges specified in host patterns should use the [x:y] syntax, instead of [x-y].
Sandra McCann
2 years ago
committed by