mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Fix/windows documentation (#17851)
* Updated Windows documentation for more clarity on particular features like NTLM auth.
This commit is contained in:
Jordan Borean
Adrian Likins
parent
60d0e681dd
commit
e357ec68f7
1 changed files with 160 additions and 19 deletions
|
|
@ -33,7 +33,15 @@ Note:: on distributions with multiple python versions, use pip2 or pip2.x, where
|
|||
Active Directory Support
|
||||
++++++++++++++++++++++++
|
||||
|
||||
If you wish to connect to domain accounts published through Active Directory (as opposed to local accounts created on the remote host), you will need to install the "python-kerberos" module on the Ansible control host (and the MIT krb5 libraries it depends on). The Ansible control host also requires a properly configured computer account in Active Directory.
|
||||
Ansible supports both local accounts and domain accounts on Windows, to use domain accounts you can use either of these authentication method;
|
||||
|
||||
- NTLM
|
||||
- Kerberos
|
||||
|
||||
NTLM authentication can be used on versions of pywinrm>=0.2.0 and does not need any special configuration on the Ansible control host. To use NTLM set ``ansible_winrm_transport=ntlm`` in the host_vars.
|
||||
|
||||
To use Kerberos you will need to install the "python-kerberos" module on the Ansible control host (and the MIT krb5 libraries it depends on). The Ansible control host also requires a properly configured computer account in Active Directory.
|
||||
|
||||
|
||||
Installing python-kerberos dependencies
|
||||
---------------------------------------
|
||||
|
|
@ -160,17 +168,65 @@ Ansible's windows support relies on a few standard variables to indicate the use
|
|||
|
||||
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||||
|
||||
In group_vars/windows.yml, define the following inventory variables::
|
||||
Examples
|
||||
++++++++
|
||||
|
||||
# it is suggested that these be encrypted with ansible-vault:
|
||||
# ansible-vault edit group_vars/windows.yml
|
||||
Below are some examples of how to set your inventory based on the auth method chosen. These should all be defined in the group_vars/windows.yml file.
|
||||
|
||||
ansible_user: Administrator
|
||||
ansible_password: SecretPasswordGoesHere
|
||||
ansible_port: 5986
|
||||
ansible_connection: winrm
|
||||
# The following is necessary for Python 2.7.9+ when using default WinRM self-signed certificates:
|
||||
ansible_winrm_server_cert_validation: ignore
|
||||
Basic Auth
|
||||
----------
|
||||
|
||||
Inventory setup for Basic auth::
|
||||
|
||||
ansible_user: USER
|
||||
ansible_password: SecretPasswordGoesHere
|
||||
ansible_port: 5986
|
||||
ansible_connection: winrm
|
||||
|
||||
Certificate Auth
|
||||
----------------
|
||||
|
||||
Inventory setup for Certificate auth::
|
||||
|
||||
ansible_port: 5986
|
||||
ansible_connection: winrm
|
||||
ansible_transport: certificate
|
||||
ansible_winrm_cert_pem: path to the client authentication certificate file path in PEM format
|
||||
ansible_winrm_cert_key_pem: path to the client authentication certificate key file path in PEM format
|
||||
|
||||
|
||||
Kerberos Auth
|
||||
-------------
|
||||
|
||||
Inventory setup for Kerberos auth, note: specifying ansible_password does not make any difference here, you need to have obtained a valid Kerberos ticket outside of Ansible for this to work::
|
||||
|
||||
ansible_user: USER@DOMAIN.COM
|
||||
ansible_port: 5986
|
||||
ansible_connection: winrm
|
||||
|
||||
|
||||
NTLM Auth
|
||||
---------
|
||||
|
||||
Inventory setup for NTLM auth::
|
||||
|
||||
ansible_user: DOMAIN\USER
|
||||
ansible_password: SecretPasswordGoesHere
|
||||
ansible_port: 5986
|
||||
ansible_connection: winrm
|
||||
ansible_transport: ntlm
|
||||
|
||||
Other Options
|
||||
-------------
|
||||
|
||||
There are other inventory options you can set for additional configuration of the WinRM connections::
|
||||
|
||||
* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for the WinRM connection. Ansible uses ``https`` by default unless the 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 Kerberos authentication. If the username contains ``@``, Ansible will use the part of the username after ``@`` by default.
|
||||
* ``ansible_winrm_transport``: Specify one or more transports as a comma-separated list. When older versions of pywinrm <0.2.0, Ansible will use ``kerberos,plaintext`` if the ``kerberos`` module is installed and a realm is defined, otherwise ``plaintext``.
|
||||
* ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to ``validate`` on Python 2.7.9 and higher, which will result in certificate validation errors against the Windows self-signed certificates. Unless verifiable certificates have been configured on the WinRM listeners, this should be set to ``ignore``
|
||||
* ``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be provided.
|
||||
|
||||
Attention for the older style variables (``ansible_ssh_*``): ansible_ssh_password doesn't exist, should be ansible_ssh_pass.
|
||||
|
||||
|
|
@ -191,15 +247,6 @@ a version that is 3 or higher.
|
|||
|
||||
You'll run this command again later though, to make sure everything is working.
|
||||
|
||||
Since 2.0, the following custom inventory variables are also supported for additional configuration of WinRM connections::
|
||||
|
||||
* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for the WinRM connection. Ansible uses ``https`` by default unless the 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 Kerberos authentication. If the username contains ``@``, Ansible will use the part of the username after ``@`` by default.
|
||||
* ``ansible_winrm_transport``: Specify one or more transports as a comma-separated list. By default, Ansible will use ``kerberos,plaintext`` if the ``kerberos`` module is installed and a realm is defined, otherwise ``plaintext``.
|
||||
* ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to ``validate`` on Python 2.7.9 and higher, which will result in certificate validation errors against the Windows self-signed certificates. Unless verifiable certificates have been configured on the WinRM listeners, this should be set to ``ignore``
|
||||
* ``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be provided.
|
||||
|
||||
.. _windows_system_prep:
|
||||
|
||||
Windows System Prep
|
||||
|
|
@ -242,6 +289,100 @@ Looking at an Ansible checkout, copy the `examples/scripts/upgrade_to_ps3.ps1 <h
|
|||
|
||||
.. _what_windows_modules_are_available:
|
||||
|
||||
Verifying Windows Configuration
|
||||
```````````````````````````````
|
||||
|
||||
After you have set up the Windows host you can use the following commands to verify the setup to ensure Ansible can communicate with the host.
|
||||
|
||||
Verify WinRM Listeners
|
||||
++++++++++++++++++++++
|
||||
|
||||
To see what listeners are currently active you can run the following ``winrm`` command in PowerShell::
|
||||
|
||||
#!powershell
|
||||
PS C:\> winrm enumerate winrm/config/listener
|
||||
|
||||
Listener
|
||||
Address = *
|
||||
Transport = HTTP
|
||||
Port = 5985
|
||||
Hostname
|
||||
Enabled = true
|
||||
URLPrefix = wsman
|
||||
CertificateThumbprint
|
||||
ListeningOn = 127.0.0.1, ::1
|
||||
|
||||
Listener
|
||||
Address = *
|
||||
Transport = HTTPS
|
||||
Port = 5986
|
||||
Hostname = WINDOWS-SERVER
|
||||
Enabled = true
|
||||
URLPrefix = wsman
|
||||
CertificateThumbprint = 1234567890ABCDEF111213141516171819101A1B
|
||||
ListeningOn = 127.0.0.1, ::1
|
||||
|
||||
In the above example we can see both a HTTP and HTTPS listener has been created and are listening on ports 5985 and 5986 respectively.
|
||||
|
||||
Verify Service Settings
|
||||
+++++++++++++++++++++++
|
||||
|
||||
Once you have verified that WinRM is setup and listening on a port you can use ``winrm get winrm/config/service`` to get the configuration of the WinRM service::
|
||||
|
||||
#!powershell
|
||||
PS C:\> winrm get winrm/config/service
|
||||
|
||||
Service
|
||||
RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD)
|
||||
MaxConcurrentOperations = 4294967295
|
||||
MaxConcurrentOperationsPerUser = 1500
|
||||
EnumerationTimeoutms = 240000
|
||||
MaxConnections = 300
|
||||
MaxPacketRetrievalTimeSeconds = 120
|
||||
AllowUnencrypted = false
|
||||
Auth
|
||||
Basic = true
|
||||
Kerberos = true
|
||||
Negotiate = true
|
||||
Certificate = false
|
||||
CredSSP = false
|
||||
CbtHardeningLevel = Relaxed
|
||||
DefaultPorts
|
||||
HTTP = 5985
|
||||
HTTPS = 5986
|
||||
IPv4Filter = *
|
||||
IPv6Filter = *
|
||||
EnableCompatibilityHttpListener = false
|
||||
EnableCompatibilityHttpsListener = false
|
||||
CertificateThumbprint
|
||||
AllowRemoteAccess = true
|
||||
|
||||
In the above example we are able to authenticate with the Windows host using:
|
||||
|
||||
- Basic (local accounts only)
|
||||
- Kerberos (domain accounts only)
|
||||
- Negotiate [Kerberos/NTLM] (local and domain accounts)
|
||||
|
||||
Because AllowUnencrypted is set to false we also have to use a HTTPS listener as pywinrm does not currently support encrypted WinRM messages over HTTP.
|
||||
|
||||
The following section defines the purpose of each relevant value::
|
||||
|
||||
* ``AllowUnencrypted``: When set to ``true`` allows WinRM messages to be sent without encryption.
|
||||
* ``Auth/Basic``: Allows basic authentication, only for local accounts
|
||||
* ``Auth/Kerberos``: Allows Kerberos authentication, only for domain accounts
|
||||
* ``Auth/Negotiate``: Leverages Windows SSPI for auth, used by NTLM and Kerberos
|
||||
* ``Auth/Certificate``: Allows certificate authentication, only for local accounts
|
||||
* ``Auth/CredSSP``: Allows CredSSP authentication for credential delegation (double-hop). Not currently supported by pywinrm
|
||||
* ``Auth/CbtHardeningLevel``: Channel Binding Token is either mandatory (``Strict``) or optional (``Relaxed``, ``None``). ``Strict`` not currently supported by pywinrm
|
||||
|
||||
.. note::
|
||||
It is highly recommended to not set AllowUnencrypted to true, please
|
||||
use HTTPS endpoints wherever possible.
|
||||
|
||||
Double-hop authentication is currently supported by pywinrm with
|
||||
the Kerberos auth method. Please set ``ansible_winrm_kerberos_delegation=true``
|
||||
in host vars for this.
|
||||
|
||||
What modules are available
|
||||
``````````````````````````
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue