ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

windows: Add IPv6 address support and docs to go with it (#34072)

Browse source 
* windows: Add IPv6 address support and docs to go with it

* minor docs fix

* fixed some doc sentances
This commit is contained in:
Jordan Borean 2018-01-04 03:26:53 +10:00 committed by Matt Davis
parent 603d6122a3
commit 57ed6a866f
2 changed files with 55 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
docs/docsite/rst/windows_winrm.rst
View file

@ -25,7 +25,7 @@ with the Ansible package, but can be installed by running the following::
Authentication Options
``````````````````````
When connecting to a Windows host, there are several different options that can be used
when authentication with an account. The authentication type may be set on inventory
when authenticating with an account. The authentication type may be set on inventory
hosts or groups with the ``ansible_winrm_transport`` variable.
The following matrix is a high level overview of the options:
@ -97,7 +97,7 @@ This can be done using one of the following methods:
* Active Directory Certificate Services
Active Directory Certificate Services is beyond of scope in this documentation but may be
the best option to use when running in a domain environment. For more information,
the best option to use when running in a domain environment. For more information,
see the `Active Directory Certificate Services documentation <https://technet.microsoft.com/en-us/library/cc732625(v=ws.11).aspx>`_.
.. Note:: Using the PowerShell cmdlet ``New-SelfSignedCertificate`` to generate
@ -142,7 +142,7 @@ To generate a certificate with ``New-SelfSignedCertificate``:
-KeyUsage DigitalSignature,KeyEncipherment `
-KeyAlgorithm RSA `
-KeyLength 2048
# export the public key
$pem_output = @()
$pem_output += "-----BEGIN CERTIFICATE-----"
@ -236,7 +236,7 @@ service, so no setup is required before using it.
NTLM is the easiest authentication protocol to use and is more secure than
``Basic`` authentication. If running in a domain environment, ``Kerberos`` should be used
instead of NTLM.
instead of NTLM.
Kerberos has several advantages over using NTLM:
@ -271,7 +271,7 @@ The following example shows host vars configured for Kerberos authentication::
ansible_winrm_transport: kerberos
As of Ansible version 2.3, the Kerberos ticket will be created based on
``ansible_user`` and ``ansible_password``. If running on an older version of
``ansible_user`` and ``ansible_password``. If running on an older version of
Ansible or when ``ansible_winrm_kinit_mode`` is ``manual``, a Kerberos
ticket must already be obtained. See below for more details.
@ -471,7 +471,7 @@ CredSSP and TLS 1.2
+++++++++++++++++++
By default the ``requests-credssp`` library is configured to authenticate over
the TLS 1.2 protocol. TLS 1.2 is installed and enabled by default for Windows Server 2012
and Windows 8 and more recent releases.
and Windows 8 and more recent releases.
There are two ways that older hosts can be used with CredSSP:
@ -479,12 +479,12 @@ There are two ways that older hosts can be used with CredSSP:
for Server 2008 R2 and Windows 7).
* Set ``ansible_winrm_credssp_disable_tlsv1_2=True`` in the inventory to run
over TLS 1.0. This is the only option when connecting to Windows Server 2008, which
over TLS 1.0. This is the only option when connecting to Windows Server 2008, which
has no way of supporting TLS 1.2
To enable TLS 1.2 support on Server 2008 R2 and Windows 7, the optional update
`KRB3080079 <https://support.microsoft.com/en-us/help/3080079/update-to-add-rds-support-for-tls-1.1-and-tls-1.2-in-windows-7-or-windows-server-2008-r2>`_
needs to be installed.
needs to be installed.
Once the update has been applied and the Windows host rebooted, run the following
PowerShell commands to enable TLS 1.2:
@ -507,7 +507,7 @@ CredSSP works by encrypting the credentials through the TLS protocol and uses a
another certificate.
.. Note:: This certificate configuration is independent of the WinRM listener
certificate. With CredSSP, message transport still occurs over the WinRM listener,
certificate. 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:
@ -531,7 +531,7 @@ WinRM is configured by default to only allow connections from accounts in the lo
winrm configSDDL default
This will display an ACL editor, where new users or groups may be added. To run commands
over WinRM, users and groups must have at least the ``Read`` and ``Execute`` permissions
over WinRM, users and groups must have at least the ``Read`` and ``Execute`` permissions
enabled.
While non-administrative accounts can be used with WinRM, most typical server administration
@ -581,12 +581,11 @@ When setting up the inventory, the following variables are required::
# it is suggested that these be encrypted with ansible-vault:
# ansible-vault edit group_vars/windows.yml
ansible_connection: winrm
# may also be passed on the command-line via --user
ansible_user: Administrator
# may also be supplied at runtime with --ask-pass
ansible_password: SecretPasswordGoesHere
@ -657,6 +656,29 @@ for each authentication option. See the section on authentication above for more
encryption done over TLS. The WinRM payload is still encrypted with TLS
when run over HTTPS, even if ``ansible_winrm_message_encryption=never``.
IPv6 Addresses
``````````````
IPv6 addresses can be used instead of IPv4 addresses or hostnames. This option
is normally set in an inventory. Ansible will attempt to parse the address
using the `ipaddress <https://docs.python.org/3/library/ipaddress.html>`_
package and pass to pywinrm correctly.
When defining a host using an IPv6 address, just add the IPv6 address as you
would an IPv4 address or hostname::
[windows-server]
2001:db8::1
[windows-server:vars]
ansible_user=username
ansible_password=password
ansible_connection=winrm
.. Note:: The ipaddress library is only included by default in Python 3.x. To
use IPv6 addresses in Python 2.6 and 2.7, make sure to run
``pip install ipaddress`` which installs a backported package.
Limitations
```````````
Due to the design of the WinRM protocol , there are a few limitations
@ -675,9 +697,9 @@ These include:
* Commands under WinRM are done under a non-interactive session, which can prevent
certain commands or executables from running.
* You cannot run a process that interacts with ``DPAPI``, which is used by some
* You cannot run a process that interacts with ``DPAPI``, which is used by some
installers (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`` (with

20
lib/ansible/plugins/connection/winrm.py
View file

@ -144,6 +144,13 @@ try:
except ImportError as e:
HAS_PEXPECT = False
# used to try and parse the hostname and detect if IPv6 is being used
try:
import ipaddress
HAS_IPADDRESS = True
except ImportError:
HAS_IPADRESS = False
try:
from __main__ import display
except ImportError:
@ -297,7 +304,18 @@ class Connection(ConnectionBase):
'''
display.vvv("ESTABLISH WINRM CONNECTION FOR USER: %s on PORT %s TO %s" %
(self._winrm_user, self._winrm_port, self._winrm_host), host=self._winrm_host)
netloc = '%s:%d' % (self._winrm_host, self._winrm_port)
winrm_host = self._winrm_host
if HAS_IPADDRESS:
display.vvvv("checking if winrm_host %s is an IPv6 address" % winrm_host)
try:
ipaddress.IPv6Address(winrm_host)
except ipaddress.AddressValueError:
pass
else:
winrm_host = "[%s]" % winrm_host
netloc = '%s:%d' % (winrm_host, self._winrm_port)
endpoint = urlunsplit((self._winrm_scheme, netloc, self._winrm_path, '', ''))
errors = []
for transport in self._winrm_transport: