* Add support for Windows hosts in the SSH connection plugin
* fix Python 2.6 unit test and sanity issues
* fix up connection tests in CI, disable SCP for now
* ensure we don't pollute the existing environment during the test
* Add connection_windows_ssh to classifier
* use test dir for inventory file
* Required powershell as default shell and fix tests
* Remove exlicit become_methods on connection
* clarify console encoding comment
* ignore recent SCP errors in integration tests
* Add cmd shell type and added more tests
* Fix some doc issues
* revises windows faq
* add anchors for windows links
* revises windows setup page
* Update changelogs/fragments/windows-ssh.yaml
Co-Authored-By: jborean93 <jborean93@gmail.com>
See :ref:`this question <windows_faq_winrm>` for more information about WinRM limitations.
What modules are available?
```````````````````````````
What Windows modules are available?
```````````````````````````````````
Most of the Ansible modules in Ansible Core are written for a combination of
Linux/Unix machines and arbitrary web services. These modules are written in
Python and most of them do not work on Windows.
@ -147,39 +153,54 @@ In addition, the following Ansible Core modules/action-plugins work with Windows
* template (also: win_template)
* wait_for_connection
Can I run Python modules?
`````````````````````````
Can I run Python modules on Windows hosts?
``````````````````````````````````````````
No, the WinRM connection protocol is set to use PowerShell modules, so Python
modules will not work. A way to bypass this issue to use
``delegate_to: localhost`` to run a Python module on the Ansible controller.
This is useful if during a playbook, an external service needs to be contacted
and there is no equivalent Windows module available.
Can I connect over SSH?
```````````````````````
Microsoft has announced and is developing a fork of OpenSSH for Windows that
allows remote manage of Windows servers through the SSH protocol instead of
WinRM. While this can be installed and used right now for normal SSH clients,
it is still in beta from Microsoft and the required functionality has not been
developed within Ansible yet.
.._winrm_faq_ssh:
There are future plans on adding this feature and this page will be updated
once more information can be shared.
Can I connect to Windows hosts over SSH?
````````````````````````````````````````
Ansible 2.8 has added experimental support for using the SSH connection plugin
to manage Windows hosts. To connect to Windows hosts over SSH, you must install and configure the `Win32-OpenSSH <https://github.com/PowerShell/Win32-OpenSSH>`_
fork that is in development with Microsoft on
the Windows host(s). While most of the basics should work with SSH,
``Win32-OpenSSH`` is rapidly changing, with new features added and bugs
fixed in every release. It is highly recommend you install the latest release
of ``Win32-OpenSSH`` from the GitHub Releases page when using it with Ansible
on Windows hosts.
Why is connecting to the host via ssh failing?
``````````````````````````````````````````````
When trying to connect to a Windows host and the output error indicates that
SSH was used, then this is an indication that the connection vars are not set
properly or the host is not inheriting them correctly.
To use SSH as the connection to a Windows host, set the following variables in
the inventory::
ansible_connection=ssh
# Set either cmd or powershell not both
ansible_shell_type=cmd
# ansible_shell_type=powershell
The value for ``ansible_shell_type`` should either be ``cmd`` or ``powershell``.
Use ``cmd`` if the ``DefaultShell`` has not been configured on the SSH service
and ``powershell`` if that has been set as the ``DefaultShell``.
Why is connecting to a Windows host via SSH failing?
The script works by checking to see what programs need to be installed
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
@ -77,15 +79,15 @@ actions are required.
..Note:: Windows Server 2008 can only install PowerShell 3.0; specifying a
newer version will result in the script failing.
..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
..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
Ansible will fail to execute certain commands on the Windows host. These
hotfixes should 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.
@ -127,10 +129,10 @@ There are different switches and parameters (like ``-EnableCredSSP`` and
``-ForceNewSSLCert``) that can be set alongside this script. The documentation
for these options are located at the top of the script itself.
..Note:: The ConfigureRemotingForAnsible.ps1 script is intended for training and
..Note:: The ConfigureRemotingForAnsible.ps1 script is intended for training and
development purposes only and should not be used in a
production environment, since it enables settings (like ``Basic`` authentication)
that can be inherently insecure.
production environment, since it enables settings (like ``Basic`` authentication)
that can be inherently insecure.
WinRM Listener
--------------
@ -193,7 +195,7 @@ the key options that are useful to understand are:
.. comment: Pygments powershell lexer does not support colons (i.e. URLs)
Jordan Borean
5 years ago
committed by