ansible/docs/templates/config.rst.j2
Brian Coca 2ed46e04f4 more updates to plugin/config generation (#30787)
* fixed module generation

added missing lookup page
point to plugins when plugins
made modules singular
add display for verbose an debug messages
nicer templating, changed generation order for ref
corrected links
moved most of lookup docs to plugin section

* Copy edits
* Fixed typos
* Clarified wording
2017-10-11 00:15:25 -04:00

108 lines
3.3 KiB
Django/Jinja

{% set name = 'Configuration' -%}
{% set name_slug = 'config' -%}
{% set name_len = name|length + 0-%}
{{ '=' * name_len }}
{{name}}
{{ '=' * name_len }}
Ansible supports a few ways of providing configuration variables, mainly through environment variables, command line switches and an ini file `ansible.cfg`.
Starting at Ansible 2.4 the `ansible-config` utility allows users to see all the configuration settings available, their defaults, how to set them and
where their current value comes from. See :doc:ansible-config for more information.
The configuration file
======================
Changes can be made and used in a configuration file which will be searched for in the following order:
* ANSIBLE_CONFIG (environment variable if set)
* ansible.cfg (in the current directory)
* ~/.ansible.cfg (in the home directory)
* /etc/ansible/ansible.cfg
Ansible will process the above list and use the first file found, all others are ignored.
.. note:: Comments
The configuration file is one variant of an INI format.
Both the hash sign ("#") and semicolon (";") are allowed as
comment markers when the comment starts the line.
However, if the comment is inline with regular values,
only the semicolon is allowed to introduce the comment.
For instance::
# some basic default values...
inventory = /etc/ansible/hosts ; This points to the file that lists your hosts
Common Options
==============
This is a copy of the options available from our release, your local install might have extra options due to additional plugins,
you can use the command line utility mentioned above (`ansible-config`) to browse through those.
{% if config_options %}
{% for config_option in config_options|sort %}
{% set config_len = config_option|length -%}
{% set config = config_options[config_option] %}
.. _{{config_option}}:
{{config_option}}
{{ '-' * config_len }}
{% if config['description'] and config['description'] != [''] %}
{% if config['description'] != ['TODO: write it'] %}
:Description: {{' '.join(config['description'])}}
{% endif %}
{% endif %}
{% if config['type'] %}
:Type: {{config['type']}}
{% endif %}
:Default: {{config['default']}}
{% if config['version_added'] %}
:Version Added: {{config['version_added']}}
{% endif %}
{% for ini_map in config['ini']|sort %}
:Ini Section: {{ini_map['section']}}
:Ini Key: {{ini_map['key']}}
{% endfor %}
{% for env_var_map in config['env']|sort %}
:Environment: :envvar:`{{env_var_map['name']}}`
{% endfor %}
{% if config['deprecated'] %}
:Deprecated in: {{config['deprecated']['version']}}
:Deprecated detail: {{config['deprecated']['why']}}
:Deprecated alternatives: {{config['deprecated']['alternatives']}}
{% endif %}
{% endfor %}
Environment Variables
=====================
.. envvar:: ANSIBLE_CONFIG
Override the default ansible config file
{% for config_option in config_options %}
{% for env_var_map in config_options[config_option]['env'] %}
.. envvar:: {{env_var_map['name']}}
{% if config_options[config_option]['description'] and config_options[config_option]['description'] != [''] %}
{% if config_options[config_option]['description'] != ['TODO: write it'] %}
{{ ''.join(config_options[config_option]['description']) }}
{% endif %}
{% endif %}
See also :ref:`{{config_option}} <{{config_option}}>`
{% endfor %}
{% endfor %}
{% endif %}