Docs - add shared snippet note about password prompts for ssh keys (#40633)

* Docs - add shared snippet note about password prompts for ssh keys

Signed-off-by: Adam Miller <admiller@redhat.com>

* add note to ssh connection plugin, fix markup, fix typo

Signed-off-by: Adam Miller <admiller@redhat.com>

docs/docsite/rst/user_guide/intro_getting_started.rst

@@ -34,6 +34,8 @@ Occasionally you'll encounter a device that doesn't support SFTP. This is rare,
 
 When speaking with remote machines, Ansible by default assumes you are using SSH keys.  SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``.  If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated).
 
+.. include:: shared_snippets/SSH_password_prompt.txt
+
 While it may be common sense, it is worth sharing: Any management system benefits from being run near the machines being managed. If you are running Ansible in a cloud, consider running it from a machine inside that cloud.  In most cases this will work better than on the open Internet.
 
 As an advanced topic, Ansible doesn't just have to connect remotely over SSH.  The transports are pluggable, and there are options for managing things locally, as well as managing chroot, lxc, and jail containers.  A mode called 'ansible-pull' can also invert the system and have systems 'phone home' via scheduled git checkouts to pull configuration directives from a central repository.

docs/docsite/rst/user_guide/intro_inventory.rst

@@ -336,6 +336,8 @@ As described above, setting the following variables control how Ansible interact
 
 Host connection:
 
+.. include:: shared_snippets/SSH_password_prompt.txt
+
 ansible_connection
     Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``.  The default is smart. Non-SSH based types are described in the next section.
 

docs/docsite/rst/user_guide/shared_snippets/SSH_password_prompt.txt

@@ -0,0 +1,2 @@
+.. note::
+   Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using the ssh connection plugin (which is the default). The use of ``ssh-agent`` is highly recommended.

lib/ansible/plugins/connection/ssh.py

@@ -12,6 +12,9 @@ DOCUMENTATION = '''
     short_description: connect via ssh client binary
     description:
         - This connection plugin allows ansible to communicate to the target machines via normal ssh command line.
+        - Ansible does not expose a channel to allow communication between the user and the ssh process to accept
+          a password manually to decrypt an ssh key when using this connection plugin (which is the default). The
+          use of ``ssh-agent`` is highly recommended.
     author: ansible (@core)
     version_added: historical
     options:
@@ -59,7 +62,7 @@ DOCUMENTATION = '''
       ssh_executable:
           default: ssh
           description:
-            - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH.
+            - This defines the location of the ssh binary. It defaults to ``ssh`` which will use the first ssh binary available in $PATH.
             - This option is usually not required, it might be useful when access to system ssh is restricted,
               or when using ssh wrappers to connect to remote hosts.
           env: [{name: ANSIBLE_SSH_EXECUTABLE}]
@@ -70,7 +73,7 @@ DOCUMENTATION = '''
       sftp_executable:
           default: sftp
           description:
-            - This defines the location of the sftp binary. It defaults to `sftp` which will use the first binary available in $PATH.
+            - This defines the location of the sftp binary. It defaults to ``sftp`` which will use the first binary available in $PATH.
           env: [{name: ANSIBLE_SFTP_EXECUTABLE}]
           ini:
           - {key: sftp_executable, section: ssh_connection}
@@ -84,11 +87,11 @@ DOCUMENTATION = '''
           - {key: scp_executable, section: ssh_connection}
           version_added: "2.6"
       scp_extra_args:
-          description: Extra exclusive to the 'scp' CLI
+          description: Extra exclusive to the ``scp`` CLI
           vars:
               - name: ansible_scp_extra_args
       sftp_extra_args:
-          description: Extra exclusive to the 'sftp' CLI
+          description: Extra exclusive to the ``sftp`` CLI
           vars:
               - name: ansible_sftp_extra_args
       ssh_extra_args: