diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index 952c2e488f7..d9e77a373c7 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -279,7 +279,7 @@ This creates a tarball of the built collection in the current directory which ca └── ... .. 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``. * 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 ``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 `My Imports `_ page. diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index aba60b87bb9..f76cbffe947 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -628,7 +628,7 @@ tests for win_stat: - 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. - :ref:`Install the required Python modules ` 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 the verbosity level using the ``-v`` argument just as you would with diff --git a/docs/docsite/rst/galaxy/dev_guide.rst b/docs/docsite/rst/galaxy/dev_guide.rst index 0dec7f28a10..62530a5dd74 100644 --- a/docs/docsite/rst/galaxy/dev_guide.rst +++ b/docs/docsite/rst/galaxy/dev_guide.rst @@ -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 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 diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst index 7971044fef7..4bc3834db00 100644 --- a/docs/docsite/rst/galaxy/user_guide.rst +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -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 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 `_ -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 -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 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 +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 +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 @@ -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: * 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. +* 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: @@ -212,7 +212,8 @@ The following provides an example of using ``--roles-path`` to install the 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 `_ 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: diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 162e0c96788..a40d219ef2e 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -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 +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 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 -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 +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 +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. -We keep paramiko as the default as if you are first installing Ansible on an EL box, it offers a better experience -for new users. +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. .. _use_ssh_jump_hosts: How do I configure a jump host to access servers that I have no direct access to? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -You can set a `ProxyCommand` in the -`ansible_ssh_common_args` inventory variable. Any arguments specified in +You can set a ``ProxyCommand`` in the +``ansible_ssh_common_args`` inventory variable. Any arguments specified in this variable are added to the sftp/scp/ssh command line when connecting 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 will append these arguments to the command line when trying to -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 -repeat global `ControlPersist` settings in `ansible_ssh_common_args`.) +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 +repeat global ``ControlPersist`` settings in ``ansible_ssh_common_args``.) -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 +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 command on the bastion host. With earlier versions of Ansible, it was necessary to configure a -suitable `ProxyCommand` for one or more hosts in `~/.ssh/config`, -or globally by setting `ssh_args` in `ansible.cfg`. +suitable ``ProxyCommand`` for one or more hosts in ``~/.ssh/config``, +or globally by setting ``ssh_args`` in ``ansible.cfg``. .. _ssh_serveraliveinterval: 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 -and run Ansible from there. +Don't try to manage a fleet of machines of a cloud provider from your laptop. +Rather connect to a management node inside this cloud provider first and run Ansible from there. .. _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 `_ 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. -Keep in mind that if you put `env` in your module shebang line (`#!/usr/bin/env `), +Keep in mind that if you put ``env`` in your module shebang line (``#!/usr/bin/env ``), this facility will be ignored so you will be at the mercy of the remote `$PATH`. .. _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. 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. @@ -195,7 +198,7 @@ need to install them into the virtualenv. There are two methods: $ 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 @@ -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 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`, :ref:`fish shell`, and :ref:`Powershell`). For - example, in the ansible config file you can set:: +* 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`, :ref:`fish shell`, + and :ref:`Powershell`). For example, in the ansible config file you can set:: 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. - To get around this limitation, download and install a later version of `python for z/OS `_ (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 `_ (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 @@ -264,7 +268,7 @@ There are a few common errors that one might run into when trying to execute Ans .. error:: 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 @@ -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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -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. 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? ++++++++++++++++++++++++ -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: +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: .. 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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -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 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: @@ -353,7 +362,8 @@ file with a list of servers. To do this, you can just access the "$groups" dicti {{ host }} {% 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 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 -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 {{ 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. 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? +++++++++++++++++++++++++++++++++ -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. @@ -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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -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 -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). Anyway, here's the trick: @@ -417,7 +428,7 @@ Anyway, here's the trick: {{ 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:: - 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? +++++++++++++++++++++++++++++++++++++++++++++++++++ -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: 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:: --- @@ -447,15 +460,18 @@ For example, to access the value of the HOME environment variable on the managem 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 - {{ 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 ` section. -There are several ways to set environment variables on your target machines. You can use the :ref:`template `, :ref:`replace `, or :ref:`lineinfile ` modules to introduce environment variables into files. -The exact files to edit vary depending on your OS and distribution and local configuration. +If you need to set environment variables for TASK execution, see :ref:`playbooks_environment` +in the :ref:`Advanced Playbooks ` section. +There are several ways to set environment variables on your target machines. You can use the +:ref:`template `, :ref:`replace `, or :ref:`lineinfile ` +modules to introduce environment variables into files. The exact files to edit vary depending on your OS +and distribution and local configuration. .. _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') }}" -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 @@ -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 -generate these passwords using Python. First, ensure that the `Passlib `_ +generate these passwords using Python. First, ensure that the `Passlib `_ password hashing library is installed: .. 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. 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): - -.. code-block:: shell-session - - encrypt +In OpenBSD, a similar option is available in the base system called ``encrypt (1)`` .. _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 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) -* disable the :ref:`inject_facts_as_vars` configuration setting to prevent fact values from colliding with variables (this will also disable the original warning) +* 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) +* 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: @@ -560,9 +575,11 @@ target machine. To mitigate this risk: Can I get training on Ansible? ++++++++++++++++++++++++++++++ -Yes! See our `services page `_ for information on our services and training offerings. Email `info@ansible.com `_ for further details. +Yes! See our `services page `_ for information on our services +and training offerings. Email `info@ansible.com `_ for further details. -We also offer free web-based training classes on a regular basis. See our `webinar page `_ for more info on upcoming webinars. +We also offer free web-based training classes on a regular basis. See our +`webinar page `_ for more info on upcoming webinars. .. _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? ++++++++++++++++++++++++++++++++++++++++++ -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 `_. Thanks! +Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`. .. _keep_secret_data: @@ -601,7 +610,7 @@ The ``no_log`` attribute can also apply to an entire play:: - hosts: all 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 ``no_log`` attribute does not prevent data from being shown when debugging Ansible itself via 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, 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: @@ -641,10 +651,11 @@ For 'non host vars' you can use the :ref:`vars lookup` plugin: .. _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. .. _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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Newer releases of OpenSSH have a `bug `_ 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 `_ +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 @@ -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. +.. _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 `_. Thanks! + .. _i_dont_see_my_question: I don't see my question here