diff options
Diffstat (limited to 'docs/docsite/rst/inventory_guide/connection_details.rst')
| -rw-r--r-- | docs/docsite/rst/inventory_guide/connection_details.rst | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/docs/docsite/rst/inventory_guide/connection_details.rst b/docs/docsite/rst/inventory_guide/connection_details.rst new file mode 100644 index 0000000..5e33216 --- /dev/null +++ b/docs/docsite/rst/inventory_guide/connection_details.rst @@ -0,0 +1,123 @@ +.. _connections: + +****************************** +Connection methods and details +****************************** + +This section shows you how to expand and refine the connection methods Ansible uses for your inventory. + +ControlPersist and paramiko +--------------------------- + +By default, Ansible uses native OpenSSH, because it supports ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. If your control machine uses an older version of OpenSSH that does not support ControlPersist, Ansible will fallback to a Python implementation of OpenSSH called 'paramiko'. + +.. _connection_set_user: + +Setting a remote user +--------------------- + +By default, Ansible connects to all remote devices with the user name you are using on the control node. If that user name does not exist on a remote device, you can set a different user name for the connection. If you just need to do some tasks as a different user, look at :ref:`become`. You can set the connection user in a playbook: + +.. code-block:: yaml + + --- + - name: update webservers + hosts: webservers + remote_user: admin + + tasks: + - name: thing to do first in this playbook + . . . + +as a host variable in inventory: + +.. code-block:: text + + other1.example.com ansible_connection=ssh ansible_user=myuser + other2.example.com ansible_connection=ssh ansible_user=myotheruser + +or as a group variable in inventory: + +.. code-block:: yaml + + cloud: + hosts: + cloud1: my_backup.cloud.com + cloud2: my_backup2.cloud.com + vars: + ansible_user: admin + +.. seealso:: + + :ref:`ssh_connection` + Details on the ``remote_user`` keyword and ``ansible_user`` variable. + :ref:`general_precedence_rules` + Details on Ansible precedence rules. + +Setting up SSH keys +------------------- + +By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the ``--ask-pass`` option. If you need to provide a password for :ref:`privilege escalation <become>` (sudo, pbrun, and so on), use ``--ask-become-pass``. + +.. include:: shared_snippets/SSH_password_prompt.txt + +To set up SSH agent to avoid retyping passwords, you can do: + +.. code-block:: bash + + $ ssh-agent bash + $ ssh-add ~/.ssh/id_rsa + +Depending on your setup, you may wish to use Ansible's ``--private-key`` command line option to specify a pem file instead. You can also add the private key file: + +.. code-block:: bash + + $ ssh-agent bash + $ ssh-add ~/.ssh/keypair.pem + +Another way to add private key files without using ssh-agent is using ``ansible_ssh_private_key_file`` in an inventory file as explained here: :ref:`intro_inventory`. + +Running against localhost +------------------------- + +You can run commands against the control node by using "localhost" or "127.0.0.1" for the server name: + +.. code-block:: bash + + $ ansible localhost -m ping -e 'ansible_python_interpreter="/usr/bin/env python"' + +You can specify localhost explicitly by adding this to your inventory file: + +.. code-block:: bash + + localhost ansible_connection=local ansible_python_interpreter="/usr/bin/env python" + +.. _host_key_checking_on: + +Managing host key checking +-------------------------- + +Ansible enables host key checking by default. Checking host keys guards against server spoofing and man-in-the-middle attacks, but it does require some maintenance. + +If a host is reinstalled and has a different key in 'known_hosts', this will result in an error message until corrected. If a new host is not in 'known_hosts' your control node may prompt for confirmation of the key, which results in an interactive experience if using Ansible, from say, cron. You might not want this. + +If you understand the implications and wish to disable this behavior, you can do so by editing ``/etc/ansible/ansible.cfg`` or ``~/.ansible.cfg``: + +.. code-block:: text + + [defaults] + host_key_checking = False + +Alternatively this can be set by the :envvar:`ANSIBLE_HOST_KEY_CHECKING` environment variable: + +.. code-block:: bash + + $ export ANSIBLE_HOST_KEY_CHECKING=False + +Also note that host key checking in paramiko mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature. + +Other connection methods +------------------------ + +Ansible can use a variety of connection methods beyond SSH. You can select any connection plugin, including managing things locally and 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. |