@ -33,7 +33,15 @@ Note:: on distributions with multiple python versions, use pip2 or pip2.x, where
Active Directory Support
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
Installing python-kerberos dependencies
---------------------------------------
---------------------------------------
@ -160,17 +168,65 @@ Ansible's windows support relies on a few standard variables to indicate the use
In group_vars/windows.yml, define the following inventory variables::
Examples
++++++++
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.
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::
# it is suggested that these be encrypted with ansible-vault:
ansible_user: DOMAIN\USER
# ansible-vault edit group_vars/windows.yml
ansible_password: SecretPasswordGoesHere
ansible_port: 5986
ansible_connection: winrm
ansible_transport: ntlm
ansible_user: Administrator
Other Options
ansible_password: SecretPasswordGoesHere
-------------
ansible_port: 5986
ansible_connection: winrm
There are other inventory options you can set for additional configuration of the WinRM connections::
# The following is necessary for Python 2.7.9+ when using default WinRM self-signed certificates:
ansible_winrm_server_cert_validation: ignore
* ``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.
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.
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:
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:
.._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::
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::
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``
Jordan Borean
8 years ago
committed by