Few fixes for reference_appendices/faq.html (#70719)

* Format using `` instead of `, add line breaks for long lines, rephrase or remove useless text.
Move some text.

* Add clearer version of OpenSSh is affected by SCP bug

* Review some pages using ansible doc writing guide.
This commit is contained in:
Baptiste Mille-Mathias 2020-07-20 20:43:39 +02:00 committed by GitHub
parent fb3db170cc
commit 92e16c2838
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 106 additions and 85 deletions

View file

@ -279,7 +279,7 @@ This creates a tarball of the built collection in the current directory which ca
└── ... └── ...
.. note:: .. note::
* Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections` to exclude other files you would not wish to distribute. * Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections` to exclude other files you would not want to distribute.
* If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``. * If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
* The current Galaxy maximum tarball size is 2 MB. * The current Galaxy maximum tarball size is 2 MB.
@ -430,7 +430,7 @@ To upload the collection artifact with the ``ansible-galaxy`` command:
The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details. The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website.
The command waits until the import process completes before reporting the status back. If you wish to continue The command waits until the import process completes before reporting the status back. If you want to continue
without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your
`My Imports <https://galaxy.ansible.com/my-imports/>`_ page. `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.

View file

@ -628,7 +628,7 @@ tests for win_stat:
- Create a copy of ``./test/integration/inventory.winrm.template`` and name it ``inventory.winrm``. - Create a copy of ``./test/integration/inventory.winrm.template`` and name it ``inventory.winrm``.
- Fill in entries under ``[windows]`` and set the required variables that are needed to connect to the host. - Fill in entries under ``[windows]`` and set the required variables that are needed to connect to the host.
- :ref:`Install the required Python modules <windows_winrm>` to support WinRM and a configured authentication method. - :ref:`Install the required Python modules <windows_winrm>` to support WinRM and a configured authentication method.
- To execute the integration tests, run ``ansible-test windows-integration win_stat``; you can replace ``win_stat`` with the role you wish to test. - To execute the integration tests, run ``ansible-test windows-integration win_stat``; you can replace ``win_stat`` with the role you want to test.
This will execute all the tests currently defined for that role. You can set This will execute all the tests currently defined for that role. You can set
the verbosity level using the ``-v`` argument just as you would with the verbosity level using the ``-v`` argument just as you would with

View file

@ -120,7 +120,7 @@ When you choose to use your username and password, your password is not sent to
It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
destroyed. destroyed.
If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the ``--github-token`` option to pass a personal access token that you create. If you do not want to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the ``--github-token`` option to pass a personal access token that you create.
Import a role Import a role

View file

@ -173,9 +173,9 @@ Installing roles from Galaxy
The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can
also use it to create a new role, remove roles, or perform tasks on the Galaxy website. also use it to create a new role, remove roles, or perform tasks on the Galaxy website.
The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. Since the `Galaxy project <https://github.com/ansible/galaxy>`_ The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. If you run your own internal Galaxy server
is an open source project, you may be running your own internal Galaxy server and wish to override the default server address. You can do this using the *--server* option and want to use it instead of the default one, pass the ``--server`` option following the address of this galaxy server. You can set permanently this option by setting
or by setting the Galaxy server value in your *ansible.cfg* file. For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`. the Galaxy server value in your ``ansible.cfg`` file to use it . For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`.
Installing roles Installing roles
@ -195,8 +195,8 @@ By default, Ansible downloads roles to the first writable directory in the defau
You can override this with one of the following options: You can override this with one of the following options:
* Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session. * Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session.
* Define ``roles_path`` in an ``ansible.cfg`` file.
* Use the ``--roles-path`` option for the ``ansible-galaxy`` command. * Use the ``--roles-path`` option for the ``ansible-galaxy`` command.
* Define ``roles_path`` in an ``ansible.cfg`` file.
The following provides an example of using ``--roles-path`` to install the role into the current working directory: The following provides an example of using ``--roles-path`` to install the role into the current working directory:
@ -212,7 +212,8 @@ The following provides an example of using ``--roles-path`` to install the role
Installing a specific version of a role Installing a specific version of a role
--------------------------------------- ---------------------------------------
When the Galaxy server imports a role, it imports any git tags matching the Semantic Version format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. When the Galaxy server imports a role, it imports any git tags matching the `Semantic Version <https://semver.org/>`_ format as versions.
In turn, you can download a specific version of a role by specifying one of the imported tags.
To see the available versions for a role: To see the available versions for a role:

View file

@ -51,25 +51,24 @@ See the rest of the documentation for more information about how to organize var
How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file? How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansible pay attention to my local SSH config file?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Switch your default connection type in the configuration file to 'ssh', or use '-c ssh' to use Switch your default connection type in the configuration file to ``ssh``, or use ``-c ssh`` to use
Native OpenSSH for connections instead of the python paramiko library. In Ansible 1.2.1 and later, 'ssh' will be used Native OpenSSH for connections instead of the python paramiko library. In Ansible 1.2.1 and later, ``ssh`` will be used
by default if OpenSSH is new enough to support ControlPersist as an option. by default if OpenSSH is new enough to support ControlPersist as an option.
Paramiko is great for starting out, but the OpenSSH type offers many advanced options. You will want to run Ansible Paramiko is great for starting out, but the OpenSSH type offers many advanced options. You will want to run Ansible
from a machine new enough to support ControlPersist, if you are using this connection type. You can still manage from a machine new enough to support ControlPersist, if you are using this connection type. You can still manage
older clients. If you are using RHEL 6, CentOS 6, SLES 10 or SLES 11 the version of OpenSSH is still a bit old, so older clients. If you are using RHEL 6, CentOS 6, SLES 10 or SLES 11 the version of OpenSSH is still a bit old, so
consider managing from a Fedora or openSUSE client even though you are managing older nodes, or just use paramiko. consider managing from a Fedora or openSUSE client even though you are managing older nodes, or just use paramiko.
We keep paramiko as the default as if you are first installing Ansible on an EL box, it offers a better experience We keep paramiko as the default as if you are first installing Ansible on these enterprise operating systems, it offers a better experience for new users.
for new users.
.. _use_ssh_jump_hosts: .. _use_ssh_jump_hosts:
How do I configure a jump host to access servers that I have no direct access to? How do I configure a jump host to access servers that I have no direct access to?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
You can set a `ProxyCommand` in the You can set a ``ProxyCommand`` in the
`ansible_ssh_common_args` inventory variable. Any arguments specified in ``ansible_ssh_common_args`` inventory variable. Any arguments specified in
this variable are added to the sftp/scp/ssh command line when connecting this variable are added to the sftp/scp/ssh command line when connecting
to the relevant host(s). Consider the following inventory group: to the relevant host(s). Consider the following inventory group:
@ -84,32 +83,35 @@ You can create `group_vars/gatewayed.yml` with the following contents::
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q user@gateway.example.com"' ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q user@gateway.example.com"'
Ansible will append these arguments to the command line when trying to Ansible will append these arguments to the command line when trying to
connect to any hosts in the group `gatewayed`. (These arguments are used connect to any hosts in the group ``gatewayed``. (These arguments are used
in addition to any `ssh_args` from `ansible.cfg`, so you do not need to in addition to any ``ssh_args`` from ``ansible.cfg``, so you do not need to
repeat global `ControlPersist` settings in `ansible_ssh_common_args`.) repeat global ``ControlPersist`` settings in ``ansible_ssh_common_args``.)
Note that `ssh -W` is available only with OpenSSH 5.4 or later. With Note that ``ssh -W`` is available only with OpenSSH 5.4 or later. With
older versions, it's necessary to execute `nc %h:%p` or some equivalent older versions, it's necessary to execute ``nc %h:%p`` or some equivalent
command on the bastion host. command on the bastion host.
With earlier versions of Ansible, it was necessary to configure a With earlier versions of Ansible, it was necessary to configure a
suitable `ProxyCommand` for one or more hosts in `~/.ssh/config`, suitable ``ProxyCommand`` for one or more hosts in ``~/.ssh/config``,
or globally by setting `ssh_args` in `ansible.cfg`. or globally by setting ``ssh_args`` in ``ansible.cfg``.
.. _ssh_serveraliveinterval: .. _ssh_serveraliveinterval:
How do I get Ansible to notice a dead target in a timely manner? How do I get Ansible to notice a dead target in a timely manner?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
You can add ``-o ServerAliveInterval=NumberOfSeconds`` in ``ssh_args`` from ``ansible.cfg``. Without this option, SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add ``ServerAliveInterval`` into your global SSH configuration. A good value for ``ServerAliveInterval`` is up to you to decide; keep in mind that ``ServerAliveCountMax=3`` is the SSH default so any value you set will be tripled before terminating the SSH session. You can add ``-o ServerAliveInterval=NumberOfSeconds`` in ``ssh_args`` from ``ansible.cfg``. Without this option,
SSH and therefore Ansible will wait until the TCP connection times out. Another solution is to add ``ServerAliveInterval``
into your global SSH configuration. A good value for ``ServerAliveInterval`` is up to you to decide; keep in mind that
``ServerAliveCountMax=3`` is the SSH default so any value you set will be tripled before terminating the SSH session.
.. _ec2_cloud_performance: .. _cloud_provider_performance:
How do I speed up management inside EC2? How do I speed up run of ansible for servers from cloud providers (EC2, openstack,.. )?
++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Don't try to manage a fleet of EC2 machines from your laptop. Connect to a management node inside EC2 first Don't try to manage a fleet of machines of a cloud provider from your laptop.
and run Ansible from there. Rather connect to a management node inside this cloud provider first and run Ansible from there.
.. _python_interpreters: .. _python_interpreters:
@ -136,12 +138,12 @@ workaround you can install Python 2 on the managed host and configure Ansible to
requires Python 2, you can also report a bug on our `bug tracker requires Python 2, you can also report a bug on our `bug tracker
<https://github.com/ansible/ansible/issues>`_ so that the incompatibility can be fixed in a future release. <https://github.com/ansible/ansible/issues>`_ so that the incompatibility can be fixed in a future release.
Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time. Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time.
Also, this works for ANY interpreter, i.e ruby: `ansible_ruby_interpreter`, perl: `ansible_perl_interpreter`, etc, Also, this works for ANY interpreter, i.e ruby: ``ansible_ruby_interpreter``, perl: ``ansible_perl_interpreter``, etc,
so you can use this for custom modules written in any scripting language and control the interpreter location. so you can use this for custom modules written in any scripting language and control the interpreter location.
Keep in mind that if you put `env` in your module shebang line (`#!/usr/bin/env <other>`), Keep in mind that if you put ``env`` in your module shebang line (``#!/usr/bin/env <other>``),
this facility will be ignored so you will be at the mercy of the remote `$PATH`. this facility will be ignored so you will be at the mercy of the remote `$PATH`.
.. _installation_faqs: .. _installation_faqs:
@ -153,7 +155,8 @@ While installing Ansible, sometimes you may encounter errors such as `No package
These errors are generally caused by the missing packages, which are dependencies of the packages required by Ansible. These errors are generally caused by the missing packages, which are dependencies of the packages required by Ansible.
For example, `libffi` package is dependency of `pynacl` and `paramiko` (Ansible -> paramiko -> pynacl -> libffi). For example, `libffi` package is dependency of `pynacl` and `paramiko` (Ansible -> paramiko -> pynacl -> libffi).
In order to solve these kinds of dependency issues, you might need to install required packages using the OS native package managers, such as `yum`, `dnf`, or `apt`, or as mentioned in the package installation guide. In order to solve these kinds of dependency issues, you might need to install required packages using
the OS native package managers, such as `yum`, `dnf`, or `apt`, or as mentioned in the package installation guide.
Refer to the documentation of the respective package for such dependencies and their installation methods. Refer to the documentation of the respective package for such dependencies and their installation methods.
@ -195,7 +198,7 @@ need to install them into the virtualenv. There are two methods:
$ virtualenv ansible --system-site-packages $ virtualenv ansible --system-site-packages
* Copy those files in manually from the system. For instance, for SELinux bindings you might do: * Copy those files in manually from the system. For instance, for SELinux bindings you might do:
.. code-block:: shell .. code-block:: shell
@ -217,8 +220,9 @@ By default, Solaris 10 and earlier run a non-POSIX shell which does not correctl
tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this
is likely the problem. There are several workarounds: is likely the problem. There are several workarounds:
* You can set ``remote_tmp`` to a path that will expand correctly with the shell you are using (see the plugin documentation for :ref:`C shell<csh_shell>`, :ref:`fish shell<fish_shell>`, and :ref:`Powershell<powershell_shell>`). For * You can set ``remote_tmp`` to a path that will expand correctly with the shell you are using
example, in the ansible config file you can set:: (see the plugin documentation for :ref:`C shell<csh_shell>`, :ref:`fish shell<fish_shell>`,
and :ref:`Powershell<powershell_shell>`). For example, in the ansible config file you can set::
remote_tmp=$HOME/.ansible/tmp remote_tmp=$HOME/.ansible/tmp
@ -241,7 +245,7 @@ There are a few common errors that one might run into when trying to execute Ans
* Version 2.7.6 of python for z/OS will not work with Ansible because it represents strings internally as EBCDIC. * Version 2.7.6 of python for z/OS will not work with Ansible because it represents strings internally as EBCDIC.
To get around this limitation, download and install a later version of `python for z/OS <https://www.rocketsoftware.com/zos-open-source>`_ (2.7.13 or 3.6.1) that represents strings internally as ASCII. Version 2.7.13 is verified to work. To get around this limitation, download and install a later version of `python for z/OS <https://www.rocketsoftware.com/zos-open-source>`_ (2.7.13 or 3.6.1) that represents strings internally as ASCII. Version 2.7.13 is verified to work.
* When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with * When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with
@ -264,7 +268,7 @@ There are a few common errors that one might run into when trying to execute Ans
.. error:: .. error::
EE3501S The module libpython2.7.so was not found. EE3501S The module libpython2.7.so was not found.
On z/OS, you must execute python from gnu bash. If gnu bash is installed at ``/usr/lpp/bash``, you can fix this in your inventory by specifying an ``ansible_shell_executable``:: On z/OS, you must execute python from gnu bash. If gnu bash is installed at ``/usr/lpp/bash``, you can fix this in your inventory by specifying an ``ansible_shell_executable``::
zos1 ansible_shell_executable=/usr/lpp/bash/bin/bash zos1 ansible_shell_executable=/usr/lpp/bash/bin/bash
@ -274,7 +278,7 @@ There are a few common errors that one might run into when trying to execute Ans
What is the best way to make content reusable/redistributable? What is the best way to make content reusable/redistributable?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
If you have not done so already, read all about "Roles" in the playbooks documentation. This helps you make playbook content If you have not done so already, read all about "Roles" in the playbooks documentation. This helps you make playbook content
self-contained, and works well with things like git submodules for sharing content with others. self-contained, and works well with things like git submodules for sharing content with others.
If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended. If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended.
@ -292,8 +296,9 @@ See :ref:`intro_configuration`.
How do I disable cowsay? How do I disable cowsay?
++++++++++++++++++++++++ ++++++++++++++++++++++++
If cowsay is installed, Ansible takes it upon itself to make your day happier when running playbooks. If you decide If cowsay is installed, Ansible takes it upon itself to make your day happier when running playbooks. If you decide
that you would like to work in a professional cow-free environment, you can either uninstall cowsay, set ``nocows=1`` in ansible.cfg, or set the :envvar:`ANSIBLE_NOCOWS` environment variable: that you would like to work in a professional cow-free environment, you can either uninstall cowsay, set ``nocows=1``
in ``ansible.cfg``, or set the :envvar:`ANSIBLE_NOCOWS` environment variable:
.. code-block:: shell-session .. code-block:: shell-session
@ -304,13 +309,17 @@ that you would like to work in a professional cow-free environment, you can eith
How do I see a list of all of the ansible\_ variables? How do I see a list of all of the ansible\_ variables?
++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++
Ansible by default gathers "facts" about the machines under management, and these facts can be accessed in Playbooks and in templates. To see a list of all of the facts that are available about a machine, you can run the "setup" module as an ad-hoc action: Ansible by default gathers "facts" about the machines under management, and these facts can be accessed in playbooks
and in templates. To see a list of all of the facts that are available about a machine, you can run the ``setup`` module
as an ad-hoc action:
.. code-block:: shell-session .. code-block:: shell-session
ansible -m setup hostname ansible -m setup hostname
This will print out a dictionary of all of the facts that are available for that particular host. You might want to pipe the output to a pager.This does NOT include inventory variables or internal 'magic' variables. See the next question if you need more than just 'facts'. This will print out a dictionary of all of the facts that are available for that particular host. You might want to pipe
the output to a pager.This does NOT include inventory variables or internal 'magic' variables. See the next question
if you need more than just 'facts'.
.. _browse_inventory_vars: .. _browse_inventory_vars:
@ -353,7 +362,8 @@ file with a list of servers. To do this, you can just access the "$groups" dicti
{{ host }} {{ host }}
{% endfor %} {% endfor %}
If you need to access facts about these hosts, for instance, the IP address of each hostname, you need to make sure that the facts have been populated. For example, make sure you have a play that talks to db_servers:: If you need to access facts about these hosts, for instance, the IP address of each hostname,
you need to make sure that the facts have been populated. For example, make sure you have a play that talks to db_servers::
- hosts: db_servers - hosts: db_servers
tasks: tasks:
@ -373,13 +383,13 @@ How do I access a variable name programmatically?
+++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++
An example may come up where we need to get the ipv4 address of an arbitrary interface, where the interface to be used may be supplied An example may come up where we need to get the ipv4 address of an arbitrary interface, where the interface to be used may be supplied
via a role parameter or other input. Variable names can be built by adding strings together, like so: via a role parameter or other input. Variable names can be built by adding strings together, like so:
.. code-block:: jinja .. code-block:: jinja
{{ hostvars[inventory_hostname]['ansible_' + which_interface]['ipv4']['address'] }} {{ hostvars[inventory_hostname]['ansible_' + which_interface]['ipv4']['address'] }}
The trick about going through hostvars is necessary because it's a dictionary of the entire namespace of variables. ``inventory_hostname`` The trick about going through hostvars is necessary because it's a dictionary of the entire namespace of variables. ``inventory_hostname``
is a magic variable that indicates the current host you are looping over in the host loop. is a magic variable that indicates the current host you are looping over in the host loop.
In the example above, if your interface names have dashes, you must replace them with underscores: In the example above, if your interface names have dashes, you must replace them with underscores:
@ -396,7 +406,8 @@ Also see dynamic_variables_.
How do I access a group variable? How do I access a group variable?
+++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++
Technically, you don't, Ansible does not really use groups directly. Groups are labels for host selection and a way to bulk assign variables, they are not a first class entity, Ansible only cares about Hosts and Tasks. Technically, you don't, Ansible does not really use groups directly. Groups are labels for host selection and a way to bulk assign variables,
they are not a first class entity, Ansible only cares about Hosts and Tasks.
That said, you could just access the variable by selecting a host that is part of that group, see first_host_in_a_group_ below for an example. That said, you could just access the variable by selecting a host that is part of that group, see first_host_in_a_group_ below for an example.
@ -406,9 +417,9 @@ That said, you could just access the variable by selecting a host that is part o
How do I access a variable of the first host in a group? How do I access a variable of the first host in a group?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we
are using dynamic inventory, which host is the 'first' may not be consistent, so you wouldn't want to do this unless your inventory are using dynamic inventory, which host is the 'first' may not be consistent, so you wouldn't want to do this unless your inventory
is static and predictable. (If you are using :ref:`ansible_tower`, it will use database order, so this isn't a problem even if you are using cloud is static and predictable. (If you are using :ref:`ansible_tower`, it will use database order, so this isn't a problem even if you are using cloud
based inventory scripts). based inventory scripts).
Anyway, here's the trick: Anyway, here's the trick:
@ -417,7 +428,7 @@ Anyway, here's the trick:
{{ hostvars[groups['webservers'][0]]['ansible_eth0']['ipv4']['address'] }} {{ hostvars[groups['webservers'][0]]['ansible_eth0']['ipv4']['address'] }}
Notice how we're pulling out the hostname of the first machine of the webservers group. If you are doing this in a template, you Notice how we're pulling out the hostname of the first machine of the webservers group. If you are doing this in a template, you
could use the Jinja2 '#set' directive to simplify this, or in a playbook, you could also use set_fact:: could use the Jinja2 '#set' directive to simplify this, or in a playbook, you could also use set_fact::
- set_fact: headnode={{ groups['webservers'][0] }} - set_fact: headnode={{ groups['webservers'][0] }}
@ -431,14 +442,16 @@ Notice how we interchanged the bracket syntax for dots -- that can be done anywh
How do I copy files recursively onto a target host? How do I copy files recursively onto a target host?
+++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++
The "copy" module has a recursive parameter. However, take a look at the "synchronize" module if you want to do something more efficient for a large number of files. The "synchronize" module wraps rsync. See the module index for info on both of these modules. The ``copy`` module has a recursive parameter. However, take a look at the ``synchronize`` module if you want to do something more efficient
for a large number of files. The ``synchronize`` module wraps rsync. See the module index for info on both of these modules.
.. _shell_env: .. _shell_env:
How do I access shell environment variables? How do I access shell environment variables?
++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++
If you just need to access existing variables ON THE CONTROLLER, use the 'env' lookup plugin.
**On controller machine :** Access existing variables from controller use the ``env`` lookup plugin.
For example, to access the value of the HOME environment variable on the management machine:: For example, to access the value of the HOME environment variable on the management machine::
--- ---
@ -447,15 +460,18 @@ For example, to access the value of the HOME environment variable on the managem
local_home: "{{ lookup('env','HOME') }}" local_home: "{{ lookup('env','HOME') }}"
For environment variables on the TARGET machines, they are available via facts in the 'ansible_env' variable: **On target machines :** Environment variables are available via facts in the ``ansible_env`` variable:
.. code-block:: jinja .. code-block:: jinja
{{ ansible_env.SOME_VARIABLE }} {{ ansible_env.HOME }}
If you need to set environment variables for TASK execution, see :ref:`playbooks_environment` in the :ref:`Advanced Playbooks <playbooks_special_topics>` section. If you need to set environment variables for TASK execution, see :ref:`playbooks_environment`
There are several ways to set environment variables on your target machines. You can use the :ref:`template <template_module>`, :ref:`replace <replace_module>`, or :ref:`lineinfile <lineinfile_module>` modules to introduce environment variables into files. in the :ref:`Advanced Playbooks <playbooks_special_topics>` section.
The exact files to edit vary depending on your OS and distribution and local configuration. There are several ways to set environment variables on your target machines. You can use the
:ref:`template <template_module>`, :ref:`replace <replace_module>`, or :ref:`lineinfile <lineinfile_module>`
modules to introduce environment variables into files. The exact files to edit vary depending on your OS
and distribution and local configuration.
.. _user_passwords: .. _user_passwords:
@ -468,7 +484,7 @@ Ansible ad-hoc command is the easiest option:
ansible all -i localhost, -m debug -a "msg={{ 'mypassword' | password_hash('sha512', 'mysecretsalt') }}" ansible all -i localhost, -m debug -a "msg={{ 'mypassword' | password_hash('sha512', 'mysecretsalt') }}"
The mkpasswd utility that is available on most Linux systems is also a great option: The ``mkpasswd`` utility that is available on most Linux systems is also a great option:
.. code-block:: shell-session .. code-block:: shell-session
@ -476,7 +492,7 @@ The mkpasswd utility that is available on most Linux systems is also a great opt
If this utility is not installed on your system (e.g. you are using macOS) then you can still easily If this utility is not installed on your system (e.g. you are using macOS) then you can still easily
generate these passwords using Python. First, ensure that the `Passlib <https://bitbucket.org/ecollins/passlib/wiki/Home>`_ generate these passwords using Python. First, ensure that the `Passlib <https://foss.heptapod.net/python-libs/passlib/-/wikis/home>`_
password hashing library is installed: password hashing library is installed:
.. code-block:: shell-session .. code-block:: shell-session
@ -492,11 +508,7 @@ Once the library is ready, SHA512 password values can then be generated as follo
Use the integrated :ref:`hash_filters` to generate a hashed version of a password. Use the integrated :ref:`hash_filters` to generate a hashed version of a password.
You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :ref:`playbooks_vault` to encrypt sensitive data. You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :ref:`playbooks_vault` to encrypt sensitive data.
In OpenBSD, a similar option is available in the base system called encrypt(1): In OpenBSD, a similar option is available in the base system called ``encrypt (1)``
.. code-block:: shell-session
encrypt
.. _dot_or_array_notation: .. _dot_or_array_notation:
@ -551,8 +563,11 @@ risky because the parameters and values passed to ``usermod_args`` could
be overwritten by malicious values in the ``host facts`` on a compromised be overwritten by malicious values in the ``host facts`` on a compromised
target machine. To mitigate this risk: target machine. To mitigate this risk:
* set bulk variables at a level of precedence greater than ``host facts`` in the order of precedence found in :ref:`ansible_variable_precedence` (the example above is safe because play vars take precedence over facts) * set bulk variables at a level of precedence greater than ``host facts`` in the order of precedence
* disable the :ref:`inject_facts_as_vars` configuration setting to prevent fact values from colliding with variables (this will also disable the original warning) found in :ref:`ansible_variable_precedence` (the example above is safe because play vars take
precedence over facts)
* disable the :ref:`inject_facts_as_vars` configuration setting to prevent fact values from colliding
with variables (this will also disable the original warning)
.. _commercial_support: .. _commercial_support:
@ -560,9 +575,11 @@ target machine. To mitigate this risk:
Can I get training on Ansible? Can I get training on Ansible?
++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++
Yes! See our `services page <https://www.ansible.com/products/consulting>`_ for information on our services and training offerings. Email `info@ansible.com <mailto:info@ansible.com>`_ for further details. Yes! See our `services page <https://www.ansible.com/products/consulting>`_ for information on our services
and training offerings. Email `info@ansible.com <mailto:info@ansible.com>`_ for further details.
We also offer free web-based training classes on a regular basis. See our `webinar page <https://www.ansible.com/resources/webinars-training>`_ for more info on upcoming webinars. We also offer free web-based training classes on a regular basis. See our
`webinar page <https://www.ansible.com/resources/webinars-training>`_ for more info on upcoming webinars.
.. _web_interface: .. _web_interface:
@ -570,15 +587,7 @@ We also offer free web-based training classes on a regular basis. See our `webin
Is there a web interface / REST API / etc? Is there a web interface / REST API / etc?
++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++
Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`. Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`.
.. _docs_contributions:
How do I submit a change to the documentation?
++++++++++++++++++++++++++++++++++++++++++++++
Great question! Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub <https://github.com/ansible/ansible/blob/devel/docs/docsite/README.md>`_. Thanks!
.. _keep_secret_data: .. _keep_secret_data:
@ -601,7 +610,7 @@ The ``no_log`` attribute can also apply to an entire play::
- hosts: all - hosts: all
no_log: True no_log: True
Though this will make the play somewhat difficult to debug. It's recommended that this Though this will make the play somewhat difficult to debug. It's recommended that this
be applied to single tasks only, once a playbook is completed. Note that the use of the be applied to single tasks only, once a playbook is completed. Note that the use of the
``no_log`` attribute does not prevent data from being shown when debugging Ansible itself via ``no_log`` attribute does not prevent data from being shown when debugging Ansible itself via
the :envvar:`ANSIBLE_DEBUG` environment variable. the :envvar:`ANSIBLE_DEBUG` environment variable.
@ -618,7 +627,8 @@ A steadfast rule is 'always use ``{{ }}`` except when ``when:``'.
Conditionals are always run through Jinja2 as to resolve the expression, Conditionals are always run through Jinja2 as to resolve the expression,
so ``when:``, ``failed_when:`` and ``changed_when:`` are always templated and you should avoid adding ``{{ }}``. so ``when:``, ``failed_when:`` and ``changed_when:`` are always templated and you should avoid adding ``{{ }}``.
In most other cases you should always use the brackets, even if previously you could use variables without specifying (like ``loop`` or ``with_`` clauses), as this made it hard to distinguish between an undefined variable and a string. In most other cases you should always use the brackets, even if previously you could use variables without
specifying (like ``loop`` or ``with_`` clauses), as this made it hard to distinguish between an undefined variable and a string.
Another rule is 'moustaches don't stack'. We often see this: Another rule is 'moustaches don't stack'. We often see this:
@ -641,10 +651,11 @@ For 'non host vars' you can use the :ref:`vars lookup<vars_lookup>` plugin:
.. _why_no_wheel: .. _why_no_wheel:
Why don't you ship in X format? Why don't you ship ansible in wheel format (or other packaging format) ?
+++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
In most cases it has to do with maintainability. There are many ways to ship software and we do not have the resources to release Ansible on every platform. In most cases it has to do with maintainability. There are many ways to ship software and we do not have
the resources to release Ansible on every platform.
In some cases there are technical issues. For example, our dependencies are not present on Python Wheels. In some cases there are technical issues. For example, our dependencies are not present on Python Wheels.
.. _ansible_host_delegated: .. _ansible_host_delegated:
@ -665,7 +676,8 @@ This works for all overridden connection variables, like ``ansible_user``, ``ans
How do I fix 'protocol error: filename does not match request' when fetching a file? How do I fix 'protocol error: filename does not match request' when fetching a file?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Newer releases of OpenSSH have a `bug <https://bugzilla.mindrot.org/show_bug.cgi?id=2966>`_ in the SCP client that can trigger this error on the Ansible controller when using SCP as the file transfer mechanism:: Since release ``7.9p1`` of OpenSSH there is a `bug <https://bugzilla.mindrot.org/show_bug.cgi?id=2966>`_
in the SCP client that can trigger this error on the Ansible controller when using SCP as the file transfer mechanism::
failed to transfer file to /tmp/ansible/file.txt\r\nprotocol error: filename does not match request failed to transfer file to /tmp/ansible/file.txt\r\nprotocol error: filename does not match request
@ -686,6 +698,14 @@ fails if the remote filename requires quotes to escape spaces or non-ascii chara
.. note:: If you see an ``invalid argument`` error when using ``-T``, then your SCP client is not performing filename validation and will not trigger this error. .. note:: If you see an ``invalid argument`` error when using ``-T``, then your SCP client is not performing filename validation and will not trigger this error.
.. _docs_contributions:
How do I submit a change to the documentation?
++++++++++++++++++++++++++++++++++++++++++++++
Documentation for Ansible is kept in the main project git repository, and complete instructions
for contributing can be found in the docs README `viewable on GitHub <https://github.com/ansible/ansible/blob/devel/docs/docsite/README.md>`_. Thanks!
.. _i_dont_see_my_question: .. _i_dont_see_my_question:
I don't see my question here I don't see my question here