<commit_before>Windows Support
===============

.. contents:: Topics

.. _windows_how_does_it_work:

Windows: How Does It Work
`````````````````````````

As you may have already read, Ansible manages Linux/Unix machines using SSH by default.

Starting in version 1.7, Ansible also contains support for managing Windows machines.  This uses
native PowerShell remoting, rather than SSH.

Ansible will still be run from a Linux control machine, and uses the "winrm" Python module to talk to remote hosts.
While not supported by Microsoft or Ansible, this Linux control machine can be a Windows Subsystem for Linux (WSL) bash shell.

No additional software needs to be installed on the remote machines for Ansible to manage them, it still maintains the agentless properties that make it popular on Linux/Unix.

Note that it is expected you have a basic understanding of Ansible prior to jumping into this section, so if you haven't written a Linux playbook first, it might be worthwhile to dig in there first.

.. _windows_installing:

Installing on the Control Machine
`````````````````````````````````

On a Linux control machine::

   pip install "pywinrm>=0.2.2"

.. Note:: on distributions with multiple python versions, use pip2 or pip2.x, where x matches the python minor version Ansible is running under.


.. _windows_control_machine:

Using a Windows control machine
```````````````````````````````
A Linux control machine is required to manage Windows hosts. This Linux control machine can be a Windows Subsystem for Linux (WSL) bash shell.


.. Note:: Running Ansible from a Windows control machine directly is not a goal of the project.  Refrain from asking for this feature, as it limits what technologies, features, and code we can use in the main project in the future.  

.. Note:: The Windows Subsystem for Linux (Beta) is not supported by Microsoft or Ansible and should not be used for production systems. 

If you would like to experiment with the Windows Subsystem for Linux (WSL), first enable the Windows Subsystem for Linux using
`these instructions <https://www.jeffgeerling.com/blog/2017/using-ansible-through-windows-10s-subsystem-linux>`_.
This requires a reboot.

Once WSL is enabled, you can open the Bash terminal. The first time you so this, a few questions need to be answered.
At the prompt you can quickly start using the Ansible devel branch by running the following commands::

    sudo apt-get install python-pip
    pip install pywinrm
    git clone https://github.com/ansible/ansible.git
    source ansible/hacking/env-setup

After you've successfully run these commands, you can start to create your inventory, write example playbooks and start targeting systems using the plethora of available Windows modules.

.. Note:: Ansible is also reported to work on Cygwin, but this is more cumbersome and doesn't scale as well as WSL.


Authentication Options
``````````````````````

When connecting to a Windows host there are different authentication options that can be used. The options and the features they support are:

+-------------+----------------+---------------------------+-----------------------+
| Option      | Local Accounts | Active Directory Accounts | Credential Delegation |
+=============+================+===========================+=======================+
| Basic       | Yes            | No                        | No                    |
+-------------+----------------+---------------------------+-----------------------+
| Certificate | Yes            | No                        | No                    |
+-------------+----------------+---------------------------+-----------------------+
| Kerberos    | No             | Yes                       | Yes                   |
+-------------+----------------+---------------------------+-----------------------+
| NTLM        | Yes            | Yes                       | No                    |
+-------------+----------------+---------------------------+-----------------------+
| CredSSP     | Yes            | Yes                       | Yes                   |
+-------------+----------------+---------------------------+-----------------------+

You can specify which authentication option you wish to use by setting it to the ``ansible_winrm_transport`` variable.

Certificate
+++++++++++

Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used instead.


Kerberos
++++++++<commit_msg>update WSL installation docs for current builds (#25237)<commit_after>Windows Support
===============

.. contents:: Topics

.. _windows_how_does_it_work:

Windows: How Does It Work
`````````````````````````

As you may have already read, Ansible manages Linux/Unix machines using SSH by default.

Starting in version 1.7, Ansible also contains support for managing Windows machines.  This uses
native PowerShell remoting, rather than SSH.

Ansible will still be run from a Linux control machine, and uses the "winrm" Python module to talk to remote hosts.
While not supported by Microsoft or Ansible, this Linux control machine can be a Windows Subsystem for Linux (WSL) bash shell.

No additional software needs to be installed on the remote machines for Ansible to manage them, it still maintains the agentless properties that make it popular on Linux/Unix.

Note that it is expected you have a basic understanding of Ansible prior to jumping into this section, so if you haven't written a Linux playbook first, it might be worthwhile to dig in there first.

.. _windows_installing:

Installing on the Control Machine
`````````````````````````````````

On a Linux control machine::

   pip install "pywinrm>=0.2.2"

.. Note:: on distributions with multiple python versions, use pip2 or pip2.x, where x matches the python minor version Ansible is running under.


.. _windows_control_machine:

Using a Windows control machine
```````````````````````````````
A Linux control machine is required to manage Windows hosts. This Linux control machine can be a Windows Subsystem for Linux (WSL) bash shell.


.. Note:: Running Ansible from a Windows control machine directly is not a goal of the project.  Refrain from asking for this feature, as it limits what technologies, features, and code we can use in the main project in the future.  

.. Note:: The Windows Subsystem for Linux (Beta) is not supported by Microsoft or Ansible and should not be used for production systems. 

If you would like to experiment with the Windows Subsystem for Linux (WSL), first enable the Windows Subsystem for Linux using
`these instructions <https://www.jeffgeerling.com/blog/2017/using-ansible-through-windows-10s-subsystem-linux>`_.
This requires a reboot.

Once WSL is enabled, you can open the Bash terminal. At the prompt, you can quickly start using the latest Ansible release by running the following commands::

    sudo apt-get update
    sudo apt-get install python-pip git libffi-dev libssl-dev -y
    pip install ansible pywinrm

    # this step is only necessary for Windows builds earlier than 16188, and must be repeated each time bash is launched,
    # unless bash is launched as ``bash --login``
    # see https://github.com/Microsoft/BashOnWindows/issues/2148 and
    # https://github.com/Microsoft/BashOnWindows/issues/816#issuecomment-301216901 for details
    source ~/.profile

After you've successfully run these commands, you can start to create your inventory, write example playbooks and start targeting systems using the plethora of available Windows modules.

If you want to run Ansible from source for development purposes, simply uninstall the pip-installed version (which will leave all the necessary dependencies behind), then clone the Ansible source, and run the hacking script to configure it to run from source::

    pip uninstall ansible -y
    git clone https://github.com/ansible/ansible.git
    source ansible/hacking/env-setup

.. Note:: Ansible is also reported to "work" on Cygwin, but installation is more cumbersome, and will incur sporadic failures due to Cygwin's implementation of ``fork()``.


Authentication Options
``````````````````````

When connecting to a Windows host there are different authentication options that can be used. The options and the features they support are:

+-------------+----------------+---------------------------+-----------------------+
| Option      | Local Accounts | Active Directory Accounts | Credential Delegation |
+=============+================+===========================+=======================+
| Basic       | Yes            | No                        | No                    |
+-------------+----------------+---------------------------+-----------------------+
| Certificate | Yes            | No                        | No                    |
+-------------+----------------+---------------------------+-----------------------+
| Kerberos    | No             | Yes                       | Yes                   |
+-------------+----------------+---------------------------+-----------------------+
| NTLM        | Yes            | Yes                       | No                    |
+-------------+----------------+---------------------------+-----------------------+
| CredSSP     | Yes            | Yes                       | Yes                   |
+-------------+----------------+---------------------------+-----------------------+

You can specify which authentication option you wish to use by setting it to the ``ansible_winrm_transport`` variable.

Certificate
+++++++++++

Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used instead.


Kerberos
++++++++
{'fraction_non_alphanumeric': 0.189769820971867, 'fraction_numerical': 0.005319693094629156, 'mean_word_length': 2.2264026402640265, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4132317', 'n_tokens_mistral': 2333, 'n_tokens_neox': 2078, 'n_words': 1098}