Add support for Windows hosts in the SSH connection plugin

changelogs/fragments/windows-ssh.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+- Added experimental support for connecting to Windows hosts over SSH using ``ansible_shell_type=cmd`` or ``ansible_shell_type=powershell``

docs/docsite/rst/user_guide/windows.rst

@@ -1,11 +1,13 @@
+.. _windows:
+
 Windows Guides
 ``````````````
 
 The following sections provide information on managing
 Windows hosts with Ansible.
 
 Because Windows is a non-POSIX-compliant operating system, there are differences between
-how Ansible interacts with them and the way Windows works. These guides will highlight 
+how Ansible interacts with them and the way Windows works. These guides will highlight
 some of the differences between Linux/Unix hosts and hosts running Windows.
 
 .. toctree::

docs/docsite/rst/user_guide/windows_faq.rst

@@ -1,3 +1,5 @@
+.. _windows_faq:
+
 Windows Frequently Asked Questions
 ==================================
 
@@ -6,7 +8,7 @@ their answers.
 
 .. note:: This document covers questions about managing Microsoft Windows servers with Ansible.
     For questions about Ansible Core, please see the
-    :ref:`FAQ page <ansible_faq>`.
+    :ref:`general FAQ page <ansible_faq>`.
 
 Does Ansible work with Windows XP or Server 2003?
 ``````````````````````````````````````````````````
@@ -22,19 +24,19 @@ supported operating system versions are:
 * Windows 8.1
 * Windows 10
 
-Ansible also has minimum PowerShell version requirements - please see 
-:doc:`windows_setup` for the latest information.
+Ansible also has minimum PowerShell version requirements - please see
+:ref:`windows_setup` for the latest information.
 
-Can I Manage Windows Nano Server?
-`````````````````````````````````
+Can I manage Windows Nano Server with Ansible?
+``````````````````````````````````````````````
 Windows Nano Server is not currently supported by Ansible, since it does
 not have access to the full .NET Framework that is used by the majority of the
 modules and internal components.
 
 Can Ansible run on Windows?
 ```````````````````````````
-No, Ansible cannot run on a Windows host natively and can only manage Windows hosts,
-but Ansible can be run under the Windows Subsystem for Linux (WSL).
+No, Ansible can only manage Windows hosts. Ansible cannot run on a Windows host
+natively, though it can run under the Windows Subsystem for Linux (WSL).
 
 .. note:: The Windows Subsystem for Linux is not supported by Ansible and
     should not be used for production systems.
@@ -60,16 +62,20 @@ installed version and then clone the git repo.
     # To enable Ansible on login, run the following
     echo ". ~/ansible/hacking/env-setup -q' >> ~/.bashrc
 
-Can I use SSH keys to authenticate?
-```````````````````````````````````
-Windows uses WinRM as the transport protocol. WinRM supports a wide range of
-authentication options. The closet option to SSH keys is to use the certificate
-authentication option which maps an X509 certificate to a local user.
+Can I use SSH keys to authenticate to Windows hosts?
+````````````````````````````````````````````````````
+SSH keys are not supported when using the WinRM or PSRP connection plugins.
+These connection plugins support X509 certificates for authentication instead
+of the SSH key pairs that SSH supports.
 
-The way that these certificates are generated and mapped to a user is different
-from the SSH implementation; consult the :doc:`windows_winrm` documentation for 
+The way X509 certificates are generated and mapped to a user is different
+from the SSH implementation; consult the :ref:`windows_winrm` documentation for
 more information.
 
+Ansible 2.8 has added experimental support for using the SSH connection plugin,
+which supports authentication with SSH keys, to connect to Windows servers. See `this question <windows_faq_ssh>`
+for more information.
+
 .. _windows_faq_winrm:
 
 Why can I run a command locally that does not work under Ansible?
@@ -82,7 +88,7 @@ running a command locally in these ways:
   delegate the user's credentials to a network resource, causing ``Access is
   Denied`` errors.
 
-* All processes run under WinRM are in a non-interactive session. Applications 
+* All processes run under WinRM are in a non-interactive session. Applications
   that require an interactive session will not work.
 
 * When running through WinRM, Windows restricts access to internal Windows
@@ -93,7 +99,7 @@ Some ways to bypass these restrictions are to:
 
 * Use ``become``, which runs a command as it would when run locally. This will
   bypass most WinRM restrictions, as Windows is unaware the process is running
-  under WinRM when ``become`` is used. See the :doc:`become` documentation for more 
+  under WinRM when ``become`` is used. See the :ref:`become` documentation for more
   information.
 
 * Use a scheduled task, which can be created with ``win_scheduled_task``. Like
@@ -107,15 +113,15 @@ Some ways to bypass these restrictions are to:
   authentication option that supports credential delegation can be used. Both
   CredSSP and Kerberos with credential delegation enabled can support this.
 
-See :doc:`become` more info on how to use become. The limitations section at
-:doc:`windows_winrm` has more details around WinRM limitations.
+See :ref:`become` more info on how to use become. The limitations section at
+:ref:`windows_winrm` has more details around WinRM limitations.
 
-This program won't install with Ansible
-```````````````````````````````````````
+This program won't install on Windows with Ansible
+``````````````````````````````````````````````````
 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?
+````````````````````````````````````````````````````
+Unless you are using ``Win32-OpenSSH`` as described above, you must connect to
+Windows hosts using :ref:`windows_winrm`. If your Ansible output indicates that
+SSH was used, either you did not set the connection vars properly or the host is not inheriting them correctly.
 
 Make sure ``ansible_connection: winrm`` is set in the inventory for the Windows
-host.
+host(s).
 
 Why are my credentials being rejected?
 ``````````````````````````````````````
 This can be due to a myriad of reasons unrelated to incorrect credentials.
 
-See HTTP 401/Credentials Rejected at :doc:`windows_setup` for a more detailed
+See HTTP 401/Credentials Rejected at :ref:`windows_setup` for a more detailed
 guide of this could mean.
 
 Why am I getting an error SSL CERTIFICATE_VERIFY_FAILED?
@@ -196,13 +217,11 @@ host.
 
 .. seealso::
 
-   :doc:`index`
-       The documentation index
-   :doc:`windows`
+   :ref:`windows`
        The Windows documentation index
-   :doc:`playbooks`
+   :ref:`about_playbooks`
        An introduction to playbooks
-   :doc:`playbooks_best_practices`
+   :ref:`playbooks_best_practices`
        Best practices advice
    `User Mailing List <https://groups.google.com/group/ansible-project>`_
        Have a question?  Stop by the google group!