diff --git a/.gitignore b/.gitignore index b4319de00b..d419a26f34 100644 --- a/.gitignore +++ b/.gitignore @@ -27,28 +27,30 @@ docs/man/man3/* *.sublime-project *.sublime-workspace # docsite stuff... +docs/api/_build/ +docs/api/rst/ +docs/docsite/*.html +docs/docsite/_build +docs/docsite/_static/*.gif +docs/docsite/_static/*.png +docs/docsite/_static/websupport.js +docs/docsite/htmlout +docs/docsite/searchindex.js +docs/docsite/rst_warnings +docs/docsite/rst/*_module.rst +docs/docsite/rst/ansible.rst +docs/docsite/rst/ansible-*.rst docs/docsite/rst/community_maintained.rst docs/docsite/rst/config.rst docs/docsite/rst/core_maintained.rst docs/docsite/rst/list_of_*.rst -docs/docsite/rst/*_module.rst docs/docsite/rst/modules_by_category.rst -docs/docsite/rst/plugins_by_category.rst docs/docsite/rst/network_maintained.rst +docs/docsite/rst/plugins_by_category.rst docs/docsite/rst/partner_maintained.rst docs/docsite/rst/playbook_keywords.rst docs/docsite/rst/playbooks_directives.rst -docs/docsite/rst/plugins/ -docs/docsite/*.html -docs/docsite/_static/*.gif -docs/docsite/_static/*.png -docs/docsite/_static/websupport.js -docs/docsite/searchindex.js -docs/docsite/htmlout -docs/docsite/_build -docs/docsite/rst_warnings -docs/api/rst/ -docs/api/_build/ +docs/docsite/rst/plugins/*/*.rst # deb building stuff... /debian/ deb-build diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index 5286a3aa28..b8138c560b 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -179,7 +179,7 @@ def get_module_info(module_dir, limit_to_modules=None, verbose=False): # Do not list blacklisted modules module = os.path.splitext(os.path.basename(module_path))[0] - if module in plugin_docs.BLACKLIST['MODULE']: + if module in plugin_docs.BLACKLIST['MODULE'] or module == 'base': continue # If requested, limit module documentation building only to passed-in @@ -309,8 +309,7 @@ def too_old(added): return added_float < TO_OLD_TO_BE_NOTABLE -def process_modules(module_map, templates, outputname, - output_dir, ansible_version, plugin_type): +def process_modules(module_map, templates, outputname, output_dir, ansible_version, plugin_type): for module in module_map: # print("rendering: %s" % module) @@ -574,21 +573,23 @@ def main(): validate_options(options) plugin_type = options.plugin_type - templates = jinja2_environment(options.template_dir, options.type, - plugin_type) - # for plugins, just use the short name 'ssh.rst' vs 'ssh_module.rst' - outputname = '%s.rst' - # trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst' if plugin_type == 'modules': + templates = jinja2_environment(options.template_dir, options.type, plugin_type) + output_dir = options.output_dir + # trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst' outputname = '%s_' + '%s.rst' % plugin_type[:-1] + else: + templates = jinja2_environment(options.template_dir, options.type, 'plugins') + # for plugins, just use 'ssh.rst' vs 'ssh_module.rst' + outputname = '%s.rst' + output_dir = '%s/plugins/%s' % (options.output_dir, plugin_type) # Convert passed-in limit_to_modules to None or list of modules. if options.limit_to_modules is not None: options.limit_to_modules = [s.lower() for s in options.limit_to_modules.split(",")] - mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules, - verbose=options.verbose) + mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules, verbose=options.verbose) categories['all'] = {'_modules': mod_info.keys()} @@ -606,22 +607,22 @@ def main(): short_desc = '' record['doc']['short_description'] = rst_ify(short_desc) - # Write master category list - category_list_text = templates['category_list'].render(categories=sorted(categories.keys())) - category_index_name = '%s_by_category.rst' % plugin_type - write_data(category_list_text, options.output_dir, category_index_name) + if plugin_type == 'module': + # Write master category list + category_list_text = templates['category_list'].render(categories=sorted(categories.keys())) + category_index_name = '%s_by_category.rst' % plugin_type + write_data(category_list_text, output_dir, category_index_name) # Render all the individual module pages - process_modules(mod_info, templates, outputname, - options.output_dir, options.ansible_version, plugin_type) + process_modules(mod_info, templates, outputname, output_dir, options.ansible_version, plugin_type) # Render all the categories for modules - category_list_name_template = 'list_of_%s_' + '%s.rst' % plugin_type - process_categories(mod_info, categories, templates, options.output_dir, - category_list_name_template, plugin_type) + if plugin_type == 'module': + category_list_name_template = 'list_of_%s_' + '%s.rst' % plugin_type + process_categories(mod_info, categories, templates, output_dir, category_list_name_template, plugin_type) - # Render all the categories for modules - process_support_levels(mod_info, templates, options.output_dir, plugin_type) + # Render all the categories for modules + process_support_levels(mod_info, templates, output_dir, plugin_type) if __name__ == '__main__': diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index e785379459..eed766e45c 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -21,6 +21,8 @@ ifdef PLUGINS PLUGIN_ARGS = -l $(PLUGINS) endif +DOC_PLUGINS ?= cache callback connection inventory lookup strategy vars + assertrst: ifndef rst $(error specify document or pattern with rst=somefile.rst) @@ -59,10 +61,11 @@ clean: -rm rst/*_by_category.rst -rm rst/*_module.rst -rm rst/*_plugin.rst - -rm -rf rst/plugins/* -rm rst/*_maintained.rst -rm rst/playbooks_directives.rst -rm rst/playbooks_keywords.rst + -rm rst/plugins/*/*.rst + -rm rst/config.rst -rm rst/ansible-*.rst -rm rst/ansible.rst @@ -82,7 +85,11 @@ modules: $(FORMATTER) ../templates/plugin.rst.j2 PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ $(MODULE_ARGS) plugins: $(FORMATTER) ../templates/plugin.rst.j2 - PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type plugins --template-dir=../templates --module-dir=../../lib/ansible/plugins -o rst/ $(PLUGIN_ARGS) + @echo "looping over doc plugins" + for plugin in $(DOC_PLUGINS); \ + do \ + PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst/ $(PLUGIN_ARGS); \ + done testing: $(TESTING_FORMATTER) diff --git a/docs/docsite/rst/command_line_tools.rst b/docs/docsite/rst/command_line_tools.rst index 80c8df5bff..460ace1228 100644 --- a/docs/docsite/rst/command_line_tools.rst +++ b/docs/docsite/rst/command_line_tools.rst @@ -1,15 +1,11 @@ Command Line Tools ================== +Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides. +Below you have the complate list, each page has the detailed swtiches and options that each tool supports and a short description of their purpose. .. toctree:: :maxdepth: 1 + :glob: ansible - ansible-playbook - ansible-vault - ansible-galaxy - ansible-console - ansible-config - ansible-doc - ansible-inventory - ansible-pull + ansible-* diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index f72ce7f497..9457a29df3 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -4,99 +4,107 @@ Developing Plugins .. contents:: Topics Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own. - -The following types of plugins are available: - -- *Action* plugins are front ends to modules and can execute actions on the controller before calling the modules themselves. -- *Cache* plugins are used to keep a cache of 'facts' to avoid costly fact-gathering operations. -- *Callback* plugins enable you to hook into Ansible events for display or logging purposes. -- *Connection* plugins define how to communicate with inventory hosts. -- *Filters* plugins allow you to manipulate data inside Ansible plays and/or templates. This is a Jinja2 feature; Ansible ships extra filter plugins. -- *Lookup* plugins are used to pull data from an external source. These are implemented using a custom Jinja2 function. -- *Strategy* plugins control the flow of a play and execution logic. -- *Shell* plugins deal with low-level commands and formatting for the different shells Ansible can encounter on remote hosts. -- *Test* plugins allow you to validate data inside Ansible plays and/or templates. This is a Jinja2 feature; Ansible ships extra test plugins. -- *Vars* plugins inject additional variable data into Ansible runs that did not come from an inventory, playbook, or the command line. - This section describes the various types of plugins and how to implement them. +.. _plugin_guidelines: + +General Guidelines +------------------ + +Some things that should apply to any type of plugin you develop. + +Raising Errors +`````````````` + +In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error. +When wrapping other exceptions into error messages you should always use the `to_text` Ansible function to ensure proper string compatiblity across +Python versions: + +.. code-block:: python + + from ansible.module_utils._text import to_native + + try: + cause_an_exeption() + except Exception as e: + AnsibleError('Something happend, this was original exception: %s' % to_native(e)) + +Check the different AnsibleError objects and see which one applies the best to your situation. + +String encoding +``````````````` +Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type +because the strings will be run through jinja2. To do this, you can use: + +.. code-block:: python + + from ansible.module_utils._text import to_text + result_string = to_text(result_string) + +Plugin configuration +```````````````````` + +Starting in 2.4 and going forward, we are unifying how each plugin type is configured and how they get those settings, plugins will be able to 'declare' +their needs and have Ansible provide them with the 'resolved' configuration. As of 2.4 both Callback and Connection type plugins can use this system, +most plugins will be able to use `self._options[]` to access the settings, except callbacks that due to prexisting collsion +use `self._plugin_optoins[]`. + +Plugins that supprot docs (see `ansible-doc` for the list) are now required to provide documentation to be considered for merge into the Ansible repo. + +Also be aware that if you inherit from a plugin you must ALSO document the optoins it takes, either via a documentation fragment or as a copy. .. _developing_callbacks: Callback Plugins ---------------- -Callback plugins enable adding new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs. +See :doc: plugins/callback as to what they are and how to use them. This section explains how to use them. -.. _callback_examples: - -Example Callback Plugins -++++++++++++++++++++++++ - -Ansible comes with a number of callback plugins that you can look at for examples. These can be found in `lib/ansible/plugins/callback `_. - -The `log_plays -`_ -callback is an example of how to intercept playbook events to a log -file, and the `mail -`_ -callback sends email when playbooks complete. - -The `osx_say -`_ -callback provided is particularly entertaining -- it will respond with -computer synthesized speech on OS X in relation to playbook events, -and is guaranteed to entertain and/or annoy coworkers. - -.. _configuring_callbacks: - -Configuring Callback Plugins -++++++++++++++++++++++++++++ - -You can activate a custom callback by either dropping it into a callback_plugins directory adjacent to your play or inside a role or by putting it in one of the callback directory sources configured in `ansible.cfg`. - -Plugins are loaded in alphanumeric order; for example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`. - -Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your `ansible.cfg` file in order to function. For example:: - - #callback_whitelist = timer, mail, mycallbackplugin - - -Managing stdout -``````````````` - -You can only have one plugin be the main manager of your console output. If you want to replace the default, you should define CALLBACK_TYPE = stdout in the subclass and then configure the stdout plugin in `ansible.cfg`. For example:: - - #stdout_callback = mycallbackplugin - - - -.. _callback_development: - -Developing Callback Plugins -+++++++++++++++++++++++++++ Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent: .. code-block:: python from ansible.plugins.callback import CallbackBase - from ansible import constants as C class CallbackModule(CallbackBase): pass -From there, override the specific methods from the CallbackBase that you want to provide a callback for. For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with `v2`. For a complete list of methods that you can override, please see ``__init__.py`` in the `lib/ansible/plugins/callback `_ directory. +From there, override the specific methods from the CallbackBase that you want to provide a callback for. +For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with `v2`. +For a complete list of methods that you can override, please see ``__init__.py`` in the +`lib/ansible/plugins/callback `_ directory. -The following example shows how Ansible's timer plugin is implemented: +The following example shows a modified example Ansible's timer plugin is implemented, +but with an extra option so you can see how configuration works in Ansible >= 2.4: .. code-block:: python - # Make coding more python3-ish + # Make coding more python3-ish, this is required for contributions to Ansible from __future__ import (absolute_import, division, print_function) __metaclass__ = type + # not only visible to ansible-doc, it also 'declares' the options the plugin requires and how to configure them. + DOCUMENTATION = ''' + callback: timer + callback_type: aggregate + requirements: + - whitelist in configuration + short_description: Adds time to play stats + version_added: "2.0" + description: + - This callback just adds total play duration to the play stats. + options: + format_string: + description: format of the string shown to user at play end + ini: + - section: callback_timer + key: format_string + env: + - name: ANSIBLE_CALLBACK_TIMER_FORMAT + default: "Playbook run took %s days, %s hours, %s minutes, %s seconds" + ''' from datetime import datetime from ansible.plugins.callback import CallbackBase @@ -109,28 +117,35 @@ The following example shows how Ansible's timer plugin is implemented: CALLBACK_VERSION = 2.0 CALLBACK_TYPE = 'aggregate' CALLBACK_NAME = 'timer' + + # only needed if you ship it and dont want to enable by default CALLBACK_NEEDS_WHITELIST = True def __init__(self): + # make sure the expected objects are present, calling the base's __init__ super(CallbackModule, self).__init__() + # start the timer when the plugin is loaded, the first play should start a few miliseconds after. self.start_time = datetime.now() - def days_hours_minutes_seconds(self, runtime): + def _days_hours_minutes_seconds(self, runtime): + ''' internal helper method for this callback ''' minutes = (runtime.seconds // 60) % 60 r_seconds = runtime.seconds - (minutes * 60) return runtime.days, runtime.seconds // 3600, minutes, r_seconds - def playbook_on_stats(self, stats): - self.v2_playbook_on_stats(stats) - + # this is only event we care about for display, when the play shows it's summary stats, the rest are ignored by the base class def v2_playbook_on_stats(self, stats): end_time = datetime.now() runtime = end_time - self.start_time - self._display.display("Playbook run took %s days, %s hours, %s minutes, %s seconds" % (self.days_hours_minutes_seconds(runtime))) + + # Shows the usage of a config option declared in the DOCUMENTATION variable, Ansible will have set it when it loads the plugin. + # Also note the use of the display object to print to screen, available to all callbacks, you should prefer this over printing yoruself + self._display.display(self._plugin_options['format_string'] % (self._days_hours_minutes_seconds(runtime))) Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible >=2.0. +CALLBACK_TYPE is mostly needed to distinguish 'stout' plugins from the rest, as you can only load one of that type. .. _developing_connection_plugins: @@ -142,7 +157,45 @@ are covered in the :doc:`../intro_getting_started` section. Should you want to directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses 'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 and later. Previous versions did not support 'smart'. -More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connection `_ and figure things out pretty easily. +More documentation on writing connection plugins is pending, though you can jump into +`lib/ansible/plugins/connection `_ and figure things out pretty easily. + +.. _developing_inventory_plugins: + +Inventory Plugins +----------------- + +Added in Ansible 2.4 they are in charge of parsing inventory sources and forming the 'in memory' representation of the Inventory. + +They are invoked via the InventoryManager and are given access to any existing inventory data added previouslly, +they are given an 'inventory source' as supplied to Ansible (via config/optoins/defaults/etc), which they can ignore +(return false from the `verify_file` method), or attempt to parse (via `parse` method) and return an `AnsibleParserError` on failure. + +.. code-block:: python + + def parse(self, inventory, loader, path, cache=True): + pass # your code goes here + +The parameters are: + + * inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory + * loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh. + * path: string with inventory source (normally a path, but not required) + * cache: hint to the plugin if it should use or avoid caches (Cache plugin and/or loader) + +Inventory sources are strings, most of the time they correspond to a file path, but can also be a comma separated list, +a uri or anything your plugin can use as input. +The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins), +a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those) which is how 'inventory scripts' work. + +Inventory plugins can also use the configured Cache plugin to store and retrieve data to avoid costly external calls, +of course this only works if using a 'persistent' cache (i.e not the memory one). + +Be aware that inventory plugins normally only execute at the start of the run, before playbooks/plays and roles are found, +but they can be 're-executed' via the `meta: refresh_inventory` task, which will clear out the existing inventory and rebuild it. + +More documentation on writing inventory plugins is pending, though you can jump into +`lib/ansible/plugins/inventory `_ and figure things out pretty easily. .. _developing_lookup_plugins: @@ -155,6 +208,25 @@ Here's a simple lookup plugin implementation - this lookup returns the contents .. code-block:: python + # python 3ish headers, required if submitting to Ansible + from __future__ import (absolute_import, division, print_function) + __metaclass__ = type + + DOCUMENTATION = """ + lookup: file + author: Daniel Hokka Zakrisson + version_added: "0.9" + short_description: read file contents + description: + - This lookup returns the contents from a file on the Ansible controller's file system. + options: + _terms: + description: path(s) of files to read + required: True + notes: + - if read in variable context, the file can be interpreted as YAML if the content is valid to the parser. + - this lookup does not understand 'globing', use the fileglob lookup instead. + """ from ansible.errors import AnsibleError, AnsibleParserError from ansible.plugins.lookup import LookupBase @@ -169,19 +241,28 @@ Here's a simple lookup plugin implementation - this lookup returns the contents def run(self, terms, variables=None, **kwargs): - ret = [] + # lookups in general are expected to both take a list as input and output a list + # this is done so they work with the looping construct `with_`. + ret = [] for term in terms: display.debug("File lookup term: %s" % term) - # Find the file in the expected search path + # Find the file in the expected search path, using a class method + # that implements the 'expected' search path for Ansible plugins. lookupfile = self.find_file_in_search_path(variables, 'files', term) + + # Don't use print or your own logging, the display class + # takes care of it in a unified way. display.vvvv(u"File lookup using %s as file" % lookupfile) try: if lookupfile: contents, show_data = self._loader._get_file_contents(lookupfile) ret.append(contents.rstrip()) else: + # Always use ansible error classes to throw 'final' exceptions, + # so the Ansible engine will know how to deal with them. + # The Parser error indicates invalid options passed raise AnsibleParserError() except AnsibleParserError: raise AnsibleError("could not locate file in lookup: %s" % term) @@ -199,13 +280,6 @@ An example of how this lookup is called:: - debug: msg="the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}" -Errors encountered during execution should be returned by raising AnsibleError() with a message describing the error. Any strings returned by your lookup plugin implementation that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2. To do this, you can use: - -.. code-block:: python - - from ansible.module_utils._text import to_text - result_string = to_text(result_string) - For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup `_. For usage examples of lookup plugins, see `Using Lookups `_. @@ -215,14 +289,42 @@ For usage examples of lookup plugins, see `Using Lookups `_ and figure -things out pretty easily. +Vars plugins got rewritten in 2.4 and had been semi-functional since 2.0. + +Older pugins used a `run` method as their main body/work: + +.. code-block:: python + + def run(self, name, vault_password=None): + pass # your code goes here + + +But Ansible 2.0 did not pass passwords to them so vaults were unavilable. +Most of the work now happens in the `get_vars` method which is called from the VariableManager when needed. + +.. code-block:: python + + def get_vars(self, loader, path, entities): + pass # your code goes here + +The parameters are: + + * loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh. + * path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data + in reference to them, `get_vars` will be called at least once per available path. + * entities: these are host or group names that are pertinent to the variables needed, the plugin will get called once for hosts and again for groups. + +This method just needs to return a dictionary structure with the pertinent variables. + +Since Ansible 2.4, vars plugins execute as needed when preparing to execute a task, this avoids the costly 'always execute' that used +to happend during inventory construction. + +More documentation on writing vars plugins is pending, though you can jump into +`lib/ansible/plugins/vars `_ and figure things out pretty easily. -If you find yourself wanting to write a vars_plugin, it's more likely you should write an inventory script instead. .. _developing_filter_plugins: @@ -255,11 +357,14 @@ Plugins are automatically loaded when you have one of the following subfolders a * lookup_plugins * callback_plugins * connection_plugins + * inventory_plugins * filter_plugins * strategy_plugins * cache_plugins * test_plugins * shell_plugins + * vars_plugins + When shipped as part of a role, the plugin will be available as soon as the role is called in the play. diff --git a/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst b/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst index b586d0b7a4..6e0a10306a 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst @@ -1,4 +1,4 @@ Sanity Tests » ansible-var-precedence-check =========================================== -Check the order of precedence for Ansible variables against :ref:`variable_precedence`. +Check the order of precedence for Ansible variables against :ref:`ansible_variable_precedence`. diff --git a/docs/docsite/rst/intro_configuration.rst b/docs/docsite/rst/intro_configuration.rst index 5ac1c23667..3ebab72902 100644 --- a/docs/docsite/rst/intro_configuration.rst +++ b/docs/docsite/rst/intro_configuration.rst @@ -1,37 +1,19 @@ -Configuration file -++++++++++++++++++ +Configuration +------------- .. contents:: Topics -Certain settings in Ansible are adjustable via a configuration file. The stock configuration should be sufficient -for most users, but there may be reasons you would want to change them. +There are several ways to control Ansible settings, this is a brief descriptoin of them. -Changes can be made and used in a configuration file which will be processed in the following order:: - * ANSIBLE_CONFIG (an environment variable) - * ansible.cfg (in the current directory) - * .ansible.cfg (in the home directory) - * /etc/ansible/ansible.cfg +.. _the_configuration_file: -Prior to 1.5 the order was:: +Configuration file +++++++++++++++++++ - * ansible.cfg (in the current directory) - * ANSIBLE_CONFIG (an environment variable) - * .ansible.cfg (in the home directory) - * /etc/ansible/ansible.cfg - -Ansible will process the above list and use the first file found. Settings in files are not merged. - -.. 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 +Certain settings in Ansible are adjustable via a configuration file (ansible.cfg). +The stock configuration should be sufficient for most users, but there may be reasons you would want to change them. .. _getting_the_latest_configuration: @@ -44,1203 +26,46 @@ as a ".rpmnew" file (or other) as appropriate in the case of updates. If you have installed from pip or from source, however, you may want to create this file in order to override default settings in Ansible. -You may wish to consult the `ansible.cfg in source control `_ for all of the possible latest values. +An example file is availble `ansible.cfg in source control `_ + +For more details and a full listing of available configurations go to :doc:configuration or (starting at Ansible 2.4) +you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values. + +For in depth details you check out :doc:`config`. -.. _environmental_configuration: Environmental configuration -``````````````````````````` ++++++++++++++++++++++++++++ -Ansible also allows configuration of settings via environment variables. If -these environment variables are set, they will override any setting loaded -from the configuration file. These variables are defined in `constants.py `_. +Ansible also allows configuration of settings via environment variables. +If these environment variables are set, they will override any setting loaded from the configuration file. -.. _config_values_by_section: +You can get a full listing of available variables from :doc:`config`. -Explanation of values by section -```````````````````````````````` +.. _command_line_configuration: -The configuration file is broken up into sections. Most options are in the "general" section but some sections of the file -are specific to certain connection types. +Command line options +++++++++++++++++++++ -.. _general_defaults: +Not all configuration options are present in the command line, just the ones deemed most useful or common. +Settings in the command line will override those passed through the configuration file and the environment. -General defaults ----------------- +The full list of options available is in :doc:`ansible-playbook` and :doc:`ansible`. -In the [defaults] section of ansible.cfg, the following settings are tunable: +.. seealso:: -.. _cfg_action_plugins: - -action_plugins -============== - -Actions are pieces of code in ansible that enable things like module execution, templating, and so forth. - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - action_plugins = ~/.ansible/plugins/action_plugins/:/usr/share/ansible_plugins/action_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details. - - -.. _allow_unsafe_lookups: - -allow_unsafe_lookups -==================== - -.. versionadded:: 2.2.3, 2.3.1 - -When enabled, this option allows lookup plugins (whether used in variables as `{{lookup('foo')}}` or as a loop as `with_foo`) to return data that is **not** marked "unsafe". By default, such data is marked as unsafe to prevent the templating engine from evaluating any jinja2 templating language, as this could represent a security risk. - -This option is provided to allow for backwards-compatibility, however users should first consider adding `allow_unsafe=True` to any lookups which may be expected to contain data which may be run through the templating engine later. For example:: - - {{lookup('pipe', '/path/to/some/command', allow_unsafe=True)}} - - -.. _allow_world_readable_tmpfiles: - -allow_world_readable_tmpfiles -============================= - -.. versionadded:: 2.1 - -This makes the temporary files created on the machine to be world readable and will issue a warning instead of failing the task. - -It is useful when becoming an unprivileged user:: - - allow_world_readable_tmpfiles=True - - - - -.. _ansible_managed: - -ansible_managed -=============== - -The ``ansible_managed`` string can be inserted into files written by -Ansible's config templating system:: - - {{ ansible_managed }} - -The default value indicates that Ansible is managing a file:: - - ansible_managed = Ansible managed - -This string can be helpful to indicate that a file should not -be directly edited because Ansible may overwrite the contents of the file. - -There are several special placeholder values that can be placed in the ``ansible_managed`` string. These are not in the default ``ansible_managed`` string because they can cause Ansible to behave as though the -entire template has changed when only the ansible_managed string has -changed. - -These placeholder values, along with the situations which can lead Ansible to -report a template as changed when they are used, are listed below: - -* Standard directives that can be used with :func:~time.strftime:. - The time referred to is the modification time of the template file. Many - revision control systems timestamp files according to when they are checked - out, not the last time the file was modified. That means Ansible will think - the file has been modified anytime there is a fresh checkout. - -.. If intersphinx isn't turned on, manually make strftime link to - https://docs.python.org/2/library/time.html#time.strftime - -* ``{file}``: expands to the name of the full path to the template file. If - Ansible is run with multiple checkouts of the same configuration repository - (for instance, in each sysadmin's home directory), then the path will differ - in each checkout causing Ansible to behave as though the file has been modified. -* ``{host}``: expands to the hostname of the machine :program:`ansible` is run - on. If :program:`ansible` is invoked on multiple machines (for instance, - each sysadmin can checkout the configuration repository on their workstation - and run :program:`ansible` there), then the host will vary on each of these - machines. This will cause Ansible to behave as though the file has been modified. -* ``{uid}``: expands to the owner of the template file. If Ansible is run - on checkouts of the configuration repository made by separate users (for - instance, if multiple system administrators are making checkouts of the - repository with their own accounts) then this will cause Ansible to behave as if - the file has been modified. - -.. _ask_pass: - -ask_pass -======== - -This controls whether an Ansible playbook should prompt for a password by default. The default behavior is no:: - - ask_pass = True - -If using SSH keys for authentication, it's probably not needed to change this setting. - -.. _ask_sudo_pass: - -ask_sudo_pass -============= - -Similar to ask_pass, this controls whether an Ansible playbook should prompt for a sudo password by default when -sudoing. The default behavior is also no:: - - ask_sudo_pass = True - -Users on platforms where sudo passwords are enabled should consider changing this setting. - -.. _ask_vault_pass: - -ask_vault_pass -============== - -This controls whether an Ansible playbook should prompt for the vault password by default. The default behavior is no:: - - ask_vault_pass = True - -.. _bin_ansible_callbacks: - -bin_ansible_callbacks -===================== - -.. versionadded:: 1.8 - -Controls whether callback plugins are loaded when running /usr/bin/ansible. This may be used to log activity from -the command line, send notifications, and so on. Callback plugins are always loaded for /usr/bin/ansible-playbook -if present and cannot be disabled:: - - bin_ansible_callbacks = False - -Prior to 1.8, callbacks were never loaded for /usr/bin/ansible. - -.. _callback_plugins: - -callback_plugins -================ - -Callbacks are pieces of code in ansible that get called on specific events, permitting to trigger notifications. - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - callback_plugins = ~/.ansible/plugins/callback:/usr/share/ansible/plugins/callback - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - -.. _callback_whitelist: - -callback_whitelist -================== - -.. versionadded:: 2.0 - -Now ansible ships with all included callback plugins ready to use but they are disabled by default. -This setting lets you enable a list of additional callbacks. This cannot change or override the -default stdout callback, use :ref:`stdout_callback` for that:: - - callback_whitelist = timer,mail - -.. _command_warnings: - -command_warnings -================ - -.. versionadded:: 1.8 - -By default since Ansible 1.8, Ansible will issue a warning when the shell or -command module is used and the command appears to be similar to an existing -Ansible module. For example, this can include reminders to use the 'git' module -instead of shell commands to execute 'git'. Using modules when possible over -arbitrary shell commands can lead to more reliable and consistent playbook runs, -and also easier to maintain playbooks:: - - command_warnings = False - -These warnings can be silenced by adjusting the following -setting or adding warn=yes or warn=no to the end of the command line -parameter string, like so:: - - - - name: usage of git that could be replaced with the git module - shell: git update foo warn=yes - -.. _connection_plugins: - -connection_plugins -================== - -Connections plugin permit to extend the channel used by ansible to transport commands and files. - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - connection_plugins = ~/.ansible/plugins/connection_plugins/:/usr/share/ansible_plugins/connection_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - -.. _deprecation_warnings: - -deprecation_warnings -==================== - -.. versionadded:: 1.3 - -Allows disabling of deprecating warnings in ansible-playbook output:: - - deprecation_warnings = True - -Deprecation warnings indicate usage of legacy features that are slated for removal in a future release of Ansible. - -.. _display_args_to_stdout: - -display_args_to_stdout -====================== - -.. versionadded:: 2.1.0 - -By default, ansible-playbook will print a header for each task that is run to -stdout. These headers will contain the ``name:`` field from the task if you -specified one. If you didn't then ansible-playbook uses the task's action to -help you tell which task is presently running. Sometimes you run many of the -same action and so you want more information about the task to differentiate -it from others of the same action. If you set this variable to ``True`` in -the config then ansible-playbook will also include the task's arguments in the -header. - -This setting defaults to ``False`` because there is a chance that you have -sensitive values in your parameters and do not want those to be printed to -stdout:: - - display_args_to_stdout = False - -If you set this to ``True`` you should be sure that you have secured your -environment's stdout (no one can shoulder surf your screen and you aren't -saving stdout to an insecure file) or made sure that all of your playbooks -explicitly added the ``no_log: True`` parameter to tasks which have sensistive -values See :ref:`keep_secret_data` for more information. - -.. _display_skipped_hosts: - -display_skipped_hosts -===================== - -If set to `False`, ansible will not display any status for a task that is skipped. The default behavior is to display skipped tasks:: - - display_skipped_hosts = True - -Note that Ansible will always show the task header for any task, regardless of whether or not the task is skipped. - -.. _error_on_undefined_vars: - -error_on_undefined_vars -======================= - -On by default since Ansible 1.3, this causes ansible to fail steps that reference variable names that are likely -typoed:: - - error_on_undefined_vars = True - -If set to False, any '{{ template_expression }}' that contains undefined variables will be rendered in a template -or ansible action line exactly as written. - -.. _executable: - -executable -========== - -This indicates the command to use to spawn a shell under a sudo environment. Users may need to change this to /bin/bash in rare instances when sudo is constrained, but in most cases it may be left as is:: - - executable = /bin/bash - -Starting in version 2.1 this can be overridden by the inventory var ``ansible_shell_executable``. - -.. _filter_plugins: - -filter_plugins -============== - -Filters are specific functions that can be used to extend the template system. - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - filter_plugins = ~/.ansible/plugins/filter_plugins/:/usr/share/ansible_plugins/filter_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - -.. _force_color: - -force_color -=========== - -This options forces color mode even when running without a TTY:: - - force_color = 1 - -.. _force_handlers: - -force_handlers -============== - -.. versionadded:: 1.9.1 - -This option causes notified handlers to run on a host even if a failure occurs on that host:: - - force_handlers = True - -The default is False, meaning that handlers will not run if a failure has occurred on a host. -This can also be set per play or on the command line. See :ref:`handlers_and_failure` for more details. - -.. _forks: - -forks -===== - -This is the default number of parallel processes to spawn when communicating with remote hosts. Since Ansible 1.3, -the fork number is automatically limited to the number of possible hosts at runtime, so this is really a limit of how much -network and CPU load you think you can handle. Many users may set this to 50, some set it to 500 or more. If you -have a large number of hosts, higher values will make actions across all of those hosts complete faster. The default -is very very conservative:: - - forks = 5 - -.. _fact_caching: - -fact_caching -============ - -This option allows you to configure fact caching. When a fact cache -is enabled and there is valid data for a host, Ansible will use that rather than running an implicit ``setup`` job on a remote host. - -The value of this option should be the name of a cache plugin. -Current versions of Ansible include ``redis`` and ``jsonfile``:: - - fact_caching = jsonfile - -.. _fact_caching_connection: - -fact_caching_connection -======================= - -This option tells Ansible where to cache facts. The value is plugin -dependent. For the ``jsonfile`` plugin, it should be a path to a -local directory. For the ``redis`` plugin, the value is a -``host:port:database`` triplet:: - - fact_caching_connection = localhost:6379:0 - -.. _fact_caching_timeout: - -fact_caching_timeout -==================== - -This option tells Ansible when to expire values from the cache. -Setting this value to 0 effectively disables expiry, and a positive -value is a TTL in seconds:: - - fact_caching_timeout = 86400 - -.. _fact_path: - -fact_path -========= - -This option allows you to globally configure a custom path for :ref:`local_facts` for the implied `setup` task when using implied fact gathering. - - fact_path = /home/centos/ansible_facts.d - -The default is to use the default from the `setup module `_: ``/etc/ansible/facts.d`` -This ONLY affects fact gathering triggered by a play when `gather_facts: True`. - -.. _gathering: - -gathering -========= - -New in 1.6, the 'gathering' setting controls the default policy of facts gathering (variables discovered about remote systems). - -The value 'implicit' is the default, which means that the fact cache will be ignored and facts will be gathered per play unless 'gather_facts: False' is set. -The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play. -The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run. -This option can be useful for those wishing to save fact gathering time. Both 'smart' and 'explicit' will use the fact cache:: - - gathering = smart - -.. versionadded:: 2.1 - -You can specify a subset of gathered facts, via the play's gather_facts directive, using the following option:: - - gather_subset = all - -:all: gather all subsets (the default) -:network: gather network facts -:hardware: gather hardware facts (longest facts to retrieve) -:virtual: gather facts about virtual machines hosted on the machine -:ohai: gather facts from ohai -:facter: gather facts from facter - -You can combine them using a comma separated list (ex: network,virtual,facter) - -You can also disable specific subsets by prepending with a `!` like this:: - - # Don't gather hardware facts, facts from chef's ohai or puppet's facter - gather_subset = !hardware,!ohai,!facter - -A set of basic facts are always collected no matter which additional subsets -are selected. If you want to collect the minimal amount of facts, use -`!all`:: - - gather_subset = !all - -hash_behaviour -============== - -Ansible by default will override variables in specific precedence orders, as described in :doc:`playbooks_variables`. When a variable -of higher precedence wins, it will replace the other value. - -Some users prefer that variables that are hashes (aka 'dictionaries' in Python terms) are merged. This setting is called 'merge'. This is not the default behavior and it does not affect variables whose values are scalars (integers, strings) or -arrays. We generally recommend not using this setting unless you think you have an absolute need for it, and playbooks in the -official examples repos do not use this setting:: - - hash_behaviour = replace - -The valid values are either 'replace' (the default) or 'merge'. - -.. versionadded:: 2.0 - -If you want to merge hashes without changing the global settings, use -the `combine` filter described in :doc:`playbooks_filters`. - -.. _hostfile: - -hostfile -======== - -This is a deprecated setting since 1.9, please look at :ref:`inventory_file` for the new setting. - -.. _host_key_checking: - -host_key_checking -================= - -As described in :doc:`intro_getting_started`, host key checking is on by default in Ansible 1.3 and later. If you understand the -implications and wish to disable it, you may do so here by setting the value to False:: - - host_key_checking = True - -.. _internal_poll_interval: - -internal_poll_interval -====================== - -.. versionadded:: 2.2 - -This sets the interval (in seconds) of Ansible internal processes polling each other. -Lower values improve performance with large playbooks at the expense of extra CPU load. -Higher values are more suitable for Ansible usage in automation scenarios, when UI responsiveness is not required but CPU usage might be a concern. -Default corresponds to the value hardcoded in Ansible ≤ 2.1:: - - internal_poll_interval=0.001 - -.. _inventory_file: - -inventory -========= - -This is the default location of the inventory file, script, or directory that Ansible will use to determine what hosts it has available -to talk to:: - - inventory = /etc/ansible/hosts - -It used to be called hostfile in Ansible before 1.9 - -.. _inventory_ignore_extensions: - -inventory_ignore_extensions -=========================== - -Comma-separated list of file extension patterns to ignore when Ansible inventory -is a directory with multiple sources (static and dynamic):: - - inventory_ignore_extensions = ~, .orig, .bak, .ini, .cfg, .retry, .pyc, .pyo - -This option can be overridden by setting :envvar:`ANSIBLE_INVENTORY_IGNORE` -environment variable. - -.. _jinja2_extensions: - -jinja2_extensions -================= - -This is a developer-specific feature that allows enabling additional Jinja2 extensions:: - - jinja2_extensions = jinja2.ext.do,jinja2.ext.i18n - -If you do not know what these do, you probably don't need to change this setting :) - -.. _library: - -library -======= - -This is the default location Ansible looks to find modules:: - - library = /usr/share/ansible - -Ansible can look in multiple locations if you feed it a colon -separated path, and it also will look for modules in the :file:`./library` -directory alongside a playbook. - -This can be used to manage modules pulled from several different locations. -For instance, a site wishing to checkout modules from several different git -repositories might handle it like this: - -.. code-block:: shell-session - - $ mkdir -p /srv/modules - $ cd /srv/modules - $ git checkout https://vendor_modules . - $ git checkout ssh://custom_modules . - $ export ANSIBLE_LIBRARY=/srv/modules/custom_modules:/srv/modules/vendor_modules - $ ansible [...] - -In case of modules with the same name, the library paths are searched in order -and the first module found with that name is used. - -.. _local_tmp: - -local_tmp -========= - -.. versionadded:: 2.1 - -When Ansible gets ready to send a module to a remote machine it usually has to -add a few things to the module: Some boilerplate code, the module's -parameters, and a few constants from the config file. This combination of -things gets stored in a temporary file until ansible exits and cleans up after -itself. The default location is a subdirectory of the user's home directory. -If you'd like to change that, you can do so by altering this setting:: - - local_tmp = ~/.ansible/tmp - -Ansible will then choose a random directory name inside this location. - -.. _log_path: - -log_path -======== - -If present and configured in ansible.cfg, Ansible will log information about executions at the designated location. Be sure -the user running Ansible has permissions on the logfile:: - - log_path=/var/log/ansible.log - -This behavior is not on by default. Note that ansible will, without this setting, record module arguments called to the -syslog of managed machines. Password arguments are excluded. - -For Enterprise users seeking more detailed logging history, you may be interested in :doc:`tower`. - -.. _lookup_plugins: - -lookup_plugins -============== - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - lookup_plugins = ~/.ansible/plugins/lookup_plugins/:/usr/share/ansible_plugins/lookup_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - -.. _merge_multiple_cli_tags: - -merge_multiple_cli_tags -======================= - -.. versionadded:: 2.3 - -This allows changing how multiple :option:`--tags ` and :option:`--skip-tags ` -arguments are handled on the command line. Specifying :option:`--tags ` more -than once merges all of the :option:`--tags ` options together. If you want -the pre-2.4.x behaviour where only the last value of :option:`--tags ` is used, -then set this to False. The same holds true for :option:`--skip-tags `. - -.. note:: The default value for this in 2.3 is False. In 2.4, the - default value is True. After 2.8, the option will be removed. - Multiple :option:`--tags ` and multiple :option:`--skip-tags ` will always - be merged together. - -.. _module_lang: - -module_lang -=========== - -This is to set the default language to communicate between the module and the system. -By default, the value is value `LANG` on the controller or, if unset, `en_US.UTF-8` (it used to be `C` in previous versions):: - - module_lang = en_US.UTF-8 - -.. note:: - - This is only used if :ref:`module_set_locale` is set to True. - -.. _module_name: - -module_name -=========== - -This is the default module name (-m) value for /usr/bin/ansible. The default is the 'command' module. -Remember the command module doesn't support shell variables, pipes, or quotes, so you might wish to change -it to 'shell':: - - module_name = command - -.. _module_set_locale: - -module_set_locale -================= - -This boolean value controls whether or not Ansible will prepend locale-specific environment variables (as specified -via the :ref:`module_lang` configuration option). If enabled, it results in the LANG, LC_MESSAGES, and LC_ALL -being set when the module is executed on the given remote system. By default this is disabled. - -.. note:: - - The module_set_locale option was added in Ansible-2.1 and defaulted to - True. The default was changed to False in Ansible-2.2 - -.. _module_utils: - -module_utils -============ - -This is the default location Ansible looks to find module_utils:: - - module_utils = /usr/share/ansible/my_module_utils - -module_utils are python modules that Ansible is able to combine with Ansible -modules when sending them to the remote machine. Having custom module_utils -is useful for extracting common code when developing a set of site-specific -modules. - -Ansible can look in multiple locations if you feed it a colon -separated path, and it also will look for modules in the -:file:`./module_utils` directory alongside a playbook. - -.. _nocolor: - -nocolor -======= - -By default ansible will try to colorize output to give a better indication of failure and status information. -If you dislike this behavior you can turn it off by setting 'nocolor' to 1:: - - nocolor = 0 - -.. _nocows: - -nocows -====== - -By default ansible will take advantage of cowsay if installed to make /usr/bin/ansible-playbook runs more exciting. -Why? We believe systems management should be a happy experience. If you do not like the cows, you can disable them -by setting 'nocows' to 1:: - - nocows = 0 - -.. _pattern: - -pattern -======= - -This is the default group of hosts to talk to in a playbook if no "hosts:" stanza is supplied. The default is to talk -to all hosts. You may wish to change this to protect yourself from surprises:: - - hosts = * - -Note that /usr/bin/ansible always requires a host pattern and does not use this setting, only /usr/bin/ansible-playbook. - -.. _poll_interval: - -poll_interval -============= - -For asynchronous tasks in Ansible (covered in :doc:`playbooks_async`), this is how often to check back on the status of those -tasks when an explicit poll interval is not supplied. The default is a reasonably moderate 15 seconds which is a tradeoff -between checking in frequently and providing a quick turnaround when something may have completed:: - - poll_interval = 15 - -.. _private_key_file: - -private_key_file -================ - -If you are using a pem file to authenticate with machines rather than SSH agent or passwords, you can set the default -value here to avoid re-specifying ``--private-key`` with every invocation:: - - private_key_file=/path/to/file.pem - -.. _remote_port: - -remote_port -=========== - -This sets the default SSH port on all of your systems, for systems that didn't specify an alternative value in inventory. -The default is the standard 22:: - - remote_port = 22 - -.. _remote_tmp: - -remote_tmp -========== - -Ansible works by transferring modules to your remote machines, running them, and then cleaning up after itself. In some -cases, you may not wish to use the default location and would like to change the path. You can do so by altering this -setting:: - - remote_tmp = ~/.ansible/tmp - -The default is to use a subdirectory of the user's home directory. Ansible will then choose a random directory name -inside this location. - -.. _remote_user: - -remote_user -=========== - -This is the default username ansible will connect as for /usr/bin/ansible-playbook. Note that /usr/bin/ansible will -always default to the current user if this is not defined:: - - remote_user = root - - -.. _retry_files_enabled: - -retry_files_enabled -=================== - -This controls whether a failed Ansible playbook should create a .retry file. The default setting is True:: - - retry_files_enabled = False - -.. _retry_files_save_path: - -retry_files_save_path -===================== - -The retry files save path is where Ansible will save .retry files when a playbook fails and retry_files_enabled is True (the default). -The default location is adjacent to the play (~/ in versions older than 2.0) and can be changed to any writeable path:: - - retry_files_save_path = ~/.ansible/retry-files - -The directory will be created if it does not already exist. - -.. _cfg_roles_path: - -roles_path -========== - -.. versionadded:: 1.4 - -The roles path indicate additional directories beyond the 'roles/' subdirectory of a playbook project to search to find Ansible -roles. For instance, if there was a source control repository of common roles and a different repository of playbooks, you might -choose to establish a convention to checkout roles in /opt/mysite/roles like so:: - - roles_path = /opt/mysite/roles - -Additional paths can be provided separated by colon characters, in the same way as other pathstrings:: - - roles_path = /opt/mysite/roles:/opt/othersite/roles - -Roles will be first searched for in the playbook directory. Should a role not be found, it will indicate all the possible paths -that were searched. - -.. _cfg_squash_actions: - -squash_actions -============== - -.. versionadded:: 2.0 - -Ansible can optimise actions that call modules that support list parameters when using with\_ looping. -Instead of calling the module once for each item, the module is called once with the full list. - -The default value for this setting is only for certain package managers, but it can be used for any module:: - - squash_actions = apk,apt,dnf,homebrew,package,pacman,pkgng,yum,zypper - -Currently, this is only supported for modules that have a name parameter, and only when the item is the -only thing being passed to the parameter. - -.. _stdout_callback: - -stdout_callback -=============== - -.. versionadded:: 2.0 - -This setting allows you to override the default stdout callback for ansible-playbook:: - - stdout_callback = skippy - -.. _cfg_strategy_plugins: - -strategy_plugins -================== - -Strategy plugin allow users to change the way in which Ansible runs tasks on targeted hosts. - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - strategy_plugins = ~/.ansible/plugins/strategy_plugins/:/usr/share/ansible_plugins/strategy_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - -.. _cfg_strategy: - -strategy -======== - -Strategy allow to change the default strategy used by Ansible:: - - strategy = free - -.. _sudo_exe: - -sudo_exe -======== - -If using an alternative sudo implementation on remote machines, the path to sudo can be replaced here provided -the sudo implementation is matching CLI flags with the standard sudo:: - - sudo_exe = sudo - -.. _sudo_flags: - -sudo_flags -========== - -Additional flags to pass to sudo when engaging sudo support. The default is '-H -S -n' which sets the HOME environment -variable, prompts for passwords via STDIN, and avoids prompting the user for input of any kind. Note that '-n' will conflict -with using password-less sudo auth, such as pam_ssh_agent_auth. In some situations you may wish to add or remove flags, but -in general most users will not need to change this setting::: - - sudo_flags=-H -S -n - -.. _sudo_user: - -sudo_user -========= - -This is the default user to sudo to if ``--sudo-user`` is not specified or 'sudo_user' is not specified in an Ansible -playbook. The default is the most logical: 'root':: - - sudo_user = root - -.. _system_warnings: - -system_warnings -=============== - -.. versionadded:: 1.6 - -Allows disabling of warnings related to potential issues on the system running ansible itself (not on the managed hosts):: - - system_warnings = True - -These may include warnings about 3rd party packages or other conditions that should be resolved if possible. - -.. _timeout: - -timeout -======= - -This is the default SSH timeout to use on connection attempts:: - - timeout = 10 - -.. _transport: - -transport -========= - -This is the default transport to use if "-c " is not specified to /usr/bin/ansible or /usr/bin/ansible-playbook. -The default is 'smart', which will use 'ssh' (OpenSSH based) if the local operating system is new enough to support ControlPersist -technology, and then will otherwise use 'paramiko'. Other transport options include 'local', 'chroot', 'jail', and so on. - -Users should usually leave this setting as 'smart' and let their playbooks choose an alternate setting when needed with the -'connection:' play parameter:: - - transport = paramiko - -.. _vars_plugins: - -vars_plugins -============ - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - vars_plugins = ~/.ansible/plugins/vars_plugins/:/usr/share/ansible_plugins/vars_plugins - -Most users will not need to use this feature. See :doc:`dev_guide/developing_plugins` for more details - - -.. _vault_password_file: - -vault_password_file -=================== - -.. versionadded:: 1.7 - -Configures the path to the Vault password file as an alternative to specifying ``--vault-password-file`` on the command line:: - - vault_password_file = /path/to/vault_password_file - -As of 1.7 this file can also be a script. If you are using a script instead of a flat file, ensure that it is marked as executable, and that the password is printed to standard output. If your script needs to prompt for data, prompts can be sent to standard error. - -.. _privilege_escalation: - -Privilege Escalation Settings ------------------------------ - -Ansible can use existing privilege escalation systems to allow a user to execute tasks as another. As of 1.9 'become' supersedes the old sudo/su, while still being backwards compatible. Settings live under the [privilege_escalation] header. - -.. _become: - -become -====== - -The equivalent of adding sudo: or su: to a play or task, set to true/yes to activate privilege escalation. The default behavior is no:: - - become = True - -.. _become_method: - -become_method -============= - -Set the privilege escalation method. The default is ``sudo``, other options are ``su``, ``pbrun``, ``pfexec``, ``doas``, ``ksu``:: - - become_method = su - -.. _become_user: - -become_user -============= - -The equivalent to ansible_sudo_user or ansible_su_user, allows to set the user you become through privilege escalation. The default is 'root':: - - become_user = root - -.. _become_ask_pass: - -become_ask_pass -=============== - -Ask for privilege escalation password, the default is False:: - - become_ask_pass = True - -.. _become_allow_same_user: - -become_allow_same_user -====================== - -Most of the time, using *sudo* to run a command as the same user who is running -*sudo* itself is unnecessary overhead, so Ansible does not allow it. However, -depending on the *sudo* configuration, it may be necessary to run a command as -the same user through *sudo*, such as to switch SELinux contexts. For this -reason, you can set ``become_allow_same_user`` to ``True`` and disable this -optimization. - -.. _paramiko_settings: - -Paramiko Specific Settings --------------------------- - -Paramiko is the default SSH connection implementation on Enterprise Linux 6 or earlier, and is not used by default on other -platforms. Settings live under the [paramiko_connection] header. - -.. _record_host_keys: - -record_host_keys -================ - -The default setting of yes will record newly discovered and approved (if host key checking is enabled) hosts in the user's hostfile. -This setting may be inefficient for large numbers of hosts, and in those situations, using the ssh transport is definitely recommended -instead. Setting it to False will improve performance and is recommended when host key checking is disabled:: - - record_host_keys = True - -.. _paramiko_proxy_command: - -proxy_command -============= - -.. versionadded:: 2.1 - -Use an OpenSSH like ProxyCommand for proxying all Paramiko SSH connections through a bastion or jump host. Requires a minimum of Paramiko version 1.9.0. On Enterprise Linux 6 this is provided by ``python-paramiko1.10`` in the EPEL repository:: - - proxy_command = ssh -W "%h:%p" bastion - -.. _openssh_settings: - -OpenSSH Specific Settings -------------------------- - -Under the [ssh_connection] header, the following settings are tunable for SSH connections. OpenSSH is the default connection type for Ansible -on OSes that are new enough to support ControlPersist. (This means basically all operating systems except Enterprise Linux 6 or earlier). - -.. _ssh_args: - -ssh_args -======== - -If set, this will pass a specific set of options to Ansible rather than Ansible's usual defaults:: - - ssh_args = -o ControlMaster=auto -o ControlPersist=60s - -In particular, users may wish to raise the ControlPersist time to encourage performance. A value of 30 minutes may -be appropriate. If ``-o ControlPath`` is set in ``ssh_args``, the ``control_path`` setting is not used. - -.. _control_path: - -control_path -============ - -This is the location to save ControlPath sockets. This defaults to:: - - control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r - -On some systems with very long hostnames or very long path names (caused by long user names or -deeply nested home directories) this can exceed the character limit on -file socket names (108 characters for most platforms). In that case, you -may wish to shorten the string to something like the below:: - - control_path = %(directory)s/%%h-%%r - -Ansible 1.4 and later will instruct users to run with "-vvvv" in situations where it hits this problem -and if so it is easy to tell there is too long of a Control Path filename. This may be frequently -encountered on EC2. This setting is ignored if ``-o ControlPath`` is set in ``ssh_args``. - -.. _control_path_dir: - -control_path_dir -================ - -.. versionadded:: 2.3 - -This is the base directory of the ControlPath sockets. -It is the ``%(directory)s`` part of the ``control_path`` option. -This defaults to:: - - control_path_dir=~/.ansible/cp - -.. _retries: - -retries -======= - -Adds the option to retry failed ssh executions if the failure is encountered in ssh itself, not the remote command. This can be helpful if there are transient network issues. Enabled by setting retries to an integer greater than 1. Defaults to:: - - retries = 0 - -.. _scp_if_ssh: - -scp_if_ssh -========== - -Occasionally users may be managing a remote system that doesn't have SFTP enabled. If set to True, we can -cause scp to be used to transfer remote files instead:: - - scp_if_ssh = False - -There's really no reason to change this unless problems are encountered, and then there's also no real drawback -to managing the switch. Most environments support SFTP by default and this doesn't usually need to be changed. - - -.. _pipelining: - -pipelining -========== - -Enabling pipelining reduces the number of SSH operations required to -execute a module on the remote server, by executing many ansible modules without actual file transfer. -This can result in a very significant performance improvement when enabled, however when using "sudo:" operations you must -first disable 'requiretty' in /etc/sudoers on all managed hosts. - -By default, this option is disabled to preserve compatibility with -sudoers configurations that have requiretty (the default on many distros), but is highly -recommended if you can enable it. - - pipelining = False - -.. _ssh_executable: - -ssh_executable -============== - -.. versionadded:: 2.2 - -This is the location of the ssh binary. It defaults to ``ssh`` which will use the first ssh binary available in ``$PATH``. This config can also be overridden with ``ansible_ssh_executable`` inventory variable:: - - ssh_executable="/usr/local/bin/ssh" - -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. - -.. _selinux_settings: - -Selinux Specific Settings -------------------------- - -These are settings that control SELinux interactions. - - -special_context_filesystems -=========================== - -.. versionadded:: 1.9 - -This is a list of file systems that require special treatment when dealing with security context. -The normal behaviour is for operations to copy the existing context or use the user default, this changes it to use a file system dependent context. -The default list is: nfs,vboxsf,fuse,ramfs:: - - special_context_filesystems = nfs,vboxsf,fuse,ramfs,myspecialfs - -libvirt_lxc_noseclabel -====================== - -.. versionadded:: 2.1 - -This setting causes libvirt to connect to lxc containers by passing --noseclabel to virsh. -This is necessary when running on systems which do not have SELinux. -The default behavior is no:: - - libvirt_lxc_noseclabel = True - -.. _show_custom_stats: - -show_custom_stats -================= - -.. versionadded:: 2.3 - -If enabled, this setting will display custom stats (set via set_stats plugin) when using the default callback. - - -Galaxy Settings ---------------- - -The following options can be set in the [galaxy] section of ansible.cfg: - -server -====== - -Override the default Galaxy server value of https://galaxy.ansible.com. Useful if you have a hosted version of the Galaxy web app or want to point to the testing site https://galaxy-qa.ansible.com. It does not work against private, hosted repos, which Galaxy can use for fetching and installing roles. - -ignore_certs -============ - -If set to *yes*, ansible-galaxy will not validate TLS certificates. This can be useful for testing against a server with a self-signed certificate. + :doc:`intro_dynamic_inventory` + Pulling inventory from dynamic sources, such as cloud providers + :doc:`intro_adhoc` + Examples of basic commands + :doc:`playbooks` + Learning Ansible's configuration, deployment, and orchestration language. + :doc:`config` + Ansible's configuration file and environment settings in detail + :doc:`command_line_tools` + Ansible's command line tools documentation and detailed options + `Mailing List `_ + Questions? Help? Ideas? Stop by the list on Google Groups + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/playbooks_lookups.rst b/docs/docsite/rst/playbooks_lookups.rst index 0e57fb927f..921f768213 100644 --- a/docs/docsite/rst/playbooks_lookups.rst +++ b/docs/docsite/rst/playbooks_lookups.rst @@ -3,15 +3,15 @@ Lookups Lookup plugins allow access of data in Ansible from outside sources. Like all templating, these plugins are evaluated on the Ansible control machine, and can include reading the filesystem but also contacting external datastores and services. -These values are then made available using the standard templating system in Ansible, and are typically used to load variables or templates with information from those systems. -.. note:: This is considered an advanced feature, and many users will probably not rely on these features. +These values are then made available using the standard templating system in Ansible, +and are typically used to load variables or templates with information from those systems. -.. note:: Lookups occur on the local computer, not on the remote computer. - -.. note:: Lookups are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script. - -.. note:: Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops. +.. note:: + - Lookups occur on the local computer, not on the remote computer. + - They are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script. + - Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops. + - This is considered an advanced feature, you should try to feel comfortable with Ansible plays before incorporating them. .. warning:: Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage. diff --git a/docs/docsite/rst/playbooks_reuse_includes.rst b/docs/docsite/rst/playbooks_reuse_includes.rst index df6cf7b28c..eb71fb801b 100644 --- a/docs/docsite/rst/playbooks_reuse_includes.rst +++ b/docs/docsite/rst/playbooks_reuse_includes.rst @@ -69,7 +69,7 @@ Variables can also be passed to include files using an alternative syntax, which - "{{ lookup('file', 'keys/one.pub') }}" - "{{ lookup('file', 'keys/two.pub') }}" -Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`variable_precedence` for more details on variable inheritance and precedence. +Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`ansible_variable_precedence` for more details on variable inheritance and precedence. Task include statements can be used at arbitrary depth. diff --git a/docs/docsite/rst/playbooks_special_topics.rst b/docs/docsite/rst/playbooks_special_topics.rst index ab5476d2cc..0f51b6483a 100644 --- a/docs/docsite/rst/playbooks_special_topics.rst +++ b/docs/docsite/rst/playbooks_special_topics.rst @@ -16,9 +16,10 @@ and adopt these only if they seem relevant or useful to your environment. playbooks_environment playbooks_error_handling playbooks_advanced_syntax - playbooks_lookups + plugins playbooks_prompts playbooks_tags playbooks_vault playbooks_startnstep playbooks_keywords + playbooks_lookups diff --git a/docs/docsite/rst/playbooks_variables.rst b/docs/docsite/rst/playbooks_variables.rst index bee569bdd3..f157b81286 100644 --- a/docs/docsite/rst/playbooks_variables.rst +++ b/docs/docsite/rst/playbooks_variables.rst @@ -798,7 +798,7 @@ As of Ansible 1.3, extra vars can be loaded from a JSON file with the ``@`` synt Also as of Ansible 1.3, extra vars can be formatted as YAML, either on the command line or in a file as above. -.. _variable_precedence: +.. _ansible_variable_precedence: Variable Precedence: Where Should I Put A Variable? ```````````````````````````````````````````````````` diff --git a/docs/docsite/rst/plugins.rst b/docs/docsite/rst/plugins.rst new file mode 100644 index 0000000000..12bb456979 --- /dev/null +++ b/docs/docsite/rst/plugins.rst @@ -0,0 +1,31 @@ +Plugins +======= + +Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set. +They are pieces of code that augment Ansible's core functionality. +Ansible ships with a number of handy plugins, and you can easily write your own. + +There are many types of plugins, these are the most relevant ones: + +.. toctree:: :maxdepth: 1 + :glob: + + plugins/* + playbooks_filters + playbooks_tests + +Most of the time you are using them without having to know about them, but when you want to change certain behaviours you need to know how to enable, +activate or trigger each type. + +.. seealso:: + + :doc:`playbooks` + An introduction to playbooks + :doc:`config` + Ansible configuration documentation and settings + :doc:`command_line_tools` + Ansible tools, description and options + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst new file mode 100644 index 0000000000..3db438ff13 --- /dev/null +++ b/docs/docsite/rst/plugins/action.rst @@ -0,0 +1,36 @@ +Action Plugins +--------------- + +These plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks. +They mostly execute automatically in the background doing prerequisite work for the modules of the same to be able to execute. + +The 'normal' action plugin takes care of modules that do not already have an action plugin. + +Enabling Vars Plugins ++++++++++++++++++++++ + +You can activate a custom action plugins by either dropping it into a ``action_plugins`` directory adjacent to your play or inside a role +or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`. + + + +.. seealso:: + + :doc:`cache` + Ansible Cache plugins + :doc:`callback` + Ansible callback plugins + :doc:`connection` + Ansible connection plugins + :doc:`inventory` + Ansible inventory plugins + :doc:`shell` + Ansible Shell plugins + :doc:`strategy` + Ansible Strategy plugins + :doc:`vars` + Ansible Vars plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst new file mode 100644 index 0000000000..d5e9251cfd --- /dev/null +++ b/docs/docsite/rst/plugins/cache.rst @@ -0,0 +1,65 @@ +.. contents:: Topics + + +Cache Plugins +------------- + +This plugin implelents a backend caching mechanism for Ansible to store gathered facts or inventory source data +to avoid the cost of retrieving them from source. + +The default plugin is the :doc:`memory ` plugin which will only cache the data for the current execution of Ansible. +Other plugins with persistent storage are available to allow caching the data across runs. + + +Enabling Cache Plugins +++++++++++++++++++++++ + +Only one cache plugin can be active at a time. + +You can enable in configuration, either via environment variable: + +.. code-block:: shell + + export ANSIBLE_CACHE_PLUGIN=jsonfile + +or in the ``ansible.cfg`` file: + +.. code-block:: ini + + [defaults] + fact_caching=redis + +You will also need to setup other settings specific to each plugin, you can check the individual plugin documenattion +or the ansible :doc:`configuration <../config>` for more details. + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t cache -l`` to see the list of available plugins, +use ``ansible-doc -t cache `` to see specific documents and examples. + +.. toctree:: :maxdepth: 1 + :glob: + + cache/* + +.. seealso:: + + :doc:`action` + Ansible Action plugins + :doc:`callback` + Ansible callback plugins + :doc:`connection` + Ansible connection plugins + :doc:`inventory` + Ansible inventory plugins + :doc:`shell` + Ansible Shell plugins + :doc:`strategy` + Ansible Strategy plugins + :doc:`vars` + Ansible Vars plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst new file mode 100644 index 0000000000..3c7b4b519a --- /dev/null +++ b/docs/docsite/rst/plugins/callback.rst @@ -0,0 +1,107 @@ +.. contents:: Topics + + +Callback Plugins +---------------- + +Callback plugins enable adding new behaviors to Ansible when responding to events. +By default, callback plugins control most of the output you see when running the command line programs, +but can also be used to add additional output, integrate with other tools and marshall the events to a storage backend. + +.. _callback_examples: + +Example Callback Plugins +++++++++++++++++++++++++ + +The :doc:`log_plays ` callback is an example of how to record playbook events to a log file, +and the :doc:`mail callback/mail` callback sends email on playbook failures. + +The :doc:`osx_say ` callback provided is particularly entertaining -- +it will respond with computer synthesized speech on OS X in relation to playbook events, +and is guaranteed to entertain and/or annoy coworkers. + + +.. _enabling_callbacks: + +Enabling Callback Plugins +++++++++++++++++++++++++++ + +You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play or inside a role +or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`. + +Plugins are loaded in alphanumeric order; for example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`. + +Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function. +For example: + +.. code-block:: ini + + #callback_whitelist = timer, mail, profile_roles + + +Managing stdout +``````````````` + +You can only have one plugin be the main manager of your console output. If you want to replace the default, you should define CALLBACK_TYPE = stdout in the subclass and then configure the stdout plugin in :doc:`ansible.cfg <../config>`. For example: + +.. code-block:: ini + + stdout_callback = dense + +or for my custom callback: + +.. code-block:: ini + + stdout_callback = mycallback + +This only affects :doc:`../ansible-playbook` by default. + +Managing AdHoc +`````````````` + +The :doc:`ansible <../ansible>` AdHoc command speifically uses a different callback plugin for stdout, +so there is an extra setting you need to enable it to use the stdout callback defined above, in :doc:`ansible.cfg <../config>`: + +.. code-block:: ini + + [defaults] + bin_ansible_callbacks=True + +or as an environment variable: + +.. code-block:: shell + + export ANSIBLE_LOAD_CALLBACK_PLUGINS=1 + + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t callback -l`` to see the list of available plugins, +use ``ansible-doc -t callback `` to see specific documents and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + callback/* + + +.. seealso:: + + :doc:`../playbooks` + An introduction to playbooks + :doc:`inventory` + Ansible inventory plugins + :doc:`../playbooks_filters` + Jinja2 filter plugins + :doc:`../playbooks_tests` + Jinja2 test plugins + :doc:`../playbooks_lookups` + Jinja2 lookup plugins + :doc:`vars` + Ansible vars plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst new file mode 100644 index 0000000000..ae66cfa399 --- /dev/null +++ b/docs/docsite/rst/plugins/connection.rst @@ -0,0 +1,83 @@ +.. contents:: Topics + + +Connection Plugins +------------------ + +These plugins are in charge of enabling Ansible to connect to the target hosts so it can execute tasks on them. +Ansible ships we many connection plugins but only one can be used per host at a time. + +By default, the configuration uses a 'smart' value, which means Ansible will decide to use the 'ssh' or 'paramiko' (python version of ssh client) +depending on what it detects on your system capabilities, it normally chooses 'ssh' if OpenSSH supports ControlPersist. + +The basics of these connection types are covered in the :doc:`../intro_getting_started` section. + +.. contents:: Topics + +.. _ssh_plugins: + +The ssh Plugins +++++++++++++++++ + +Since ssh is the default protocol used in system administration it is also the most used and prevalent in Ansible, +so much so that ssh options are included in the command line tools unlike other plugins, see :doc:`../ansible-playbook` for more details. + + +.. _using_connection_plugins: + +Using Connection Plugins +++++++++++++++++++++++++ + +The transport can be changed via :doc:`configuration <../config>`, in the command line (``-c``, ``--connection``), as a keyword (:ref:`connection`) +in your play or by setting the a connection variable (:ref:`ansible_connection`), most often, in your inventory. +For example, for windows machines you might want o use the :doc:`winrm ` plugin instead. + +Most connection plugins can operate with a minimum configuration, by defaul they use the :ref:`inventory_hostname` and defaults to find the target host. +Each plugin documents it's configuration options and how to set, the following are 'connection variables' common to most: + +:ref:ansible_host + The name of the host to connect to, if different from the :ref:`inventory_hostname`. +:ref:ansible_port + The ssh port number, for :doc:`ssh ` and :doc:`paramiko ` it defaults to 22. +:ref:ansible_user + The default user name to log in as, most plugins defaul to the 'current user running Ansible' + +Each plugin might also have a specific version that overrides the general one. i.e :ref:`ansible_ssh_host` for the :doc:`ssh ` plugin. + +Enabling Connection Plugins ++++++++++++++++++++++++++++ + +Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as dropping a custom plugin +into the ``connection_plugins`` directory. + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t connection -l`` to see the list of available plugins, +use ``ansible-doc -t connection `` to examine detailed documentation and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + connection/* + + +.. seealso:: + + :doc:`../playbooks` + An introduction to playbooks + :doc:`callback` + Ansible callback plugins + :doc:`../playbooks_filters` + Jinja2 filter plugins + :doc:`../playbooks_tests` + Jinja2 test plugins + :doc:`../playbooks_lookups` + Jinja2 lookup plugins + :doc:`vars` + Ansible vars plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst new file mode 100644 index 0000000000..cf784d4bce --- /dev/null +++ b/docs/docsite/rst/plugins/inventory.rst @@ -0,0 +1,62 @@ +.. contents:: Topics + + +Inventory Plugins +----------------- + +Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target it's tasks. +They control what happens when with ``-i /path/to/file`` and/or ``-i 'host1, host2`` when passed into Ansible (or from other configuration sources). + +.. _enabling_inventory_plugins: + +Enabling Inventory Plugins +++++++++++++++++++++++++++ + +Most inventory plugins shipped with Ansible are disabled by default and need to be whitelisted in your +:doc:`ansible.cfg <../config>` file in order to function. For example, this is how the default looks like: + +.. code-block:: ini + + [inventory] + enable_plugins = host_list, script, yaml, ini + +This list also establishes the order in which each plugin tries to parse an inventory source (in the case 2 plugins can use the same source). +Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use: + +.. code-block:: ini + + [inventory] + enable_plugins = advanced_host_list, constructed, yaml + + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t inventory -l`` to see the list of available plugins, +use ``ansible-doc -t inventory `` to see specific documents and examples. + +.. toctree:: :maxdepth: 1 + :glob: + + inventory/* + +.. seealso:: + + :doc:`../playbooks` + An introduction to playbooks + :doc:`callback` + Ansible callback plugins + :doc:`connection` + Ansible connection plugins + :doc:`../playbooks_filters` + Jinja2 filter plugins + :doc:`../playbooks_tests` + Jinja2 test plugins + :doc:`../playbooks_lookups` + Jinja2 lookup plugins + :doc:`vars` + Ansible vars plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst new file mode 100644 index 0000000000..75247d8a1c --- /dev/null +++ b/docs/docsite/rst/plugins/shell.rst @@ -0,0 +1,36 @@ +Shell Plugins +------------- + +These plugins work behind the scenes making sure the basic commands Ansible runs, +in order to be able to execute a task's action, +are properly formated to work with the target machine. + +You normally don't have to wory about these plugins at all, +unless you have a restricted or exotic setup, +in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution. + +Enabling Shell Plugins +++++++++++++++++++++++ + +You probably never need to do this, but aside from the defaul configuration settings in :doc:`../config`, +you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use, +you will also want to update the :ref:`ansible_executable` to match. + +.. seealso:: + + :doc:`../playbooks` + An introduction to playbooks + :doc:`inventory` + Ansible inventory plugins + :doc:`callback` + Ansible callback plugins + :doc:`../playbooks_filters` + Jinja2 filter plugins + :doc:`../playbooks_tests` + Jinja2 test plugins + :doc:`../playbooks_lookups` + Jinja2 lookup plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst new file mode 100644 index 0000000000..0afb7d2abc --- /dev/null +++ b/docs/docsite/rst/plugins/strategy.rst @@ -0,0 +1,71 @@ +.. contents:: Topics + + +Strategy Plugins +---------------- + +Strategy plugins control the flow of play execution, they handle task and host scheduleing. + + +Enabling Cache Plugins +++++++++++++++++++++++ + +Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run. +The default is the :doc:`linear ` plugin, you can change this default via :doc:`configuration <../config>`: + +.. code-block:: shell + + export ANSIBLE_STRATEGY=free + +or in the `ansible.cfg` file: + +.. code-block:: ini + + [defaults] + strategy=linear + +Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword:: + + - hosts: all + strategy: debug + tasks: + - copy: src=myhosts dest=/etc/hosts + notify: restart_tomcat + + - package: name=tomcat state=present + + handlers: + - name: restart_tomcat + service: name=tomcat state=restarted + + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t strategy -l`` to see the list of available plugins, +use ``ansible-doc -t strategy `` to see specific documents and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + strategy/* + +.. seealso:: + + :doc:`../playbooks` + An introduction to playbooks + :doc:`inventory` + Ansible inventory plugins + :doc:`callback` + Ansible callback plugins + :doc:`../playbooks_filters` + Jinja2 filter plugins + :doc:`../playbooks_tests` + Jinja2 test plugins + :doc:`../playbooks_lookups` + Jinja2 lookup plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst new file mode 100644 index 0000000000..fa280dd87f --- /dev/null +++ b/docs/docsite/rst/plugins/vars.rst @@ -0,0 +1,48 @@ +.. contents:: Topics + + +Vars Plugins +------------ + +They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line. +The :doc:`host_group_vars ` plugin shipped with Ansible provides reading variables from :ref:`host_vars` and :ref:`group_vars`. + + +Enabling Vars Plugins ++++++++++++++++++++++ + +You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play or inside a role +or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`. + +Plugin Lists +++++++++++++ + +You can use ``ansible-doc -t vars -l`` to see the list of available plugins, +use ``ansible-doc -t vars `` to see specific documents and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + vars/* + +.. seealso:: + + :doc:`action` + Ansible Action plugins + :doc:`cache` + Ansible Cache plugins + :doc:`callback` + Ansible callback plugins + :doc:`connection` + Ansible connection plugins + :doc:`inventory` + Ansible inventory plugins + :doc:`shell` + Ansible Shell plugins + :doc:`strategy` + Ansible Strategy plugins + `User Mailing List `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2 index f40143690f..e3ffa531b8 100644 --- a/docs/templates/config.rst.j2 +++ b/docs/templates/config.rst.j2 @@ -6,9 +6,42 @@ {{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 %} diff --git a/docs/templates/man.j2 b/docs/templates/man.j2 index 641d06128b..bad8863397 100644 --- a/docs/templates/man.j2 +++ b/docs/templates/man.j2 @@ -104,7 +104,6 @@ AUTHOR ------ Ansible was originally written by Michael DeHaan. -See the AUTHORS file for a complete list of contributors. COPYRIGHT diff --git a/lib/ansible/plugins/inventory/constructed.py b/lib/ansible/plugins/inventory/constructed.py index 814c67a4f9..35d19f9e80 100644 --- a/lib/ansible/plugins/inventory/constructed.py +++ b/lib/ansible/plugins/inventory/constructed.py @@ -13,17 +13,22 @@ DOCUMENTATION = ''' - Uses a YAML configuration file to define var expresisions and group conditionals - The Jinja2 conditionals that qualify a host for membership. - The JInja2 exprpessions are calculated and assigned to the variables - - Only variables already available from previous inventories can be used for templating. - - Failed expressions will be ignored (assumes vars were missing). + - Only variables already available from previous inventories or the fact cache can be used for templating. + - When `strict` is False, failed expressions will be ignored (assumes vars were missing). extends_documentation_fragment: - constructed ''' EXAMPLES = ''' # inventory.config file in YAML format - plugin: comstructed + plugin: constructed + strict: False compose: var_sum: var1 + var2 + + # this variable will only be set if I have a persistent fact cache enabled (and have non expired facts) + # `strict: False` will skip this instead of producing an error if it is missing facts. + server_type: "ansible_hostname | regex_replace ('(.{6})(.{2}).*', '\\2')" groups: # simple name matching webservers: inventory_hostname.startswith('web')