From 21feca6683007dd146b88ce8030beb4a8d25250a Mon Sep 17 00:00:00 2001 From: Adam Miller Date: Wed, 23 May 2018 17:01:55 -0500 Subject: [PATCH] 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 * add note to ssh connection plugin, fix markup, fix typo Signed-off-by: Adam Miller --- .../rst/user_guide/intro_getting_started.rst | 20 ++++++++++--------- .../rst/user_guide/intro_inventory.rst | 4 +++- .../shared_snippets/SSH_password_prompt.txt | 2 ++ lib/ansible/plugins/connection/ssh.py | 11 ++++++---- 4 files changed, 23 insertions(+), 14 deletions(-) create mode 100644 docs/docsite/rst/user_guide/shared_snippets/SSH_password_prompt.txt diff --git a/docs/docsite/rst/user_guide/intro_getting_started.rst b/docs/docsite/rst/user_guide/intro_getting_started.rst index ebd39f01414..78477e82860 100644 --- a/docs/docsite/rst/user_guide/intro_getting_started.rst +++ b/docs/docsite/rst/user_guide/intro_getting_started.rst @@ -11,7 +11,7 @@ Foreword ```````` Now that you've read the :ref:`installation guide` and installed Ansible, it's time to get -started with some ad-hoc commands. +started with some ad-hoc commands. What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible. These features are handled by playbooks which are covered in a separate section. @@ -24,9 +24,9 @@ Remote Connection Information ````````````````````````````` Before we get started, it's important to understand how Ansible communicates with remote -machines over SSH. +machines over SSH. -By default, Ansible will try to use native +By default, Ansible will try to use native OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform. @@ -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. @@ -51,8 +53,8 @@ public SSH key should be located in ``authorized_keys`` on those systems:: 192.0.2.50 aserver.example.org bserver.example.org - - + + This is an inventory file, which is also explained in greater depth here: :doc:`intro_inventory`. We'll assume you are using SSH keys for authentication. To set up SSH agent to avoid retyping passwords, you can @@ -81,7 +83,7 @@ If you would like to access sudo mode, there are also flags to do that: # as bruce $ ansible all -m ping -u bruce # as bruce, sudoing to root - $ ansible all -m ping -u bruce --sudo + $ ansible all -m ping -u bruce --sudo # as bruce, sudoing to batman $ ansible all -m ping -u bruce --sudo --sudo-user batman @@ -95,13 +97,13 @@ If you would like to access sudo mode, there are also flags to do that: replacement. Flags passed to sudo (like -H) can also be set there.) Now run a live command on all of your nodes: - + .. code-block:: bash $ ansible all -a "/bin/echo hello" Congratulations! You've just contacted your nodes with Ansible. It's -soon going to be time to: read about some more real-world cases in :doc:`intro_adhoc`, +soon going to be time to: read about some more real-world cases in :doc:`intro_adhoc`, explore what you can do with different modules, and to learn about the Ansible :doc:`playbooks` language. Ansible is not just about running commands, it also has powerful configuration management and deployment features. There's more to @@ -126,7 +128,7 @@ You can specify localhost explicitly by adding this to your inventory file:: Host Key Checking ````````````````` -Ansible has host key checking enabled by default. +Ansible has host key checking enabled by default. If a host is reinstalled and has a different key in 'known_hosts', this will result in an error message until corrected. If a host is not initially in 'known_hosts' this will result in prompting for confirmation of the key, which results in an interactive experience if using Ansible, from say, cron. You might not want this. diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst index ccce561fb10..338d873fc22 100644 --- a/docs/docsite/rst/user_guide/intro_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_inventory.rst @@ -290,7 +290,7 @@ Ansible will read all the files in these directories in lexicographical order. A All hosts that are in the 'raleigh' group will have the variables defined in these files available to them. This can be very useful to keep your variables organized when a single file starts to be too big, or when you want to use :doc:`Ansible Vault` on a part of a group's -variables. +variables. Tip: The ``group_vars/`` and ``host_vars/`` directories can exist in the playbook directory OR the inventory directory. If both paths exist, variables in the playbook @@ -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. diff --git a/docs/docsite/rst/user_guide/shared_snippets/SSH_password_prompt.txt b/docs/docsite/rst/user_guide/shared_snippets/SSH_password_prompt.txt new file mode 100644 index 00000000000..dc61ab38b70 --- /dev/null +++ b/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. diff --git a/lib/ansible/plugins/connection/ssh.py b/lib/ansible/plugins/connection/ssh.py index 57494a9d0dd..144de68040b 100644 --- a/lib/ansible/plugins/connection/ssh.py +++ b/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: