diff options
| author | Brian Coca <brian.coca+git@gmail.com> | 2017-08-20 11:20:30 -0400 |
|---|---|---|
| committer | Toshio Kuratomi <a.badger@gmail.com> | 2017-09-09 09:48:22 -0700 |
| commit | 075ead8fb0fe26f502f592bcf78851d0e24ac3a4 (patch) | |
| tree | f7e9eb43a26a58da3b94776d748d6a0b8dbda5bb /lib/ansible | |
| parent | f88750d66512bb01fa64e9080f3d3fbc9eb9d758 (diff) | |
| download | ansible-075ead8fb0fe26f502f592bcf78851d0e24ac3a4.tar.gz | |
fixes to config/setting retrieval
- better variable precedence management
- universal plugin option handling
- also updated comments for future directions
- leverage fragments for plugins
- removed fact namespacing
- added 'firendly name' field
- updated missing descriptions
- removed some unused yaml entries, updated others to reflect possible future
- documented more plugins
- allow reading docs using alias
- short licenses
- corrected args for 'all plugins'
- fixed -a option for ansible-doc
- updated vars plugins to allow docs
- fixed 'gathering'
- only set options IF connection
- added path list and renamed pathspec mostly the diff is , vs : as separator
- readded removed config entries that were deprecated but had no message ... and deprecated again
- now deprecated entries give warning when set
Diffstat (limited to 'lib/ansible')
69 files changed, 1871 insertions, 1301 deletions
diff --git a/lib/ansible/cli/__init__.py b/lib/ansible/cli/__init__.py index 6d0292dba1..48b62597a7 100644 --- a/lib/ansible/cli/__init__.py +++ b/lib/ansible/cli/__init__.py @@ -168,6 +168,17 @@ class CLI(with_metaclass(ABCMeta, object)): else: display.v(u"No config file found; using defaults") + # warn about deprecated options + for deprecated in C.config.DEPRECATED: + name = deprecated[0] + why = deprecated[1]['why'] + if 'alternative' in deprecated[1]: + alt = ', use %s instead' % deprecated[1]['alternative'] + else: + alt = '' + ver = deprecated[1]['version'] + display.deprecated("%s option, %s %s" % (name, why, alt), version=ver) + @staticmethod def split_vault_id(vault_id): # return (before_@, after_@) diff --git a/lib/ansible/cli/config.py b/lib/ansible/cli/config.py index 418b998f38..b02dea95b4 100644 --- a/lib/ansible/cli/config.py +++ b/lib/ansible/cli/config.py @@ -44,7 +44,7 @@ except ImportError: class ConfigCLI(CLI): """ Config command line class """ - VALID_ACTIONS = ("view", "edit", "update", "dump", "list") + VALID_ACTIONS = ("view", "dump", "list") # TODO: edit, update, search def __init__(self, args, callback=None): @@ -59,7 +59,6 @@ class ConfigCLI(CLI): epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]), desc="View, edit, and manage ansible configuration.", ) - self.parser.add_option('-c', '--config', dest='config_file', help="path to configuration file, defaults to first file found in precedence.") self.set_action() @@ -70,14 +69,11 @@ class ConfigCLI(CLI): if self.action == "dump": self.parser.add_option('--only-changed', dest='only_changed', action='store_true', help="Only show configurations that have changed from the default") - self.parser.set_usage("usage: %prog dump [options] [-c ansible.cfg]") - elif self.action == "view": - self.parser.set_usage("usage: %prog view [options] [-c ansible.cfg] ") - elif self.action == "edit": - self.parser.set_usage("usage: %prog edit [options] [-c ansible.cfg]") elif self.action == "update": self.parser.add_option('-s', '--setting', dest='setting', help="config setting, the section defaults to 'defaults'") self.parser.set_usage("usage: %prog update [options] [-c ansible.cfg] -s '[section.]setting=value'") + elif self.action == "search": + self.parser.set_usage("usage: %prog update [options] [-c ansible.cfg] <search term>") self.options, self.args = self.parser.parse_args() display.verbosity = self.options.verbosity diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 103b16c1e6..d46d1800b3 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -30,7 +30,8 @@ from ansible.cli import CLI from ansible.errors import AnsibleError, AnsibleOptionsError from ansible.module_utils.six import string_types from ansible.parsing.yaml.dumper import AnsibleDumper -from ansible.plugins.loader import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, connection_loader, strategy_loader, PluginLoader +from ansible.plugins.loader import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, \ + vars_loader, connection_loader, strategy_loader, PluginLoader from ansible.utils import plugin_docs try: from __main__ import display @@ -53,7 +54,7 @@ class DocCLI(CLI): def parse(self): self.parser = CLI.base_parser( - usage='usage: %prog [options] [plugin]', + usage='usage: %prog [-l|-s|-a] [options] [-t <plugin type] [plugin]', module_opts=True, desc="plugin documentation tool", epilog="See man pages for Ansible CLI options or website for tutorials https://docs.ansible.com" @@ -67,10 +68,13 @@ class DocCLI(CLI): help='Show documentation for all plugins') self.parser.add_option("-t", "--type", action="store", default='module', dest='type', type='choice', help='Choose which plugin type (defaults to "module")', - choices=['cache', 'callback', 'connection', 'inventory', 'lookup', 'module', 'strategy']) + choices=['cache', 'callback', 'connection', 'inventory', 'lookup', 'module', 'strategy', 'vars']) super(DocCLI, self).parse() + if [self.options.all_plugins, self.options.list_dir, self.options.show_snippet].count(True) > 1: + raise AnsibleOptionsError("Only one of -l, -a or -s can be used at the same time.") + display.verbosity = self.options.verbosity def run(self): @@ -90,6 +94,8 @@ class DocCLI(CLI): loader = lookup_loader elif plugin_type == 'strategy': loader = strategy_loader + elif plugin_type == 'vars': + loader = vars_loader elif plugin_type == 'inventory': loader = PluginLoader('InventoryModule', 'ansible.plugins.inventory', 'inventory_plugins', 'inventory_plugins') else: @@ -118,6 +124,7 @@ class DocCLI(CLI): paths = loader._get_paths() for path in paths: self.find_plugins(path, plugin_type) + self.args = sorted(set(self.plugin_list)) if len(self.args) == 0: raise AnsibleOptionsError("Incorrect options passed") @@ -128,7 +135,7 @@ class DocCLI(CLI): try: # if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs - filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True) + filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True) if filename is None: display.warning("%s %s not found in:\n%s\n" % (plugin_type, plugin, search_paths)) continue @@ -221,7 +228,7 @@ class DocCLI(CLI): for plugin in sorted(self.plugin_list): # if the module lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs - filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True) + filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True) if filename is None: continue diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml index e18f101633..501ac3fdbe 100644 --- a/lib/ansible/config/base.yml +++ b/lib/ansible/config/base.yml @@ -97,6 +97,7 @@ ACCELERATE_TIMEOUT: version: "2.5" alternatives: ssh and paramiko ALLOW_WORLD_READABLE_TMPFILES: + name: Allow world readable temporary files default: False description: - This makes the temporary files created on the machine to be world readable and will issue a warning instead of failing the task. @@ -108,45 +109,50 @@ ALLOW_WORLD_READABLE_TMPFILES: yaml: {key: defaults.allow_world_readable_tmpfiles} version_added: "2.1" ANSIBLE_COW_SELECTION: + name: Cowsay filter selection default: default description: This allows you to chose a specific cowsay stencil for the banners or use 'random' to cycle through them. env: [{name: ANSIBLE_COW_SELECTION}] ini: - {key: cow_selection, section: defaults} - yaml: {key: defaults.cow_selection} ANSIBLE_COW_WHITELIST: + name: Cowsay filter whitelist default: ['bud-frogs', 'bunny', 'cheese', 'daemon', 'default', 'dragon', 'elephant-in-snake', 'elephant', 'eyes', 'hellokitty', 'kitty', 'luke-koala', 'meow', 'milk', 'moofasa', 'moose', 'ren', 'sheep', 'small', 'stegosaurus', 'stimpy', 'supermilker', 'three-eyes', 'turkey', 'turtle', 'tux', 'udder', 'vader-koala', 'vader', 'www'] description: White list of cowsay templates that are 'safe' to use, set to empty list if you want to enable all installed templates. env: [{name: ANSIBLE_COW_WHITELIST}] ini: - {key: cow_whitelist, section: defaults} type: list - yaml: {key: defaults.cow_whitelist} + yaml: {key: display.cowsay_whitelist} ANSIBLE_FORCE_COLOR: + name: Force color output default: False - description: This options forces color mode even when running without a TTY + description: This options forces color mode even when running without a TTY or the "nocolor" setting is True. env: [{name: ANSIBLE_FORCE_COLOR}] ini: - {key: force_color, section: defaults} type: boolean - yaml: {key: defaults.force_color} + yaml: {key: display.force_color} ANSIBLE_NOCOLOR: + name: Suppress color output default: False description: This setting allows suppressing colorizing output, which is used to give a better indication of failure and status information. env: [{name: ANSIBLE_NOCOLOR}] ini: - {key: nocolor, section: defaults} type: boolean - yaml: {key: defaults.nocolor} + yaml: {key: display.nocolor} ANSIBLE_NOCOWS: + name: Suppress cowsay output default: False description: If you have cowsay installed but want to avoid the 'cows' (why????), use this. env: [{name: ANSIBLE_NOCOWS}] ini: - {key: nocows, section: defaults} type: boolean - yaml: {key: defaults.nocows} + yaml: {key: display.i_am_no_fun} ANSIBLE_PIPELINING: + name: Connection pipelining default: False description: - Pipelining, if supported by the connection plugin, reduces the number of network operations required to execute a module on the remote server, @@ -160,6 +166,7 @@ ANSIBLE_PIPELINING: type: boolean yaml: {key: plugins.connection.pipelining} ANSIBLE_SSH_ARGS: + # TODO: move to ssh plugin default: -C -o ControlMaster=auto -o ControlPersist=60s description: - If set, this will override the Ansible default ssh arguments. @@ -192,6 +199,7 @@ ANSIBLE_SSH_CONTROL_PATH_DIR: - {key: control_path_dir, section: ssh_connection} yaml: {key: ssh_connection.control_path_dir} ANSIBLE_SSH_EXECUTABLE: + # TODO: move to ssh plugin default: ssh description: - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH. @@ -203,6 +211,7 @@ ANSIBLE_SSH_EXECUTABLE: yaml: {key: ssh_connection.ssh_executable} version_added: "2.2" ANSIBLE_SSH_PIPELINING: + # TODO: move to ssh plugin default: False description: - Pipelining reduces the number of SSH operations required to execute a module on the remote server, @@ -215,104 +224,116 @@ ANSIBLE_SSH_PIPELINING: type: boolean yaml: {key: ssh_connection.pipelining} ANSIBLE_SSH_RETRIES: + # TODO: move to ssh plugin default: 0 - description: 'TODO: write it' + description: Number of attempts to establish a connection before we give up and report the host as 'UNREACHABLE' env: [{name: ANSIBLE_SSH_RETRIES}] ini: - {key: retries, section: ssh_connection} type: integer yaml: {key: ssh_connection.retries} ANY_ERRORS_FATAL: + name: Make Task failures fatal default: False - description: Sets the default value for the any_errors_fatal keyword + description: Sets the default value for the any_errors_fatal keyword, if True, Task failures will be considered fatal errors. env: - name: ANSIBLE_ANY_ERRORS_FATAL ini: - section: defaults key: any_errors_fatal type: boolean - yaml: {key: errors.anyerrors_fatal} + yaml: {key: errors.any_task_errors_fatal} version_added: "2.4" BECOME_ALLOW_SAME_USER: + name: Allow becomming the same user default: False - description: This setting controls if become is skipped when remote user and become user are the same. + description: This setting controls if become is skipped when remote user and become user are the same. I.E root sudo to root. env: [{name: ANSIBLE_BECOME_ALLOW_SAME_USER}] ini: - {key: become_allow_same_user, section: privilege_escalation} type: boolean yaml: {key: privilege_escalation.become_allow_same_user} CACHE_PLUGIN: + name: Persistent Cache plugin default: memory - description: Chooses which cache plugin to use + description: Chooses which cache plugin to use, the default 'memory' is ephimeral. env: [{name: ANSIBLE_CACHE_PLUGIN}] ini: - {key: fact_caching, section: defaults} - yaml: {key: defaults.fact_caching} + yaml: {key: facts.cache.plugin} CACHE_PLUGIN_CONNECTION: - default: + name: Cache Plugin URI + default: ~ description: Defines connection or path information for the cache plugin env: [{name: ANSIBLE_CACHE_PLUGIN_CONNECTION}] ini: - {key: fact_caching_connection, section: defaults} - yaml: {key: defaults.fact_caching_connection} + yaml: {key: facts.cache.uri} CACHE_PLUGIN_PREFIX: + name: Cache Plugin table prefix default: ansible_facts description: Prefix to use for cache plugin files/tables env: [{name: ANSIBLE_CACHE_PLUGIN_PREFIX}] ini: - {key: fact_caching_prefix, section: defaults} - yaml: {key: defaults.fact_caching_prefix} + yaml: {key: facts.cache.prefix} CACHE_PLUGIN_TIMEOUT: + name: Cache Plugin expiration timeout default: 86400 description: Expiration timeout for the cache plugin data env: [{name: ANSIBLE_CACHE_PLUGIN_TIMEOUT}] ini: - {key: fact_caching_timeout, section: defaults} type: integer - yaml: {key: defaults.fact_caching_timeout} + yaml: {key: facts.cache.timeout} COLOR_CHANGED: + name: Color for 'changed' task status default: yellow - description: Defines the color to use on 'Changed' status + description: Defines the color to use on 'Changed' task status env: [{name: ANSIBLE_COLOR_CHANGED}] ini: - {key: changed, section: colors} yaml: {key: display.colors.changed} COLOR_DEBUG: + name: Color for debug statements default: dark gray description: Defines the color to use when emitting debug messages env: [{name: ANSIBLE_COLOR_DEBUG}] ini: - {key: debug, section: colors} - yaml: {key: colors.debug} + yaml: {key: display.colors.debug} COLOR_DEPRECATE: + name: Color for deprecation messages default: purple description: Defines the color to use when emitting deprecation messages env: [{name: ANSIBLE_COLOR_DEPRECATE}] ini: - {key: deprecate, section: colors} - yaml: {key: colors.deprecate} + yaml: {key: display.colors.deprecate} COLOR_DIFF_ADD: + name: Color for diff added display default: green description: Defines the color to use when showing added lines in diffs env: [{name: ANSIBLE_COLOR_DIFF_ADD}] ini: - {key: diff_add, section: colors} - yaml: {key: colors.diff_add} + yaml: {key: display.colors.diff.add} COLOR_DIFF_LINES: + name: Color for diff lines display default: cyan description: Defines the color to use when showing diffs env: [{name: ANSIBLE_COLOR_DIFF_LINES}] ini: - {key: diff_lines, section: colors} - yaml: {key: colors.diff_lines} COLOR_DIFF_REMOVE: + name: Color for diff removed display default: red description: Defines the color to use when showing removed lines in diffs env: [{name: ANSIBLE_COLOR_DIFF_REMOVE}] ini: - {key: diff_remove, section: colors} - yaml: {key: colors.diff_remove} COLOR_ERROR: + name: Color for error messages default: red description: Defines the color to use when emitting error messages env: [{name: ANSIBLE_COLOR_ERROR}] @@ -320,432 +341,533 @@ COLOR_ERROR: - {key: error, section: colors} yaml: {key: colors.error} COLOR_HIGHLIGHT: + name: Color for highlighting default: white - description: 'TODO: write it' + description: Color used for highlights env: [{name: ANSIBLE_COLOR_HIGHLIGHT}] ini: - {key: highlight, section: colors} - yaml: {key: colors.highlight} COLOR_OK: + name: Color for 'ok' task status default: green - description: Defines the color to use when showing 'OK' status + description: Defines the color to use when showing 'OK' task status env: [{name: ANSIBLE_COLOR_OK}] ini: - {key: ok, section: colors} - yaml: {key: colors.ok} COLOR_SKIP: + name: Color for 'skip' task status default: cyan - description: Defines the color to use when showing 'Skipped' status + description: Defines the color to use when showing 'Skipped' task status env: [{name: ANSIBLE_COLOR_SKIP}] ini: - {key: skip, section: colors} - yaml: {key: colors.skip} COLOR_UNREACHABLE: + name: Color for 'unreachable' host state default: bright red description: Defines the color to use on 'Unreachable' status env: [{name: ANSIBLE_COLOR_UNREACHABLE}] ini: - {key: unreachable, section: colors} - yaml: {key: colors.unreachable} COLOR_VERBOSE: + name: Color for verbose messages default: blue - description: Defines the color to use when emitting verbose messages + description: Defines the color to use when emitting verbose messages. i.e those that show with '-v's. env: [{name: ANSIBLE_COLOR_VERBOSE}] ini: - {key: verbose, section: colors} - yaml: {key: colors.verbose} COLOR_WARN: + name: Color for warning messages default: bright purple description: Defines the color to use when emitting warning messages env: [{name: ANSIBLE_COLOR_WARN}] ini: - {key: warn, section: colors} - yaml: {key: colors.warn} COMMAND_WARNINGS: + name: Command module warnings default: True - description: 'TODO: write it' + description: + - By default 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. + - These warnings can be silenced by adjusting this setting to False. You can also control this at the task level with the module optoin ``warn``. env: [{name: ANSIBLE_COMMAND_WARNINGS}] ini: - {key: command_warnings, section: defaults} type: boolean - yaml: {key: defaults.command_warnings} + version_added: "1.8" DEFAULT_ACTION_PLUGIN_PATH: + name: Action plugins path default: ~/.ansible/plugins/action:/usr/share/ansible/plugins/action description: Colon separated paths in which Ansible will search for Action Plugins. env: [{name: ANSIBLE_ACTION_PLUGINS}] ini: - {key: action_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.action_plugins} + type: pathspec + yaml: {key: plugins.action.path} DEFAULT_ALLOW_UNSAFE_LOOKUPS: + name: Allow unsafe lookups default: False - description: 'TODO: write it' + description: + - 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 late env: [] ini: - {key: allow_unsafe_lookups, section: defaults} type: boolean - yaml: {key: defaults.allow_unsafe_lookups} + version_added: "2.2.3" DEFAULT_ASK_PASS: + name: Ask for the login password default: False - description: 'TODO: write it' + description: + - This controls whether an Ansible playbook should prompt for a login password. + If using SSH keys for authentication, you probably do not needed to change this setting. env: [{name: ANSIBLE_ASK_PASS}] ini: - {key: ask_pass, section: defaults} type: boolean yaml: {key: defaults.ask_pass} DEFAULT_ASK_SUDO_PASS: + name: Ask for the sudo password default: False deprecated: why: In favor of become which is a generic framework version: "2.8" alternatives: become - description: 'TODO: write it' + description: + - This controls whether an Ansible playbook should prompt for a sudo password. env: [{name: ANSIBLE_ASK_SUDO_PASS}] ini: - {key: ask_sudo_pass, section: defaults} type: boolean DEFAULT_ASK_SU_PASS: + name: Ask for the su password default: False deprecated: why: In favor of become which is a generic framework version: "2.8" alternatives: become - description: 'TODO: write it' + description: + - This controls whether an Ansible playbook should prompt for a su password. env: [{name: ANSIBLE_ASK_SU_PASS}] ini: - {key: ask_su_pass, section: defaults} type: boolean DEFAULT_ASK_VAULT_PASS: + name: Ask for the vault password(s) default: False - description: 'TODO: write it' + description: + - This controls whether an Ansible playbook should prompt for a vault password. env: [{name: ANSIBLE_ASK_VAULT_PASS}] ini: - {key: ask_vault_pass, section: defaults} type: boolean - yaml: {key: defaults.ask_vault_pass} DEFAULT_BECOME: + name: Enable privilege escalation (become) default: False description: Toggles the use of privilege escalation, allowing you to 'become' another user after login. env: [{name: ANSIBLE_BECOME}] ini: - {key: become, section: privilege_escalation} type: boolean - yaml: {key: privilege_escalation.become} DEFAULT_BECOME_ASK_PASS: + name: Ask for the privelege escalation (become) password default: False description: Toggle to prompt for privilege escalation password. env: [{name: ANSIBLE_BECOME_ASK_PASS}] ini: - {key: become_ask_pass, section: privilege_escalation} type: boolean - yaml: {key: privilege_escalation.become_ask_pass} DEFAULT_BECOME_METHOD: + name: Choose privilege escalation method default: 'sudo' description: Privilege escalation method to use when `become` is enabled. env: [{name: ANSIBLE_BECOME_METHOD}] ini: - {section: privilege_escalation, key: become_method} - yaml: {key: privilege_escalation.become_method} DEFAULT_BECOME_EXE: + name: Choose 'become' executable default: ~ description: 'executable to use for privilege escalation, otherwise Ansible will depend on PATh' env: [{name: ANSIBLE_BECOME_EXE}] ini: - {key: become_exe, section: privilege_escalation} - yaml: {key: privilege_escalation.become_exe} DEFAULT_BECOME_FLAGS: + name: Set 'become' executable options default: ~ description: Flags to pass to the privilege escalation executable. env: [{name: ANSIBLE_BECOME_FLAGS}] ini: - {key: become_flags, section: privilege_escalation} - yaml: {key: privilege_escalation.become_flags} DEFAULT_BECOME_USER: + # FIXME: should really be blank and make -u passing optional depending on it + name: Set the user you 'become' via privlege escalation default: root - description: User your become when using privilege escalation, most systems will use 'root' when no user is specified. + description: The user your login/remote user 'becomes' when using privilege escalation, most systems will use 'root' when no user is specified. env: [{name: ANSIBLE_BECOME_USER}] ini: - {key: become_user, section: privilege_escalation} - yaml: {key: privilege_escalation.become_user} + yaml: {key: become.user} DEFAULT_CACHE_PLUGIN_PATH: + name: Cache Plugins Path default: ~/.ansible/plugins/cache:/usr/share/ansible/plugins/cache - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Cache Plugins. env: [{name: ANSIBLE_CACHE_PLUGINS}] ini: - {key: cache_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.cache_plugins} + type: pathspec DEFAULT_CALLABLE_WHITELIST: + name: Template 'callable' whitelist default: [] - description: 'TODO: write it' + description: Whitelist of callable methods to be made available to template evaluation env: [{name: ANSIBLE_CALLABLE_WHITELIST}] ini: - {key: callable_whitelist, section: defaults} type: list - yaml: {key: defaults.callable_whitelist} DEFAULT_CALLBACK_PLUGIN_PATH: + name: Callback Plugins Path default: ~/.ansible/plugins/callback:/usr/share/ansible/plugins/callback - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Callback Plugins. env: [{name: ANSIBLE_CALLBACK_PLUGINS}] ini: - {key: callback_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.callback_plugins} + type: pathspec + yaml: {key: plugins.callback.path} DEFAULT_CALLBACK_WHITELIST: + name: Callback Whitelist default: [] - description: 'TODO: write it' + description: + - List of whitelisted callbacks, not all callbacks need whitelisting, + but many of those shipped with Ansible do as we don't want them activated by default. env: [{name: ANSIBLE_CALLBACK_WHITELIST}] ini: - {key: callback_whitelist, section: defaults} type: list - yaml: {key: defaults.callback_whitelist} + yaml: {key: plugins.callback.whitelist} DEFAULT_CONNECTION_PLUGIN_PATH: + name: Connection Plugins Path default: ~/.ansible/plugins/connection:/usr/share/ansible/plugins/connection - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Connection Plugins. env: [{name: ANSIBLE_CONNECTION_PLUGINS}] ini: - {key: connection_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.connection_plugins} + type: pathspec + yaml: {key: plugins.connection.path} DEFAULT_DEBUG: + name: Debug mode default: False description: Toggles debug output in Ansible, VERY verbose and can hinder multiprocessing. env: [{name: ANSIBLE_DEBUG}] ini: - {key: debug, section: defaults} type: boolean - yaml: {key: defaults.debug} DEFAULT_EXECUTABLE: + name: Target shell executable default: /bin/sh - description: 'TODO: write it' + description: + - This indicates the command to use to spawn a shell under for Ansible's execution needs on a target. + Users may need to change this in rare instances when shell usage is constrained, but in most cases it may be left as is. env: [{name: ANSIBLE_EXECUTABLE}] ini: - {key: executable, section: defaults} - yaml: {key: defaults.executable} DEFAULT_FACT_PATH: - default: - description: 'TODO: write it' + name: local fact path + default: ~ + description: + - This option allows you to globally configure a custom path for 'local_facts' for the implied M(setup) task when using fact gathering. + - "If not set, it will fallback to the default from the M(setup) module: ``/etc/ansible/facts.d``." + - This does **not ** affect user defined tasks that use the M(setup) module. env: [{name: ANSIBLE_FACT_PATH}] ini: - {key: fact_path, section: defaults} type: path - yaml: {key: defaults.fact_path} + yaml: {key: facts.gathering.fact_path} DEFAULT_FILTER_PLUGIN_PATH: + name: Jinja2 Filter Plugins Path default: ~/.ansible/plugins/filter:/usr/share/ansible/plugins/filter - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Jinja2 Filter Plugins. env: [{name: ANSIBLE_FILTER_PLUGINS}] ini: - {key: filter_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.filter_plugins} + type: pathspec DEFAULT_FORCE_HANDLERS: + name: Force handlers to run after failure default: False - description: 'TODO: write it' + description: + - This option controls if notified handlers run on a host even if a failure occurs on that host. + - When false, the 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 Handlers and Failure for more details. env: [{name: ANSIBLE_FORCE_HANDLERS}] ini: - {key: force_handlers, section: defaults} type: boolean - yaml: {key: defaults.force_handlers} + version_added: "1.9.1" DEFAULT_FORKS: + name: Number of task forks default: 5 description: Maximum number of forks Ansible will use to execute tasks on target hosts. env: [{name: ANSIBLE_FORKS}] ini: - {key: forks, section: defaults} type: integer - yaml: {key: defaults.forks} DEFAULT_GATHERING: - default: 'implicit' - description: 'TODO: write it' - env: [{name: ANSIBLE_GATHERING}] - ini: - - key: gathering - section: defaults - yaml: {key: defaults.gathering} + name: Gathering behaviour + default: 'implicit' + description: + - This setting controls the default policy of fact gathering (facts discovered about remote systems). + - "When ‘implicit’ (the default), the cache plugin will be ignored and facts will be gathered per play unless ‘gather_facts: False’ is set." + - When ‘explicit’ the inverse is true, facts will not be gathered unless directly requested in the play. + - The ‘smart’ value 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 cache plugin. + env: [{name: ANSIBLE_GATHERING}] + ini: + - key: gathering + section: defaults + version_added: "1.6" + choices: ['smart', 'explicit', 'implicit'] DEFAULT_GATHER_SUBSET: - default: 'all' - description: 'TODO: write it' - env: [{name: ANSIBLE_GATHER_SUBSET}] - ini: - - key: gather_subset - section: defaults - yaml: {key: defaults.gather_subset} + name: Gather facts subset + default: 'all' + description: + - Set the `gather_subset` option for the M(setup) task in the implicit fact gathering. + See the module documentation for specifics. + - It does **not** apply to user defined M(setup) tasks. + env: [{name: ANSIBLE_GATHER_SUBSET}] + ini: + - key: gather_subset + section: defaults + version_added: "2.1" DEFAULT_GATHER_TIMEOUT: + name: Gather facts timeout default: 10 - description: 'TODO: write it' + description: + - Set the timeout in seconds for the implicit fact gathering. + - It does **not** apply to user defined M(setup) tasks. env: [{name: ANSIBLE_GATHER_TIMEOUT}] ini: - {key: gather_timeout, section: defaults} type: integer yaml: {key: defaults.gather_timeout} DEFAULT_HANDLER_INCLUDES_STATIC: + name: Make handler M(include) static default: False - description: 'TODO: write it' + description: + - Since 2.0 M(include) can be 'dynamic', this setting (if True) forces that if the include appears in a ``handlers`` section to be 'static'. env: [{name: ANSIBLE_HANDLER_INCLUDES_STATIC}] ini: - {key: handler_includes_static, section: defaults} type: boolean - yaml: {key: defaults.handler_includes_static} deprecated: why: include itself is deprecated and this setting will not matter in the future version: "2.8" alternatives: none as its already built into the decision between include_tasks and import_tasks DEFAULT_HASH_BEHAVIOUR: + name: Hash merge behaviour default: replace - description: 'TODO: write it' + type: string + choices: [‘replace’, ‘merge’] + description: + - This setting controls how variables merge in Ansible. + By default Ansible will override variables in specific precedence orders, as described in 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 + - In version 2.0 a ``combine`` filter was added to allow doing this for a particular variable (described in Filters). env: [{name: ANSIBLE_HASH_BEHAVIOUR}] ini: - {key: hash_behaviour, section: defaults} - yaml: {key: defaults.hash_behaviour} DEFAULT_HOST_LIST: + name: Inventory Source default: /etc/ansible/hosts - description: Location of the Ansible inventory source. - env: [{name: ANSIBLE_INVENTORY}] + description: Colon separated list of Ansible inventory sources + env: + - name: ANSIBLE_HOSTS + deprecated: + why: The variable is misleading as it can be a list of hosts and/or paths to inventory sources + version: "2.8" + alternatives: ANSIBLE_INVENTORY + - name: ANSIBLE_INVENTORY expand_relative_paths: True ini: - - {key: inventory, section: defaults} + - key: hostfile + section: defaults + deprecated: + why: The key is misleading as it can also be a list of hosts, a directory or a list of paths + version: "2.8" + alternatives: inventory + - key: inventory + section: defaults type: pathlist yaml: {key: defaults.inventory} DEFAULT_INTERNAL_POLL_INTERVAL: + name: Internal poll interval default: 0.001 - description: 'TODO: write it' env: [] ini: - {key: internal_poll_interval, section: defaults} type: float - yaml: {key: defaults.internal_poll_interval} + version_added: "2.2" + description: + - 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. + - The default corresponds to the value hardcoded in Ansible ≤ 2.1 DEFAULT_INVENTORY_PLUGIN_PATH: + name: Inventory Plugins Path default: ~/.ansible/plugins/inventory:/usr/share/ansible/plugins/inventory - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Inventory Plugins. env: [{name: ANSIBLE_INVENTORY_PLUGINS}] ini: - {key: inventory_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.inventory_plugins} + type: pathspec DEFAULT_JINJA2_EXTENSIONS: - default: - description: 'TODO: write it' + name: Enabled Jinja2 extensions + default: [] + description: + - This is a developer-specific feature that allows enabling additional Jinja2 extensions. + - See the Jinja2 documentation for details. If you do not know what these do, you probably don’t need to change this setting :) env: [{name: ANSIBLE_JINJA2_EXTENSIONS}] ini: - {key: jinja2_extensions, section: defaults} - yaml: {key: defaults.jinja2_extensions} DEFAULT_KEEP_REMOTE_FILES: + name: Keep remote files default: False description: Enables/disables the cleaning up of the temporary files Ansible used to execute the tasks on the remote. env: [{name: ANSIBLE_KEEP_REMOTE_FILES}] ini: - {key: keep_remote_files, section: defaults} type: boolean - yaml: {key: defaults.keep_remote_files} DEFAULT_LIBVIRT_LXC_NOSECLABEL: + # TODO: move to plugin + name: No security label on Lxc default: False - description: 'TODO: write it' + description: + - 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. env: [{name: LIBVIRT_LXC_NOSECLABEL}] ini: - {key: libvirt_lxc_noseclabel, section: selinux} type: boolean - yaml: {key: selinux.libvirt_lxc_noseclabel} + version_added: "2.1" DEFAULT_LOAD_CALLBACK_PLUGINS: + name: Load callbacks for adhoc default: False - description: 'TODO: write it' + description: + - 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 ``ansible-playbook``. env: [{name: ANSIBLE_LOAD_CALLBACK_PLUGINS}] ini: - {key: bin_ansible_callbacks, section: defaults} type: boolean - yaml: {key: defaults.bin_ansible_callbacks} + version_added: "1.8" DEFAULT_LOCAL_TMP: + name: Controller temporary directory default: ~/.ansible/tmp description: Temporary directory for Ansible to use on the controller. env: [{name: ANSIBLE_LOCAL_TEMP}] ini: - {key: local_tmp, section: defaults} type: tmppath - yaml: {key: defaults.local_tmp} DEFAULT_LOG_PATH: + name: Ansible log file path default: '' description: File to which Ansible will log on the controller. When empty logging is disabled. env: [{name: ANSIBLE_LOG_PATH}] ini: - {key: log_path, section: defaults} type: path - yaml: {key: defaults.log_path} DEFAULT_LOOKUP_PLUGIN_PATH: + name: Lookup Plugins Path + description: Colon separated paths in which Ansible will search for Lookup Plugins. default: ~/.ansible/plugins/lookup:/usr/share/ansible/plugins/lookup - description: 'TODO: write it' env: [{name: ANSIBLE_LOOKUP_PLUGINS}] ini: - {key: lookup_plugins, section: defaults} - type: pathlist + type: pathspec yaml: {key: defaults.lookup_plugins} DEFAULT_MANAGED_STR: - default: Ansible managed - description: Sets the macro for the 'ansible_managed' variable available for 'tempalte' tasks. + name: Ansible managed + default: 'Ansible managed' + description: Sets the macro for the 'ansible_managed' variable available for M(template) tasks. env: [] ini: - {key: ansible_managed, section: defaults} yaml: {key: defaults.ansible_managed} DEFAULT_MODULE_ARGS: + name: Adhoc default arguments default: '' - description: 'TODO: write it' + description: + - This sets the default arguments to pass to the ``ansible`` adhoc binary if no ``-a`` is specified. env: [{name: ANSIBLE_MODULE_ARGS}] ini: - {key: module_args, section: defaults} - yaml: {key: defaults.module_args} DEFAULT_MODULE_COMPRESSION: + name: Python module compression default: ZIP_DEFLATED - description: 'TODO: write it' + description: Compression scheme to use when transfering Python modules to the target. env: [] ini: - {key: module_compression, section: defaults} - yaml: {key: defaults.module_compression} +# vars: +# - name: ansible_module_compression DEFAULT_MODULE_LANG: - # TODO: allow setting to function: os.getenv('LANG', 'en_US.UTF-8') + name: Target language environment default: eval(os.getenv('LANG', 'en_US.UTF-8')) description: "Language locale setting to use for modules when they execute on the target, if empty it defaults to 'en_US.UTF-8'" env: [{name: ANSIBLE_MODULE_LANG}] ini: - {key: module_lang, section: defaults} - yaml: {key: defaults.module_lang} +# vars: +# - name: ansible_module_lang DEFAULT_MODULE_NAME: + name: Default adhoc module default: command - description: Module to use with the `ansible` AdHoc command, if none is specified. + description: Module to use with the ``ansible`` AdHoc command, if none is specified via ``-m``. env: [] ini: - {key: module_name, section: defaults} - yaml: {key: defaults.module_name} DEFAULT_MODULE_PATH: + name: Modules Path + description: Colon separated paths in which Ansible will search for Modules. default: ~/.ansible/plugins/modules:/usr/share/ansible/plugins/modules - description: 'TODO: write it' env: [{name: ANSIBLE_LIBRARY}] ini: - {key: library, section: defaults} - type: pathlist - yaml: {key: defaults.library} + type: pathspec DEFAULT_MODULE_SET_LOCALE: + name: Target locale default: False description: Controls if we set locale for modules when executing on the target. env: [{name: ANSIBLE_MODULE_SET_LOCALE}] ini: - {key: module_set_locale, section: defaults} type: boolean - yaml: {key: defaults.module_set_locale} +# vars: +# - name: ansible_module_locale DEFAULT_MODULE_UTILS_PATH: + name: Module Utils Path + description: Colon separated paths in which Ansible will search for Module utils files, which are shared by modules. default: ~/.ansible/plugins/module_utils:/usr/share/ansible/plugins/module_utils - description: 'TODO: write it' env: [{name: ANSIBLE_MODULE_UTILS}] ini: - {key: module_utils, section: defaults} - type: pathlist - yaml: {key: defaults.module_utils} + type: pathspec DEFAULT_NO_LOG: + name: No log default: False description: Toggle Ansible's display and logging of task details, mainly used to avoid security disclosures. env: [{name: ANSIBLE_NO_LOG}] ini: - {key: no_log, section: defaults} type: boolean - yaml: {key: defaults.no_log} DEFAULT_NO_TARGET_SYSLOG: + name: No syslog on target default: False description: Toggle Ansbile logging to syslog on the target when it executes tasks. env: [{name: ANSIBLE_NO_TARGET_SYSLOG}] @@ -754,39 +876,47 @@ DEFAULT_NO_TARGET_SYSLOG: type: boolean yaml: {key: defaults.no_target_syslog} DEFAULT_NULL_REPRESENTATION: - default: - description: 'TODO: write it' + name: Represent a null + default: ~ + description: What templating should return as a 'null' value. When not set it will let Jinja2 decide. env: [{name: ANSIBLE_NULL_REPRESENTATION}] ini: - {key: null_representation, section: defaults} type: none - yaml: {key: defaults.null_representation} DEFAULT_POLL_INTERVAL: + name: Async poll interval default: 15 - description: 'TODO: write it' + description: + - For asynchronous tasks in Ansible (covered in Asynchronous Actions and Polling), + 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. env: [{name: ANSIBLE_POLL_INTERVAL}] ini: - {key: poll_interval, section: defaults} type: integer - yaml: {key: defaults.poll_interval} DEFAULT_PRIVATE_KEY_FILE: - default: - description: 'TODO: write it' + name: Private key file + default: ~ + description: + - Option for connections using a certificate or key file to authenticate, rather than an agent or passwords, + you can set the default value here to avoid re-specifying --private-key with every invocation. env: [{name: ANSIBLE_PRIVATE_KEY_FILE}] ini: - {key: private_key_file, section: defaults} type: path - yaml: {key: defaults.private_key_file} DEFAULT_PRIVATE_ROLE_VARS: + name: Private role variables default: False - description: 'TODO: write it' + description: '' env: [{name: ANSIBLE_PRIVATE_ROLE_VARS}] ini: - {key: private_role_vars, section: defaults} type: boolean yaml: {key: defaults.private_role_vars} DEFAULT_REMOTE_PORT: - default: + name: Remote port + default: ~ description: Port to use in remote connections, when blank it will use the connection plugin default. env: [{name: ANSIBLE_REMOTE_PORT}] ini: @@ -794,6 +924,7 @@ DEFAULT_REMOTE_PORT: type: integer yaml: {key: defaults.remote_port} DEFAULT_REMOTE_TMP: + name: Target temporary directory default: ~/.ansible/tmp description: - Temporary directory to use on targets when executing tasks. @@ -803,8 +934,8 @@ DEFAULT_REMOTE_TMP: - {key: remote_tmp, section: defaults} vars: - name: ansible_remote_tmp - yaml: {key: defaults.remote_tmp} DEFAULT_REMOTE_USER: + name: Login/Remote User default: description: - Sets the login user for the target machines @@ -812,17 +943,18 @@ DEFAULT_REMOTE_USER: env: [{name: ANSIBLE_REMOTE_USER}] ini: - {key: remote_user, section: defaults} - yaml: {key: defaults.remote_user} DEFAULT_ROLES_PATH: + name: Roles path default: ~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Roles. env: [{name: ANSIBLE_ROLES_PATH}] expand_relative_paths: True ini: - {key: roles_path, section: defaults} - type: pathlist + type: pathspec yaml: {key: defaults.roles_path} DEFAULT_SCP_IF_SSH: + # TODO: move to ssh plugin default: smart description: - "Prefered method to use when transfering files over ssh" @@ -831,20 +963,19 @@ DEFAULT_SCP_IF_SSH: env: [{name: ANSIBLE_SCP_IF_SSH}] ini: - {key: scp_if_ssh, section: ssh_connection} - yaml: {key: ssh_connection.scp_if_ssh} DEFAULT_SELINUX_SPECIAL_FS: + name: Problematic file systems default: fuse, nfs, vboxsf, ramfs, 9p description: - "Some filesystems do not support safe operations and/or return inconsistent errors, this setting makes Ansible 'tolerate' those in the list w/o causing fatal errors." - Data corruption may occur and writes are not always verified when a filesystem is in the list. - env: [] ini: - {key: special_context_filesystems, section: selinux} type: list - yaml: {key: selinux.special_context_filesystems} DEFAULT_SFTP_BATCH_MODE: + # TODO: move to ssh plugin default: True description: 'TODO: write it' env: [{name: ANSIBLE_SFTP_BATCH_MODE}] @@ -853,6 +984,7 @@ DEFAULT_SFTP_BATCH_MODE: type: boolean yaml: {key: ssh_connection.sftp_batch_mode} DEFAULT_SQUASH_ACTIONS: + name: Squashable actions default: apk, apt, dnf, homebrew, openbsd_pkg, pacman, pkgng, yum, zypper description: - Ansible can optimise actions that call modules that support list parameters when using with_ looping. @@ -863,9 +995,9 @@ DEFAULT_SQUASH_ACTIONS: ini: - {key: squash_actions, section: defaults} type: list - yaml: {key: defaults.squash_actions} version_added: "2.0" DEFAULT_SSH_TRANSFER_METHOD: + # TODO: move to ssh plugin default: description: 'unused?' # - "Prefered method to use when transfering files over ssh" @@ -874,8 +1006,8 @@ DEFAULT_SSH_TRANSFER_METHOD: env: [{name: ANSIBLE_SSH_TRANSFER_METHOD}] ini: - {key: transfer_method, section: ssh_connection} - yaml: {key: ssh_connection.transfer_method} DEFAULT_STDOUT_CALLBACK: + name: Main display callback plugin default: default description: - "Set the main callback used to display Ansible output, you can only have one at a time." @@ -883,23 +1015,22 @@ DEFAULT_STDOUT_CALLBACK: env: [{name: ANSIBLE_STDOUT_CALLBACK}] ini: - {key: stdout_callback, section: defaults} - yaml: {key: defaults.stdout_callback} DEFAULT_STRATEGY: + name: Implied strategy default: 'linear' description: Set the default strategy used for plays. env: [{name: ANSIBLE_STRATEGY}] ini: - {key: strategy, section: defaults} - yaml: {key: defaults.strategy} version_added: "2.3" DEFAULT_STRATEGY_PLUGIN_PATH: + name: Strategy Plugins Path + description: Colon separated paths in which Ansible will search for Strategy Plugins. default: ~/.ansible/plugins/strategy:/usr/share/ansible/plugins/strategy - description: 'TODO: write it' env: [{name: ANSIBLE_STRATEGY_PLUGINS}] ini: - {key: strategy_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.strategy_plugins} + type: pathspec DEFAULT_SU: default: False description: 'Toggle the use of "su" for tasks.' @@ -920,6 +1051,7 @@ DEFAULT_SUDO: - {key: sudo, section: defaults} type: boolean DEFAULT_SUDO_EXE: + name: sudo executable default: sudo deprecated: why: In favor of become which is a generic framework @@ -930,6 +1062,7 @@ DEFAULT_SUDO_EXE: ini: - {key: sudo_exe, section: defaults} DEFAULT_SUDO_FLAGS: + name: sudo flags default: '-H -S -n' deprecated: why: In favor of become which is a generic framework @@ -940,6 +1073,7 @@ DEFAULT_SUDO_FLAGS: ini: - {key: sudo_flags, section: defaults} DEFAULT_SUDO_USER: + name: sudo user default: deprecated: why: In favor of become which is a generic framework @@ -950,6 +1084,7 @@ DEFAULT_SUDO_USER: ini: - {key: sudo_user, section: defaults} DEFAULT_SU_EXE: + name: su executable default: su deprecated: why: In favor of become which is a generic framework @@ -960,6 +1095,7 @@ DEFAULT_SU_EXE: ini: - {key: su_exe, section: defaults} DEFAULT_SU_FLAGS: + name: su flags default: ~ deprecated: why: In favor of become which is a generic framework @@ -970,6 +1106,7 @@ DEFAULT_SU_FLAGS: ini: - {key: su_flags, section: defaults} DEFAULT_SU_USER: + name: su user default: description: 'User you become when using "su", leaving it blank will use the default configured on the target (normally root)' env: [{name: ANSIBLE_SU_USER}] @@ -980,72 +1117,79 @@ DEFAULT_SU_USER: version: "2.8" alternatives: become DEFAULT_SYSLOG_FACILITY: + name: syslog facility default: LOG_USER - description: 'TODO: write it' + description: Syslog facility to use when Ansible logs to the remote target env: [{name: ANSIBLE_SYSLOG_FACILITY}] ini: - {key: syslog_facility, section: defaults} - yaml: {key: defaults.syslog_facility} DEFAULT_TASK_INCLUDES_STATIC: + name: Task include static default: False - description: 'TODO: write it' + description: + - The `include` tasks can be static or dynamic, this toggles the default expected behaviour if autodetection fails and it is not explicitly set in task. env: [{name: ANSIBLE_TASK_INCLUDES_STATIC}] ini: - {key: task_includes_static, section: defaults} type: boolean - yaml: {key: defaults.task_includes_static} + version_added: "2.1" deprecated: why: include itself is deprecated and this setting will not matter in the future version: "2.8" alternatives: None, as its already built into the decision between include_tasks and import_tasks DEFAULT_TEST_PLUGIN_PATH: + name: Jinja2 Test Plugins Path + description: Colon separated paths in which Ansible will search for Jinja2 Test Plugins. default: ~/.ansible/plugins/test:/usr/share/ansible/plugins/test - description: 'TODO: write it' env: [{name: ANSIBLE_TEST_PLUGINS}] ini: - {key: test_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.test_plugins} + type: pathspec DEFAULT_TIMEOUT: + name: Connection timeout default: 10 - description: 'TODO: write it' + description: This is the default timeout for connection plugins to use. env: [{name: ANSIBLE_TIMEOUT}] ini: - {key: timeout, section: defaults} type: integer - yaml: {key: defaults.timeout} DEFAULT_TRANSPORT: + name: Connection plugin default: smart description: "Default connection plugin to use, the 'smart' option will toggle between 'ssh' and 'paramiko' depending on controller OS and ssh versions" env: [{name: ANSIBLE_TRANSPORT}] ini: - {key: transport, section: defaults} - yaml: {key: defaults.transport} DEFAULT_UNDEFINED_VAR_BEHAVIOR: + name: Jinja2 fail on undefined default: True - description: 'TODO: write it' + version_added: "1.3" + description: + - When True, this causes ansible templating to fail steps that reference variable names that are likely typoed. + - Otherwise, any ‘{{ template_expression }}’ that contains undefined variables will be rendered in a template or ansible action line exactly as written. env: [{name: ANSIBLE_ERROR_ON_UNDEFINED_VARS}] ini: - {key: error_on_undefined_vars, section: defaults} type: boolean - yaml: {key: defaults.error_on_undefined_vars} DEFAULT_VARS_PLUGIN_PATH: + name: Vars Plugins Path default: ~/.ansible/plugins/vars:/usr/share/ansible/plugins/vars - description: 'TODO: write it' + description: Colon separated paths in which Ansible will search for Vars Plugins. env: [{name: ANSIBLE_VARS_PLUGINS}] ini: - {key: vars_plugins, section: defaults} - type: pathlist - yaml: {key: defaults.vars_plugins} -DEFAULT_VAR_COMPRESSION_LEVEL: - default: 0 - description: 'TODO: write it' - env: [{name: ANSIBLE_VAR_COMPRESSION_LEVEL}] - ini: - - {key: var_compression_level, section: defaults} - type: integer - yaml: {key: defaults.var_compression_level} + type: pathspec +# TODO: unused? +#DEFAULT_VAR_COMPRESSION_LEVEL: +# default: 0 +# description: 'TODO: write it' +# env: [{name: ANSIBLE_VAR_COMPRESSION_LEVEL}] +# ini: +# - {key: var_compression_level, section: defaults} +# type: integer +# yaml: {key: defaults.var_compression_level} DEFAULT_VAULT_ID_MATCH: + name: Force vault id match default: False description: 'If true, decrypting vaults with a vault id will only try the password from the matching vault-id' env: [{name: ANSIBLE_VAULT_ID_MATCH}] @@ -1053,6 +1197,7 @@ DEFAULT_VAULT_ID_MATCH: - {key: vault_id_match, section: defaults} yaml: {key: defaults.vault_id_match} DEFAULT_VAULT_IDENTITY: + name: Vault id label default: default description: 'The label to use for the default vault id label in cases where a vault id label is not provided' env: [{name: ANSIBLE_VAULT_IDENTITY}] @@ -1060,6 +1205,7 @@ DEFAULT_VAULT_IDENTITY: - {key: vault_identity, section: defaults} yaml: {key: defaults.vault_identity} DEFAULT_VAULT_IDENTITY_LIST: + name: Default vault ids default: [] description: 'A list of vault-ids to use by default. Equivalent to multiple --vault-id args. Vault-ids are tried in order.' env: [{name: ANSIBLE_VAULT_IDENTITY_LIST}] @@ -1068,6 +1214,7 @@ DEFAULT_VAULT_IDENTITY_LIST: type: list yaml: {key: defaults.vault_identity_list} DEFAULT_VAULT_PASSWORD_FILE: + name: Vault password file default: ~ description: 'The vault password file to use. Equivalent to --vault-password-file or --vault-id' env: [{name: ANSIBLE_VAULT_PASSWORD_FILE}] @@ -1076,93 +1223,108 @@ DEFAULT_VAULT_PASSWORD_FILE: type: path yaml: {key: defaults.vault_password_file} DEFAULT_VERBOSITY: + name: Verbosity default: 0 - description: 'TODO: write it' + description: Sets the default verbosity, equivalent to the number of ``-v`` passed in the command line. env: [{name: ANSIBLE_VERBOSITY}] ini: - {key: verbosity, section: defaults} type: integer - yaml: {key: defaults.verbosity} DEPRECATION_WARNINGS: + name: Deprecation messages default: True description: "Toggle to control the showing of deprecation warnings" env: [{name: ANSIBLE_DEPRECATION_WARNINGS}] ini: - {key: deprecation_warnings, section: defaults} type: boolean - yaml: {key: defaults.deprecation_warnings} DIFF_ALWAYS: + name: Show differences default: False - description: 'TODO: write it' + description: Configuration toggle to tell modules to show differences when in 'changed' status, equivalent to ``--diff``. env: [{name: ANSIBLE_DIFF_ALWAYS}] ini: - {key: always, section: diff} type: bool - yaml: {key: diff.always} DIFF_CONTEXT: + name: Difference context default: 3 - description: 'TODO: write it' + description: How many lines of context to show when displaying the differences between files. env: [{name: ANSIBLE_DIFF_CONTEXT}] ini: - {key: context, section: diff} type: integer - yaml: {key: diff.context} DISPLAY_ARGS_TO_STDOUT: + name: Show task arguments default: False - description: 'TODO: write it' + description: + - "Normally ``ansible-playbook`` will print a header for each task that is run. + 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 + you do not want those to be printed. + - "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 How do I keep secret data in my playbook? for more information." env: [{name: ANSIBLE_DISPLAY_ARGS_TO_STDOUT}] ini: - {key: display_args_to_stdout, section: defaults} type: boolean - yaml: {key: defaults.display_args_to_stdout} + version_added: "2.1" DISPLAY_SKIPPED_HOSTS: + name: Show skipped results default: True - description: "Toggle to control displaying skipped host entries in a task in the default callback" + description: "Toggle to control displaying skipped task/host entries in a task in the default callback" env: [{name: DISPLAY_SKIPPED_HOSTS}] ini: - {key: display_skipped_hosts, section: defaults} type: boolean - yaml: {key: defaults.display_skipped_hosts} ERROR_ON_MISSING_HANDLER: + name: Missing handler error default: True description: "Toggle to allow missing handlers to become a warning instead of an error when notifying." env: [{name: ANSIBLE_ERROR_ON_MISSING_HANDLER}] ini: - {key: error_on_missing_handler, section: defaults} type: boolean - yaml: {key: defaults.error_on_missing_handler} GALAXY_IGNORE_CERTS: + name: Galaxy validate certs default: False - description: 'TODO: write it' + description: + - 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. env: [{name: ANSIBLE_GALAXY_IGNORE}] ini: - {key: ignore_certs, section: galaxy} type: boolean - yaml: {key: galaxy.ignore_certs} GALAXY_ROLE_SKELETON: + name: Galaxy skeleton direcotry default: - description: 'TODO: write it' + description: Role skeleton directory to use as a template for the ``init`` action in ``ansible-galaxy``, same as ``--role-skeleton``. env: [{name: ANSIBLE_GALAXY_ROLE_SKELETON}] ini: - {key: role_skeleton, section: galaxy} type: path - yaml: {key: galaxy.role_skeleton} GALAXY_ROLE_SKELETON_IGNORE: + name: Galaxy skeleton ignore default: [^.git$, ^.*/.git_keep$] - description: 'TODO: write it' + description: patterns of files to ignore inside a galaxy role skeleton directory env: [{name: ANSIBLE_GALAXY_ROLE_SKELETON_IGNORE}] ini: - {key: role_skeleton_ignore, section: galaxy} type: list - yaml: {key: galaxy.role_skeleton_ignore} -GALAXY_SCMS: - default: git, hg - description: 'TODO: write it' - env: [{name: ANSIBLE_GALAXY_SCMS}] - ini: - - {key: scms, section: galaxy} - type: list - yaml: {key: galaxy.scms} +# TODO: unused? +#GALAXY_SCMS: +# name: Galaxy SCMS +# default: git, hg +# description: Available galaxy source control management systems. +# env: [{name: ANSIBLE_GALAXY_SCMS}] +# ini: +# - {key: scms, section: galaxy} +# type: list GALAXY_SERVER: default: https://galaxy.ansible.com description: "URL to prepend when roles don't specify the full URI, assume they are referencing this server as the source." @@ -1171,6 +1333,7 @@ GALAXY_SERVER: - {key: server, section: galaxy} yaml: {key: galaxy.server} HOST_KEY_CHECKING: + name: Check host keys default: True description: 'Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host' env: [{name: ANSIBLE_HOST_KEY_CHECKING}] @@ -1178,6 +1341,7 @@ HOST_KEY_CHECKING: - {key: host_key_checking, section: defaults} type: boolean INVENTORY_ENABLED: + name: Active Inventory plugins default: ['host_list', 'script', 'yaml', 'ini'] description: List of enabled inventory plugins, it also determines the order in which they are used. env: [{name: ANSIBLE_INVENTORY_ENABLED}] @@ -1185,6 +1349,7 @@ INVENTORY_ENABLED: - {key: enable_plugins, section: inventory} type: list INVENTORY_IGNORE_EXTS: + name: Inventory ignore extensions default: eval(BLACKLIST_EXTS + ( '~', '.orig', '.ini', '.cfg', '.retry')) description: List of extensions to ignore when using a directory as an inventory source env: [{name: ANSIBLE_INVENTORY_IGNORE}] @@ -1193,6 +1358,7 @@ INVENTORY_IGNORE_EXTS: - {key: ignore_extensions, section: inventory} type: list INVENTORY_IGNORE_PATTERNS: + name: Inventory ignore patterns default: [] description: List of patterns to ignore when using a directory as an inventory source env: [{name: ANSIBLE_INVENTORY_IGNORE_REGEX}] @@ -1201,29 +1367,35 @@ INVENTORY_IGNORE_PATTERNS: - {key: ignore_patterns, section: inventory} type: list INVENTORY_UNPARSED_IS_FAILED: + name: Unparsed Inventory failure default: False description: If 'true' unparsed inventory sources become fatal errors, they are warnings otherwise. env: [{name: ANSIBLE_INVENTORY_UNPARSED_FAILED}] ini: - {key: unparsed_is_failed, section: inventory} - type: boolean + type: bool MAX_FILE_SIZE_FOR_DIFF: + name: Diff maxiumum file size default: 104448 description: Maximum size of files to be considered for diff display env: [{name: ANSIBLE_MAX_DIFF_SIZE}] ini: - {key: max_diff_size, section: defaults} - type: integer - yaml: {key: defaults.max_diff_size} + type: int MERGE_MULTIPLE_CLI_TAGS: + name: Merge 'tags' options default: True - description: 'TODO: write it' + description: + - "This allows changing how multiple –tags and –skip-tags arguments are handled on the command line. + In Ansible up to and including 2.3, specifying –tags more than once will only take the last value of –tags." + - "Setting this config value to True will mean that all of the –tags options will be merged together. The same holds true for –skip-tags." env: [{name: ANSIBLE_MERGE_MULTIPLE_CLI_TAGS}] ini: - {key: merge_multiple_cli_tags, section: defaults} - type: boolean - yaml: {key: defaults.merge_multiple_cli_tags} + type: bool + version_added: "2.3" NETWORK_GROUP_MODULES: + name: Network module families default: [eos, nxos, ios, iosxr, junos, ce, vyos, sros, dellos9, dellos10, dellos6, asa, aruba, aireos] description: 'TODO: write it' env: [{name: NETWORK_GROUP_MODULES}] @@ -1231,112 +1403,115 @@ NETWORK_GROUP_MODULES: - {key: network_group_modules, section: defaults} type: list yaml: {key: defaults.network_group_modules} -ONLY_NAMESPACE_FACTS: - default: False - description: - - Facts normally get injected as top level variables, this setting prevents that. - - Facts are still available in the `ansible_facts` variable w/o the `ansible_` prefix. - env: [{name: ANSIBLE_RESTRICT_FACTS}] - ini: - - {key: restrict_facts_namespace, section: defaults} - type: boolean - yaml: {key: defaults.restrict_facts_namespace} - version_added: "2.4" +# Deffered to 2.5 +#ONLY_NAMESPACE_FACTS: +# default: False +# description: +# - Facts normally get injected as top level variables, this setting prevents that. +# - Facts are still available in the `ansible_facts` variable w/o the `ansible_` prefix. +# env: [{name: ANSIBLE_RESTRICT_FACTS}] +# ini: +# - {key: restrict_facts_namespace, section: defaults} +# type: boolean +# yaml: {key: defaults.restrict_facts_namespace} +# version_added: "2.4" PARAMIKO_HOST_KEY_AUTO_ADD: + # TODO: move to plugin default: False description: 'TODO: write it' env: [{name: ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD}] ini: - {key: host_key_auto_add, section: paramiko_connection} type: boolean - yaml: {key: paramiko_connection.host_key_auto_add} PARAMIKO_LOOK_FOR_KEYS: + # TODO: move to plugin default: True description: 'TODO: write it' env: [{name: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS}] ini: - {key: look_for_keys, section: paramiko_connection} type: boolean - yaml: {key: paramiko_connection.look_for_keys} PARAMIKO_PROXY_COMMAND: + # TODO: move to plugin default: description: 'TODO: write it' env: [{name: ANSIBLE_PARAMIKO_PROXY_COMMAND}] ini: - {key: proxy_command, section: paramiko_connection} - yaml: {key: paramiko_connection.proxy_command} PARAMIKO_PTY: + # TODO: move to plugin default: True description: 'TODO: write it' env: [{name: ANSIBLE_PARAMIKO_PTY}] ini: - {key: pty, section: paramiko_connection} type: boolean - yaml: {key: paramiko_connection.pty} PARAMIKO_RECORD_HOST_KEYS: + # TODO: move to plugin default: True description: 'TODO: write it' env: [{name: ANSIBLE_PARAMIKO_RECORD_HOST_KEYS}] ini: - {key: record_host_keys, section: paramiko_connection} type: boolean - yaml: {key: paramiko_connection.record_host_keys} PERSISTENT_CONTROL_PATH_DIR: + name: Persistence socket path default: ~/.ansible/pc - description: 'TODO: write it' + description: Path to socket to be used by the connection persistence system. env: [{name: ANSIBLE_PERSISTENT_CONTROL_PATH_DIR}] ini: - {key: control_path_dir, section: persistent_connection} - yaml: {key: persistent_connection.control_path_dir} + type: path PERSISTENT_CONNECT_TIMEOUT: + name: Persistence timeout default: 30 description: This controls how long the persistent connection will remain idle before it is destroyed. env: [{name: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT}] ini: - {key: connect_timeout, section: persistent_connection} type: integer - yaml: {key: persistent_connection.connect_timeout} PERSISTENT_CONNECT_RETRY_TIMEOUT: + name: Persistence connection retry timeout default: 15 description: This contorls the retry timeout for presistent connection to connect to the local domain socket. env: [{name: ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT}] ini: - {key: connect_retry_timeout, section: persistent_connection} type: integer - yaml: {key: persistent_connection.connect_retry_timeout} PERSISTENT_COMMAND_TIMEOUT: + name: Persistence command timeout default: 10 description: This controls the amount of time to wait for response from remote device before timing out presistent connection. env: [{name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT}] ini: - {key: command_timeout, section: persistent_connection} - type: integer - yaml: {key: persistent_connection.command_timeout} + type: int RETRY_FILES_ENABLED: + name: Retry files default: True description: This controls whether a failed Ansible playbook should create a .retry file. env: [{name: ANSIBLE_RETRY_FILES_ENABLED}] ini: - {key: retry_files_enabled, section: defaults} - type: boolean - yaml: {key: errors.retry.enabled} + type: bool RETRY_FILES_SAVE_PATH: + name: Retry files path default: ~ description: This sets the path in which Ansible will save .retry files when a playbook fails and retry files are enabled. env: [{name: ANSIBLE_RETRY_FILES_SAVE_PATH}] ini: - {key: retry_files_save_path, section: defaults} type: path - yaml: {key: errors.retry.path} SHOW_CUSTOM_STATS: + name: Display custom stats default: False description: 'This adds the custom stats set via the set_stats plugin to the default output' env: [{name: ANSIBLE_SHOW_CUSTOM_STATS}] ini: - {key: show_custom_stats, section: defaults} - type: boolean - yaml: {key: defaults.show_custom_stats} + type: bool STRING_TYPE_FILTERS: + name: Filters to preserve strings default: [string, to_json, to_nice_json, to_yaml, ppretty, json] description: - "This list of filters avoids 'type conversion' when templating variables" @@ -1345,32 +1520,35 @@ STRING_TYPE_FILTERS: ini: - {key: dont_type_filters, section: jinja2} type: list - yaml: {key: jinja2.dont_type_filters} SYSTEM_WARNINGS: + name: System warnings default: True - description: 'TODO: write it' + description: + - Allows disabling of warnings related to potential issues on the system running ansible itself (not on the managed hosts) + - These may include warnings about 3rd party packages or other conditions that should be resolved if possible. env: [{name: ANSIBLE_SYSTEM_WARNINGS}] ini: - {key: system_warnings, section: defaults} type: boolean - yaml: {key: defaults.system_warnings} USE_PERSISTENT_CONNECTIONS: + name: Persistence default: False - description: 'TODO: write it' + description: Toggles the use of persistence for connections. env: [{name: ANSIBLE_USE_PERSISTENT_CONNECTIONS}] ini: - {key: use_persistent_connections, section: defaults} type: boolean - yaml: {key: defaults.use_persistent_connections} VARIABLE_PRECEDENCE: - default: [all_inventory, groups_inventory, all_plugins_inventory, all_plugins_play, groups_plugins_inventory, groups_plugins_play] - description: 'TODO: write it' + name: Group variable precedence + default: ['all_inventory', 'groups_inventory', 'all_plugins_inventory', 'all_plugins_play', 'groups_plugins_inventory', 'groups_plugins_play'] + description: Allows to change the group variable precedence merge order. env: [{name: ANSIBLE_PRECEDENCE}] ini: - {key: precedence, section: defaults} type: list - yaml: {key: defaults.precedence} + version_added: "2.4" YAML_FILENAME_EXTENSIONS: + name: Valid YAML extensions default: [".yml", ".yaml", ".json"] description: - "Check all of these extensions when looking for 'variable' files which should be YAML or JSON or vaulted versions of these." @@ -1381,5 +1559,4 @@ YAML_FILENAME_EXTENSIONS: - section: yaml_valid_extensions key: defaults type: list - yaml: {key: defaults.yaml_valid_extensions} ... diff --git a/lib/ansible/config/manager.py b/lib/ansible/config/manager.py index 11f33b400c..545cb7c19b 100644 --- a/lib/ansible/config/manager.py +++ b/lib/ansible/config/manager.py @@ -22,8 +22,9 @@ from ansible.parsing.quoting import unquote from ansible.utils.path import unfrackpath from ansible.utils.path import makedirs_safe -Plugin = namedtuple('Plugin','name type') -Setting = namedtuple('Setting','name value origin') +Plugin = namedtuple('Plugin', 'name type') +Setting = namedtuple('Setting', 'name value origin type') + # FIXME: see if we can unify in module_utils with similar function used by argspec def ensure_type(value, value_type): @@ -74,9 +75,15 @@ def ensure_type(value, value_type): prefix = 'ansible-local-%s' % os.getpid() value = tempfile.mkdtemp(prefix=prefix, dir=value) + elif value_type == 'pathspec': + if isinstance(value, string_types): + value = value.split(os.pathsep) + value = [resolve_path(x) for x in value] + elif value_type == 'pathlist': if isinstance(value, string_types): - value = [resolve_path(x) for x in value.split(os.pathsep)] + value = value.split(',') + value = [resolve_path(x) for x in value] # defaults to string types elif isinstance(value, string_types): @@ -84,14 +91,16 @@ def ensure_type(value, value_type): return to_text(value, errors='surrogate_or_strict', nonstring='passthru') + # FIXME: see if this can live in utils/path def resolve_path(path): ''' resolve relative or 'varaible' paths ''' - if '{{CWD}}' in path: # allow users to force CWD using 'magic' {{CWD}} + if '{{CWD}}' in path: # allow users to force CWD using 'magic' {{CWD}} path = path.replace('{{CWD}}', os.getcwd()) return unfrackpath(path, follow=False) + # FIXME: generic file type? def get_config_type(cfile): @@ -107,17 +116,19 @@ def get_config_type(cfile): return ftype + # FIXME: can move to module_utils for use for ini plugins also? def get_ini_config_value(p, entry): ''' returns the value of last ini entry found ''' value = None if p is not None: try: - value = p.get(entry.get('section','defaults'), entry.get('key',''), raw=True) - except: # FIXME: actually report issues here + value = p.get(entry.get('section', 'defaults'), entry.get('key', ''), raw=True) + except: # FIXME: actually report issues here pass return value + def find_ini_config_file(): ''' Load INI Config File order(first found is used): ENV, CWD, HOME, /etc/ansible ''' # FIXME: eventually deprecate ini configs @@ -142,6 +153,7 @@ def find_ini_config_file(): return path + class ConfigManager(object): UNABLE = [] @@ -156,8 +168,7 @@ class ConfigManager(object): self._config_file = conf_file self.data = ConfigData() - - #FIXME: make dynamic? scan for more? make it's own method? + # FIXME: make dynamic? scan for more? make it's own method? # Create configuration definitions from source bconfig_def = to_bytes('%s/base.yml' % os.path.dirname(__file__)) if os.path.exists(bconfig_def): @@ -200,12 +211,10 @@ class ConfigManager(object): else: raise AnsibleOptionsError("Unsupported configuration file type: %s" % to_native(ftype)) - def _find_yaml_config_files(self): ''' Load YAML Config Files in order, check merge flags, keep origin of settings''' pass - def get_configuration_definitions(self, plugin_type=None, name=None): ''' just list the possible settings, either base or for specific plugins or plugin ''' @@ -227,12 +236,13 @@ class ConfigManager(object): for entry in entry_list: name = entry.get('name') temp_value = container.get(name, None) - if temp_value is not None: # only set if env var is defined + if temp_value is not None: # only set if env var is defined value = temp_value origin = name # deal with deprecation of setting source, if used - #FIXME: if entry.get('deprecated'): + if 'deprecated' in entry: + self.DEPRECATED.append((entry['name'], entry['deprecated'])) return value, origin @@ -273,15 +283,16 @@ class ConfigManager(object): if ftype and defs[config].get(ftype): if ftype == 'ini': # load from ini config - try: # FIXME: generaelize _loop_entries to allow for files also + try: # FIXME: generaelize _loop_entries to allow for files also for ini_entry in defs[config]['ini']: value = get_ini_config_value(self._parser, ini_entry) origin = cfile - #FIXME: if ini_entry.get('deprecated'): + if 'deprecated' in ini_entry: + self.DEPRECATED.append(('[%s]%s' % (ini_entry['section'], ini_entry['key']), ini_entry['deprecated'])) except Exception as e: sys.stderr.write("Error while loading ini config %s: %s" % (cfile, to_native(e))) elif ftype == 'yaml': - pass # FIXME: implement, also , break down key from defs (. notation???) + pass # FIXME: implement, also , break down key from defs (. notation???) origin = cfile ''' @@ -315,17 +326,11 @@ class ConfigManager(object): self.UNABLE.append(config) # deal with deprecation of the setting - if defs[config].get('deprecated') and origin != 'default': + if 'deprecated' in defs[config] and origin != 'default': self.DEPRECATED.append((config, defs[config].get('deprecated'))) return value, origin - def update_plugin_config(self, plugin_type, name, defs): - ''' really: update constants ''' - # no sense? - self.initialize_plugin_configuration_definitions(plugin_type, name, defs) - self.update_config_data(defs) - def initialize_plugin_configuration_definitions(self, plugin_type, name, defs): if plugin_type not in self._plugins: @@ -346,7 +351,7 @@ class ConfigManager(object): raise AnsibleOptionsError("Invalid configuration definition type: %s for %s" % (type(defs), defs)) # update the constant for config file - self.data.update_setting(Setting('CONFIG_FILE', configfile, '')) + self.data.update_setting(Setting('CONFIG_FILE', configfile, '', 'string')) origin = None # env and config defs can have several entries, ordered in list from lowest to highest precedence @@ -358,7 +363,7 @@ class ConfigManager(object): value, origin = self.get_config_value_and_origin(config, configfile) # set the constant - self.data.update_setting(Setting(config, value, origin)) + self.data.update_setting(Setting(config, value, origin, defs[config].get('type', 'string'))) # FIXME: find better way to do this by passing back to where display is available if self.UNABLE: diff --git a/lib/ansible/constants.py b/lib/ansible/constants.py index 25f1a00d8e..a83f166ec5 100644 --- a/lib/ansible/constants.py +++ b/lib/ansible/constants.py @@ -6,14 +6,13 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -import os # used to set lang - +import os # used to set lang and for backwards compat get_config from string import ascii_letters, digits from ansible.module_utils._text import to_text from ansible.module_utils.parsing.convert_bool import boolean, BOOLEANS_TRUE from ansible.module_utils.six import string_types -from ansible.config.manager import ConfigManager +from ansible.config.manager import ConfigManager, ensure_type def _deprecated(msg): ''' display is not guaranteed here, nor it being the full class, but try anyways, fallback to sys.stderr.write ''' @@ -33,8 +32,6 @@ def get_config(parser, section, key, env_var, default_value, value_type=None, ex ''' kept for backwarsd compatibility, but deprecated ''' _deprecated('ansible.constants.get_config() is deprecated. There is new config API, see porting docs.') - import os - value = None # small reconstruction of the old code env/ini/default value = os.environ.get(env_var, None) @@ -52,6 +49,10 @@ def get_config(parser, section, key, env_var, default_value, value_type=None, ex return value +def set_constant(name, value, export=vars()): + ''' sets constants and returns resolved options dict ''' + export[name] = value + ### CONSTANTS ### yes, actual ones BLACKLIST_EXTS = ('.pyc', '.pyo', '.swp', '.bak', '~', '.rpm', '.md', '.txt') BECOME_METHODS = ['sudo', 'su', 'pbrun', 'pfexec', 'doas', 'dzdo', 'ksu', 'runas', 'pmrun'] @@ -98,15 +99,15 @@ config = ConfigManager() # Generate constants from config for setting in config.data.get_settings(): - # FIXME: find better way to do in manager class and/or ensure types + value = None if isinstance(setting.value, string_types) and (setting.value.startswith('eval(') and setting.value.endswith(')')): try: + # FIXME: find better way to do in manager class and/or ensure types eval_string = setting.value.replace('eval(', '', 1)[:-1] - vars()[setting.name] = eval(eval_string) # FIXME: safe eval? - continue + value = ensure_type(eval(eval_string), setting.type) # FIXME: safe eval? except: - pass + value = setting.value - vars()[setting.name] = setting.value + set_constant(setting.name, setting.value) diff --git a/lib/ansible/executor/task_executor.py b/lib/ansible/executor/task_executor.py index 9d739dc928..66e371deb4 100644 --- a/lib/ansible/executor/task_executor.py +++ b/lib/ansible/executor/task_executor.py @@ -414,6 +414,8 @@ class TaskExecutor: # We also add "magic" variables back into the variables dict to make sure # a certain subset of variables exist. self._play_context.update_vars(variables) + + # FIXME: update connection/shell plugin options except AnsibleError as e: # save the error, which we'll raise later if we don't end up # skipping this task during the conditional evaluation step @@ -731,11 +733,11 @@ class TaskExecutor: conn_type = self._play_context.connection connection = self._shared_loader_obj.connection_loader.get(conn_type, self._play_context, self._new_stdin) - self._play_context.set_options_from_plugin(connection) - if not connection: raise AnsibleError("the connection plugin '%s' was not found" % conn_type) + self._play_context.set_options_from_plugin(connection) + if self._play_context.accelerate: # accelerate is deprecated as of 2.1... display.deprecated('Accelerated mode is deprecated. Consider using SSH with ControlPersist and pipelining enabled instead', version='2.6') diff --git a/lib/ansible/playbook/play_context.py b/lib/ansible/playbook/play_context.py index 8292d34e89..42fa67293b 100644 --- a/lib/ansible/playbook/play_context.py +++ b/lib/ansible/playbook/play_context.py @@ -307,7 +307,7 @@ class PlayContext(Base): self.force_handlers = play.force_handlers def set_options_from_plugin(self, plugin): - # generic derived from connection plugin + # generic derived from connection plugin, temporary for backwards compat, in the end we should not set play_context properties # get options for plugins options = C.config.get_configuration_definitions(get_plugin_class(plugin), plugin._load_name) @@ -318,7 +318,7 @@ class PlayContext(Base): setattr(self, flag, self.connection.get_option(flag)) # TODO: made irrelavent by above - # get ssh options FIXME: make these common to all connections + # get ssh options # for flag in ('ssh_common_args', 'docker_extra_args', 'sftp_extra_args', 'scp_extra_args', 'ssh_extra_args'): # setattr(self, flag, getattr(options, flag, '')) diff --git a/lib/ansible/plugins/__init__.py b/lib/ansible/plugins/__init__.py index b9e7a299e0..c89ffd7ef7 100644 --- a/lib/ansible/plugins/__init__.py +++ b/lib/ansible/plugins/__init__.py @@ -44,5 +44,17 @@ def get_plugin_class(obj): class AnsiblePlugin(with_metaclass(ABCMeta, object)): - def get_option(self, option): - return C.get_plugin_option(get_plugin_class(self), self.name, option) + def __init__(self): + self.options = {} + + def get_option(self, option, hostvars=None): + if option not in self.options: + option_value = C.config.get_config_value(option, plugin_type=get_plugin_class(self), plugin_name=self.name, variables=hostvars) + self.set_option(option, option_value) + return self.options.get(option) + + def set_option(self, option, value): + self.options[option] = value + + def set_options(self, options): + self.options = options diff --git a/lib/ansible/plugins/action/__init__.py b/lib/ansible/plugins/action/__init__.py index a33f120461..cf5417d078 100644 --- a/lib/ansible/plugins/action/__init__.py +++ b/lib/ansible/plugins/action/__init__.py @@ -392,7 +392,7 @@ class ActionBase(with_metaclass(ABCMeta, object)): # we have a need for it, at which point we'll have to do something different. return remote_paths - if self._play_context.become and self._play_context.become_user not in ('root', remote_user): + if self._play_context.become and self._play_context.become_user and self._play_context.become_user not in ('root', remote_user): # Unprivileged user that's different than the ssh user. Let's get # to work! diff --git a/lib/ansible/plugins/cache/jsonfile.py b/lib/ansible/plugins/cache/jsonfile.py index d1131cdc79..c387676f39 100644 --- a/lib/ansible/plugins/cache/jsonfile.py +++ b/lib/ansible/plugins/cache/jsonfile.py @@ -1,19 +1,7 @@ # (c) 2014, Brian Coca, Josh Drake, et al -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: cache: jsonfile @@ -21,8 +9,36 @@ DOCUMENTATION: description: - This cache uses JSON formatted, per host, files saved to the filesystem. version_added: "1.9" - author: Brian Coca (@bcoca) + author: Ansible Core + options: + _uri: + required: True + description: + - Path in which the cache plugin will save the JSON files + type: list + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the JSON files + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + - section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults + type: integer ''' + # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/cache/memcached.py b/lib/ansible/plugins/cache/memcached.py index 0b74895376..dca0b48066 100644 --- a/lib/ansible/plugins/cache/memcached.py +++ b/lib/ansible/plugins/cache/memcached.py @@ -1,19 +1,45 @@ # (c) 2014, Brian Coca, Josh Drake, et al -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + cache: memcached + short_description: Use memcached DB for cache + description: + - This cache uses JSON formatted, per host records saved in memcached. + version_added: "1.9" + requirements: + - memcache (python lib) + options: + _uri: + description: + - List of connection information for the memcached DBs + default: ['127.0.0.1:11211'] + type: list + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the DB entries + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + - section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults + type: integer +''' + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/cache/memory.py b/lib/ansible/plugins/cache/memory.py index 494fd49513..d0ecc65d28 100644 --- a/lib/ansible/plugins/cache/memory.py +++ b/lib/ansible/plugins/cache/memory.py @@ -1,25 +1,15 @@ # (c) 2014, Brian Coca, Josh Drake, et al -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: cache: memory short_description: RAM backed, non persistent description: - RAM backed cache that is not persistent. + - This is the default used if no other plugin is specified. + - There are no options to configure. version_added: historical author: core team (@ansible-core) ''' diff --git a/lib/ansible/plugins/cache/pickle.py b/lib/ansible/plugins/cache/pickle.py index 1a3163ef4e..489acc2ec6 100644 --- a/lib/ansible/plugins/cache/pickle.py +++ b/lib/ansible/plugins/cache/pickle.py @@ -1,27 +1,41 @@ # (c) 2017, Brian Coca -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: - cache: yaml + cache: pickle short_description: Pickle formatted files. description: - This cache uses Python's pickle serialization format, in per host files, saved to the filesystem. version_added: "2.3" author: Brian Coca (@bcoca) + options: + _uri: + required: True + description: + - Path in which the cache plugin will save the files + type: list + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the files + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + - section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults ''' # Make coding more python3-ish diff --git a/lib/ansible/plugins/cache/redis.py b/lib/ansible/plugins/cache/redis.py index 7eea4d440a..0f4fb4f5fe 100644 --- a/lib/ansible/plugins/cache/redis.py +++ b/lib/ansible/plugins/cache/redis.py @@ -1,19 +1,42 @@ # (c) 2014, Brian Coca, Josh Drake, et al -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +''' +DOCUMENTATION: + cache: redis + short_description: Use Redis DB for cache + description: + - This cache uses JSON formatted, per host records saved in Redis. + version_added: "1.9" + requirements: + - redis (python lib) + options: + _uri: + description: + - A colon separated string of connection information for Redis. + required: True + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the DB entries + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + - section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults + type: integer +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/cache/yaml.py b/lib/ansible/plugins/cache/yaml.py index aecf88894a..bf151fef61 100644 --- a/lib/ansible/plugins/cache/yaml.py +++ b/lib/ansible/plugins/cache/yaml.py @@ -1,19 +1,7 @@ # (c) 2017, Brian Coca -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: cache: yaml @@ -22,6 +10,33 @@ DOCUMENTATION: - This cache uses YAML formatted, per host, files saved to the filesystem. version_added: "2.3" author: Brian Coca (@bcoca) + options: + _uri: + required: True + description: + - Path in which the cache plugin will save the files + type: list + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the files + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + - section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults + type: integer ''' # Make coding more python3-ish diff --git a/lib/ansible/plugins/callback/actionable.py b/lib/ansible/plugins/callback/actionable.py index 5aad78d52a..5f0995d62e 100644 --- a/lib/ansible/plugins/callback/actionable.py +++ b/lib/ansible/plugins/callback/actionable.py @@ -1,20 +1,19 @@ # (c) 2015, Andrew Gaffney <andrew@agaffney.org> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: actionable + type: stdout + short_description: shows only items that need attention + description: + - Use this callback when you dont care about OK nor Skipped. + - This callback suppreses any non Failed or Changed status. + version_added: "2.1" + requirements: + - set as stdout callback in configuration +''' # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/context_demo.py b/lib/ansible/plugins/callback/context_demo.py index 89e729f2ec..08add61625 100644 --- a/lib/ansible/plugins/callback/context_demo.py +++ b/lib/ansible/plugins/callback/context_demo.py @@ -1,21 +1,20 @@ # (C) 2012, Michael DeHaan, <michael.dehaan@gmail.com> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: context_demo + type: aggregate + short_description: demo callback that adds play/task context + description: + - Displays some play and task context along with normal output + - This is mostly for demo purposes + version_added: "2.1" + requirements: + - whitelist in configuration +''' -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/debug.py b/lib/ansible/plugins/callback/debug.py index 16ed7d6bd4..94e7b86c14 100644 --- a/lib/ansible/plugins/callback/debug.py +++ b/lib/ansible/plugins/callback/debug.py @@ -1,3 +1,17 @@ +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: debug + type: stdout + short_description: formated stdout/stderr display + description: + - Use this callback to sort though extensive debug output + version_added: "2.4" + requirements: + - set as stdout in configuration +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/default.py b/lib/ansible/plugins/callback/default.py index 238608f646..34f4180f54 100644 --- a/lib/ansible/plugins/callback/default.py +++ b/lib/ansible/plugins/callback/default.py @@ -1,28 +1,40 @@ # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: callback: default + type: stdout short_description: default Ansible screen output version_added: historical description: - This is the default output callback for ansible-playbook. + options: + show_skipped_hosts: + name: Show skipped hosts + description: "Toggle to control displaying skipped task/host results in a task" + env: + - name: DISPLAY_SKIPPED_HOSTS + ini: + - key: display_skipped_hosts + section: defaults + type: boolean + default: True + show_custom_stats: + name: Show custom stats + default: False + description: 'This adds the custom stats set via the set_stats plugin to the play recap' + env: + - name: ANSIBLE_SHOW_CUSTOM_STATS + ini: + - key: show_custom_stats + section: defaults + type: bool + requirements: + - set as stdout in configuration ''' -# Make coding more python3-ish + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/dense.py b/lib/ansible/plugins/callback/dense.py index 11d7c2e85f..7adbdb819c 100644 --- a/lib/ansible/plugins/callback/dense.py +++ b/lib/ansible/plugins/callback/dense.py @@ -1,21 +1,18 @@ # (c) 2016, Dag Wieers <dag@wieers.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# Make coding more python3-ish +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: dense + type: stdout + short_description: minimal stdout output + description: + - When in verbose mode it will act the same as the default callback + version_added: "2.3" + requirements: + - set as stdout in configuation +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/foreman.py b/lib/ansible/plugins/callback/foreman.py index 4e97edfc17..0172b4c43c 100644 --- a/lib/ansible/plugins/callback/foreman.py +++ b/lib/ansible/plugins/callback/foreman.py @@ -1,21 +1,42 @@ # -*- coding: utf-8 -*- -# (C) 2015, 2016 Daniel Lobato <elobatocs@gmail.com> -# 2016 Guido Günther <agx@sigxcpu.org> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2015, 2016 Daniel Lobato <elobatocs@gmail.com> +# (c) 2016 Guido Günther <agx@sigxcpu.org> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: foreman + type: notification + short_description: Sends events to Foreman + description: + - This callback will report facts and task events to Foreman https://theforeman.org/ + version_added: "2.2" + requirements: + - whitelisting in configuration + - requests (python library) + options: + url: + description: URL to the Foreman server + env: + - name: FOREMAN_URL + required: True + ssl_cert: + description: X509 certificate to authenticate to Foreman if https is used + env: + - name: FOREMAN_SSL_CERT + ssl_key: + description: the corresponding private key + env: + - name: FOREMAN_SSL_KEY + verify_certs: + description: + - Toggle to decidewhether to verify the Foreman certificate. + - It can be set to '1' to verify SSL certificates using the installed CAs or to a path pointing to a CA bundle. + - Set to '0' to disable certificate checking. + env: + - name: FOREMAN_SSL_VERIFY +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/full_skip.py b/lib/ansible/plugins/callback/full_skip.py index a453eec0d6..dd2e8876f9 100644 --- a/lib/ansible/plugins/callback/full_skip.py +++ b/lib/ansible/plugins/callback/full_skip.py @@ -1,20 +1,18 @@ # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +''' +DOCUMENTATION: + callback: full_skip + type: stdout + short_description: suppreses tasks if all hosts skipped + description: + - Use this plugin when you dont care about any output for tasks that were completly skipped + version_added: "2.4" + requirements: + - set as stdout in configuation +''' # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/hipchat.py b/lib/ansible/plugins/callback/hipchat.py index 3de5f85bb5..55ff0ac93b 100644 --- a/lib/ansible/plugins/callback/hipchat.py +++ b/lib/ansible/plugins/callback/hipchat.py @@ -1,21 +1,42 @@ # (C) 2014, Matt Martz <matt@sivel.net> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: hipchat + type: notification + short_description: post task events to hipchat + description: + - The chatty part of ChatOps with a Hipchat server as a target + - This callback plugin sends status updates to a HipChat channel during playbook execution. + version_added: "1.6" + requirements: + - prettytable (python lib) + options: + token: + description: HipChat API token + required: True + env: + - name: HIPCHAT_TOKEN + room: + description: HipChat room to post in. + default: ansible + env: + - name: HIPCHAT_ROOM + from: + description: Name to post as + default: ansible + env: + - name: HIPCHAT_FROM + notify: + description: Add notify flag to important messages + type: bool + default: True + env: + - name: HIPCHAT_NOTIFY +''' -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/jabber.py b/lib/ansible/plugins/callback/jabber.py index 2f764daa7c..89983d7d37 100644 --- a/lib/ansible/plugins/callback/jabber.py +++ b/lib/ansible/plugins/callback/jabber.py @@ -1,18 +1,41 @@ -# Ansible CallBack module for Jabber (XMPP) # Copyright (C) 2016 maxn nikolaev.makc@gmail.com -# -# This module is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see http://www.gnu.org/licenses/ +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: jabber + type: notification + short_description: post task events to a jabber server + description: + - The chatty part of ChatOps with a Hipchat server as a target + - This callback plugin sends status updates to a HipChat channel during playbook execution. + version_added: "2.2" + requirements: + - xmpp (python lib https://github.com/ArchipelProject/xmpppy) + options: + server: + description: connection info to jabber server + required: True + env: + - name: JABBER_SERV + user: + description: Jabber user to authenticate as + required: True + env: + - name: JABBER_USER + password: + description: Password for the user to the jabber server + required: True + env: + - name: JABBER_PASS + to: + description: chat identifier that will recieve the message + required: True + env: + - name: JABBER_TO +''' + from __future__ import (absolute_import, division, print_function) __metaclass__ = type @@ -48,9 +71,9 @@ class CallbackModule(CallbackBase): self.j_pass = os.getenv('JABBER_PASS') self.j_to = os.getenv('JABBER_TO') - if (self.j_user or self.j_pass or self.serv) is None: + if (self.j_user or self.j_pass or self.serv or self.j_to) is None: self.disabled = True - self._display.warning('Jabber CallBack want JABBER_USER and JABBER_PASS env variables') + self._display.warning('Jabber CallBack wants the JABBER_SERV, JABBER_USER, JABBER_PASS and JABBER_TO environment variables') def send_msg(self, msg): """Send message""" diff --git a/lib/ansible/plugins/callback/json.py b/lib/ansible/plugins/callback/json.py index 1dd886ab2c..464605fe2f 100644 --- a/lib/ansible/plugins/callback/json.py +++ b/lib/ansible/plugins/callback/json.py @@ -1,29 +1,17 @@ # (c) 2016, Matt Martz <matt@sivel.net> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ''' DOCUMENTATION: callback: json - short_description: Ansbile screen output asjson + short_description: Ansbile screen output as JSON version_added: "2.2" description: - - This callback converts all events into JSON output + - This callback converts all events into JSON output to stdout type: stdout - plugin_api_version: "2.0" + requirements: + - Set as stdout in config ''' # Make coding more python3-ish diff --git a/lib/ansible/plugins/callback/junit.py b/lib/ansible/plugins/callback/junit.py index 367d5fcf8a..b7255ebf7a 100644 --- a/lib/ansible/plugins/callback/junit.py +++ b/lib/ansible/plugins/callback/junit.py @@ -1,19 +1,44 @@ # (c) 2016 Matt Clay <matt@mystile.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: junit + type: aggregate + short_description: write playbook output to a JUnit file. + version_added: historical + description: + - This callback writes playbook output to a JUnit formatted XML file. + - "Tasks show up in the report as follows: + 'ok': pass + 'failed' with 'EXPECTED FAILURE' in the task name: pass + 'failed' due to an exception: error + 'failed' for other reasons: failure + 'skipped': skipped" + options: + output_dir: + name: JUnit output dir + default: ~/.ansible.log + description: Directory to write XML files to. + env: + - name: JUNIT_OUTPUT_DIR + task_class: + name: JUnit Task class + default: False + description: Configure the output to be one class per yaml file + env: + - name: JUNIT_TASK_CLASS + fail_on_change: + name: JUnit fail on change + default: False + description: Consider any tasks reporting "changed" as a junit test failure + env: + - name: JUNIT_FAIL_ON_CHANGE + requirements: + - whitelist in configuration + - junit_xml (python lib) +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/log_plays.py b/lib/ansible/plugins/callback/log_plays.py index 12c6a8d225..cfa65a87ee 100644 --- a/lib/ansible/plugins/callback/log_plays.py +++ b/lib/ansible/plugins/callback/log_plays.py @@ -1,21 +1,21 @@ # (C) 2012, Michael DeHaan, <michael.dehaan@gmail.com> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: log_plays + type: notification + short_description: write playbook output to log file + version_added: historical + description: + - This callback writes playbook output to a file per host in the `/var/log/ansible/hosts` directory + - "TODO: make this configurable" + requirements: + - Whitelist in configuration + - A writeable /var/log/ansible/hosts directory by the user executing Ansbile on the controller +''' -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/logentries.py b/lib/ansible/plugins/callback/logentries.py index 8d013ced0b..ddb3f096bf 100644 --- a/lib/ansible/plugins/callback/logentries.py +++ b/lib/ansible/plugins/callback/logentries.py @@ -1,46 +1,84 @@ -""" (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com> - -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -This callback plugin will generate json objects to be sent to logentries -for auditing/debugging purposes. - -Todo: - -* Better formatting of output before sending out to logentries data/api nodes. - -To use: - -Add this to your ansible.cfg file in the defaults block +# (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: logentries + type: notification + short_description: Sends events to Logentries + description: + - This callback plugin will generate JSON objects and send them to Logentries for auditing/debugging purposes. + - If you want to use an ini configuration, the file must be placed in the same directory as this plugin and named logentries.ini + version_added: "2.0" + requirements: + - whitelisting in configuration + - certifi (python library) + - flatdict (pytnon library) + options: + api: + description: URI to the Logentries API + env: + - name: LOGENTRIES_API + default: data.logentries.com + ini: + - section: defaults + key: api + port: + description: Http port to use when connecting to the API + env: + - name: LOGENTRIES_PORT + default: 80 + ini: + - section: defaults + key: port + tls_port: + description: Port to use when connecting to the API when TLS is enabled + env: + - name: LOGENTRIES_TLS_PORT + default: 443 + ini: + - section: defaults + key: tls_port + token: + description: the authentication token + env: + - name: LOGENTRIES_ANSIBLE_TOKEN + required: True + ini: + - section: defaults + key: token + use_tls: + description: + - Toggle to decidewhether to use TLS to encrypt the communications with the API server + env: + - name: LOGENTRIES_USE_TLS + default: False + type: boolean + ini: + - section: defaults + key: use_tls + flatten: + description: flatten complex data structures into a single dictionary with complex keys + type: boolean + default: False + env: + - name: LOGENTRIES_FLATTEN + ini: + - section: defaults + key: flatten +EXAMPLES: > + To enable, add this to your ansible.cfg file in the defaults block [defaults] - callback_plugins = ./callback_plugins - callback_stdout = logentries callback_whitelist = logentries -Copy the callback plugin into the callback_plugins directory - -Either set the environment variables - + Either set the environment variables export LOGENTRIES_API=data.logentries.com export LOGENTRIES_PORT=10000 export LOGENTRIES_ANSIBLE_TOKEN=dd21fc88-f00a-43ff-b977-e3a4233c53af -Or create a logentries.ini config file that sites next to the plugin with the following contents - + Or create a logentries.ini config file that sites next to the plugin with the following contents [logentries] api = data.logentries.com port = 10000 @@ -48,10 +86,7 @@ Or create a logentries.ini config file that sites next to the plugin with the fo use_tls = no token = dd21fc88-f00a-43ff-b977-e3a4233c53af flatten = False - - -""" - +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type @@ -59,7 +94,6 @@ import os import socket import random import time -import codecs import uuid try: @@ -77,6 +111,10 @@ except ImportError: from ansible.module_utils.six.moves import configparser from ansible.module_utils._text import to_bytes, to_text from ansible.plugins.callback import CallbackBase +""" +Todo: + * Better formatting of output before sending out to logentries data/api nodes. +""" class PlainTextSocketAppender(object): @@ -92,8 +130,7 @@ class PlainTextSocketAppender(object): self.MIN_DELAY = 0.1 self.MAX_DELAY = 10 # Error message displayed when an incorrect Token has been detected - self.INVALID_TOKEN = ("\n\nIt appears the LOGENTRIES_TOKEN " - "parameter you entered is incorrect!\n\n") + self.INVALID_TOKEN = ("\n\nIt appears the LOGENTRIES_TOKEN parameter you entered is incorrect!\n\n") # Unicode Line separator character \u2028 self.LINE_SEP = u'\u2028' @@ -189,15 +226,17 @@ class CallbackModule(CallbackBase): if not HAS_SSL: self._display.warning("Unable to import ssl module. Will send over port 80.") + warn = '' if not HAS_CERTIFI: self.disabled = True - self._display.warning('The `certifi` python module is not installed. ' - 'Disabling the Logentries callback plugin.') + warn += 'The `certifi` python module is not installed.' if not HAS_FLATDICT: self.disabled = True - self._display.warning('The `flatdict` python module is not installed. ' - 'Disabling the Logentries callback plugin.') + warn += 'The `flatdict` python module is not installed.' + + if warn: + self._display.warning('%s\nDisabling the Logentries callback plugin.' % warn) config_path = os.path.abspath(os.path.dirname(__file__)) config = configparser.ConfigParser() diff --git a/lib/ansible/plugins/callback/logstash.py b/lib/ansible/plugins/callback/logstash.py index a900ae3f42..bc3e24f6e6 100644 --- a/lib/ansible/plugins/callback/logstash.py +++ b/lib/ansible/plugins/callback/logstash.py @@ -1,19 +1,35 @@ # (C) 2016, Ievgen Khmelenko <ujenmr@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (C) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: logstash + type: notification + short_description: Sends events to Logstash + description: + - This callback will report facts and task events to Foreman https://theforeman.org/ + version_added: "2.3" + requirements: + - whitelisting in configuration + - logstash (python library) + options: + server: + description: Address of the Logstash server + env: + - name: LOGSTASH_SERVER + default: localhost + port: + description: Port on which logstash is listening + env: + - name: LOGSTASH_PORT + default: 5000 + type: + description: Message type + env: + - name: LOGSTASH_TYPE + default: ansible +''' from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/mail.py b/lib/ansible/plugins/callback/mail.py index 499d04f367..bd186205ef 100644 --- a/lib/ansible/plugins/callback/mail.py +++ b/lib/ansible/plugins/callback/mail.py @@ -1,8 +1,28 @@ # -*- coding: utf-8 -*- - # Copyright: (c) 2012, Dag Wieers <dag@wieers.com> # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +''' +DOCUMENTATION: + callback: mail + type: notification + short_description: Sends failure events via email + description: + - This callback will report failures via email + version_added: "2.3" + requirements: + - whitelisting in configuration + - logstash (python library) + options: + mta: + description: Mail Transfer Agent, server that accepts SMTP + env: + - name: SMTPHOST + default: localhost + note: + - "TODO: expand configuration options now that plugins can leverage Ansible's configuration" +''' + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/minimal.py b/lib/ansible/plugins/callback/minimal.py index eadc7de0ef..eb6bd5c5aa 100644 --- a/lib/ansible/plugins/callback/minimal.py +++ b/lib/ansible/plugins/callback/minimal.py @@ -1,21 +1,19 @@ # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: minimal + type: stdout + short_description: minimal Ansible screen output + version_added: historical + description: + - This is the default output callback used by the ansible command (ad-hoc) +''' # Make coding more python3-ish +# Make coding more python3-ish from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/callback/oneline.py b/lib/ansible/plugins/callback/oneline.py index 55e5ea4ce8..e55856d6a5 100644 --- a/lib/ansible/plugins/callback/oneline.py +++ b/lib/ansible/plugins/callback/oneline.py @@ -1,19 +1,16 @@ # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: oneline + type: stdout + short_description: oneline Ansible screen output + version_added: historical + description: + - This is the output callback used by the -o/--one-line command line option. +''' # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) diff --git a/lib/ansible/plugins/callback/osx_say.py b/lib/ansible/plugins/callback/osx_say.py index d2f85f9a31..1b4b490146 100644 --- a/lib/ansible/plugins/callback/osx_say.py +++ b/lib/ansible/plugins/callback/osx_say.py @@ -1,20 +1,19 @@ - -# (C) 2012, Michael DeHaan, <michael.dehaan@gmail.com> - -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2012, Michael DeHaan, <michael.dehaan@gmail.com> +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: osx_say + type: notification + requirements: + - whitelising in configuration + - the '/usr/bin/say' command line program (standard on OS X) + short_description: oneline Ansible screen output + version_added: historical + description: + - This plugin will use the 'say' program to "speak" about play events. +''' # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) diff --git a/lib/ansible/plugins/callback/skippy.py b/lib/ansible/plugins/callback/skippy.py index 0d75c50dd8..856b424894 100644 --- a/lib/ansible/plugins/callback/skippy.py +++ b/lib/ansible/plugins/callback/skippy.py @@ -1,19 +1,17 @@ # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +''' +DOCUMENTATION: + callback: skippy + callback_type: stdout + requires: set as display + short_description: Ansible screen output that ignores skipped status + version_added: "2.0" + description: + - This callback does the same as the default except it does not output skipped host/task/item status +''' # Make coding more python3-ish from __future__ import (absolute_import, division, print_function) diff --git a/lib/ansible/plugins/connection/__init__.py b/lib/ansible/plugins/connection/__init__.py index 8a30cbbbdc..0eada4a228 100644 --- a/lib/ansible/plugins/connection/__init__.py +++ b/lib/ansible/plugins/connection/__init__.py @@ -70,6 +70,9 @@ class ConnectionBase(AnsiblePlugin): allow_executable = True def __init__(self, play_context, new_stdin, *args, **kwargs): + + super(ConnectionBase, self).__init__() + # All these hasattrs allow subclasses to override these parameters if not hasattr(self, '_play_context'): self._play_context = play_context diff --git a/lib/ansible/plugins/connection/accelerate.py b/lib/ansible/plugins/connection/accelerate.py index e38365dfd1..b91fe12d1e 100644 --- a/lib/ansible/plugins/connection/accelerate.py +++ b/lib/ansible/plugins/connection/accelerate.py @@ -14,6 +14,18 @@ # # You should have received a copy of the GNU General Public License # along with Ansible. If not, see <http://www.gnu.org/licenses/>. +""" +DOCUMENTATION: + author: Ansible Core Team + connection: accelerate + short_description: Temporary 0mq agent + description: + - This plugin uses one of the other ssh plugins to setup a temporary 0mq daemon on the target to execute subsequent tasks + deprecated: + why: paramiko and ssh + controlpersist perform the same or better without the problems of having an agent. + version: 2.5 + alternative: paramiko and ssh with conrol persistence. +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/buildah.py b/lib/ansible/plugins/connection/buildah.py index 41fc26786d..c210fb6e26 100644 --- a/lib/ansible/plugins/connection/buildah.py +++ b/lib/ansible/plugins/connection/buildah.py @@ -1,52 +1,41 @@ # Based on the docker connection plugin +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # # Connection plugin for building container images using buildah tool # https://github.com/projectatomic/buildah # # Written by: Tomas Tomecek (https://github.com/TomasTomecek) -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. """ DOCUMENTATION: connection: buildah - short_description: interact with an existing buildah container + short_description: Interact with an existing buildah container description: - Run commands or put/fetch files to an existing container using buildah tool. author: Tomas Tomecek (ttomecek@redhat.com) version_added: 2.4 options: - remote_addr: - description: - - The ID of the container you want to access. - default: inventory_hostname - config: - vars: - - name: ansible_host - remote_user: - description: - - User specified via name or ID which is used to execute commands inside the container. - config: - ini: - - section: defaults - key: remote_user - env: - - name: ANSIBLE_REMOTE_USER - vars: - - name: ansible_user + remote_addr: + description: + - The ID of the container you want to access. + default: inventory_hostname + vars: + - name: ansible_host +# keyword: +# - name: hosts + remote_user: + description: + - User specified via name or ID which is used to execute commands inside the container. + ini: + - section: defaults + key: remote_user + env: + - name: ANSIBLE_REMOTE_USER + vars: + - name: ansible_user +# keyword: +# - name: remote_user """ from __future__ import (absolute_import, division, print_function) diff --git a/lib/ansible/plugins/connection/chroot.py b/lib/ansible/plugins/connection/chroot.py index 4ad6aa87e5..f2a1aa2b45 100644 --- a/lib/ansible/plugins/connection/chroot.py +++ b/lib/ansible/plugins/connection/chroot.py @@ -1,21 +1,37 @@ # Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> +# # (c) 2013, Maykel Moya <mmoya@speedyrails.com> # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Maykel Moya <mmoya@speedyrails.com> + connection: chroot + short_description: Interact with local chroot + description: + - Run commands or put/fetch files to an existing chroot on the Ansible controller. + version_added: "1.1" + options: + remote_addr: + description: + - The path of the chroot you want to access. + default: inventory_hostname + vars: + - name: ansible_host + executable: + description: + - User specified executable shell + ini: + - section: defaults + key: executable + env: + - name: ANSIBLE_EXECUTABLE + vars: + - name: ansible_executable +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/docker.py b/lib/ansible/plugins/connection/docker.py index 6f2c44db24..2d33d8b0f4 100644 --- a/lib/ansible/plugins/connection/docker.py +++ b/lib/ansible/plugins/connection/docker.py @@ -1,26 +1,42 @@ # Based on the chroot connection plugin by Maykel Moya # -# Connection plugin for configuring docker containers # (c) 2014, Lorin Hochstein -# (c) 2015, Leendert Brouwer +# (c) 2015, Leendert Brouwer (https://github.com/objectified) # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> -# -# Maintainer: Leendert Brouwer (https://github.com/objectified) -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: + - Lorin Hochestein + - Leendert Brouwer + connection: docker + short_description: Run tasks in docker containers + description: + - Run commands or put/fetch files to an existing docker container. + version_added: "2.0" + options: + remote_user: + description: + - The user to execute as inside the container + default: The set user as per docker's configuration + vars: + - name: ansible_user + - name: ansible_docker4_user + docker_extra_args: + description: + - Extra arguments to pass to the docker command line + default: '' + remote_addr: + description: + - The path of the chroot you want to access. + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_docker_host +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/funcd.py b/lib/ansible/plugins/connection/funcd.py index 1193906937..6cc9f3f422 100644 --- a/lib/ansible/plugins/connection/funcd.py +++ b/lib/ansible/plugins/connection/funcd.py @@ -1,26 +1,28 @@ # Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com> -# (c) 2013, Michael Scherer <misc@zarb.org> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# --- -# The func transport permit to use ansible over func. For people who have already setup -# func and that wish to play with ansible, this permit to move gradually to ansible -# without having to redo completely the setup of the network. +# Copyright (c) 2013, Michael Scherer <misc@zarb.org> +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Michael Scherer (@msherer) <misc@zarb.org> + connection: funcd + short_description: Use funcd to connect to target + description: + - This transport permits you to use Ansible over Func. + - For people who have already setup func and that wish to play with ansible, + this permit to move gradually to ansible without having to redo completely the setup of the network. + version_added: "1.1" + options: + remote_addr: + description: + - The path of the chroot you want to access. + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_func_host +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type @@ -61,8 +63,7 @@ class Connection(object): self.client = fc.Client(self.host) return self - def exec_command(self, cmd, become_user=None, sudoable=False, - executable='/bin/sh', in_data=None): + def exec_command(self, cmd, become_user=None, sudoable=False, executable='/bin/sh', in_data=None): ''' run a command on the remote minion ''' if in_data: @@ -96,8 +97,7 @@ class Connection(object): # take a file directly tmpdir = tempfile.mkdtemp(prefix="func_ansible") self.client.local.getfile.get(in_path, tmpdir) - shutil.move(os.path.join(tmpdir, self.host, os.path.basename(in_path)), - out_path) + shutil.move(os.path.join(tmpdir, self.host, os.path.basename(in_path)), out_path) shutil.rmtree(tmpdir) def close(self): diff --git a/lib/ansible/plugins/connection/iocage.py b/lib/ansible/plugins/connection/iocage.py index cc26edb39e..d196cd2d91 100644 --- a/lib/ansible/plugins/connection/iocage.py +++ b/lib/ansible/plugins/connection/iocage.py @@ -1,21 +1,33 @@ -# based on jail.py (c) 2013, Michael Scherer <misc@zarb.org> -# (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> +# Based on jail.py +# (c) 2013, Michael Scherer <misc@zarb.org> +# (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> # (c) 2016, Stephan Lohse <dev-github@ploek.org> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Stephan Lohse <dev-github@ploek.org> + connection: iocage + short_description: Run tasks in iocage jails + description: + - Run commands or put/fetch files to an existing iocage jail + version_added: "2.0" + options: + remote_addr: + description: + - Path to the jail + default: The set user as per docker's configuration + vars: + - name: ansible_host + - name: ansible_iocage_host + remote_user: + description: + - User to execute as inside the jail + vars: + - name: ansible_user + - name: ansible_iocage_user +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/jail.py b/lib/ansible/plugins/connection/jail.py index 6810aaeb19..77e26fdb86 100644 --- a/lib/ansible/plugins/connection/jail.py +++ b/lib/ansible/plugins/connection/jail.py @@ -1,22 +1,34 @@ -# Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> -# and chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com> -# (c) 2013, Michael Scherer <misc@zarb.org> -# (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Based on local.py by Michael DeHaan <michael.dehaan@gmail.com> +# and chroot.py by Maykel Moya <mmoya@speedyrails.com> +# Copyright (c) 2013, Michael Scherer <misc@zarb.org> +# Copyright (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Core Team + connection: jail + short_description: Run tasks in jails + description: + - Run commands or put/fetch files to an existing jail + version_added: "2.0" + options: + remote_addr: + description: + - Path to the jail + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_jail_host + remote_user: + description: + - User to execute as inside the jail + vars: + - name: ansible_user + - name: ansible_jail_user +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/libvirt_lxc.py b/lib/ansible/plugins/connection/libvirt_lxc.py index 123caa798c..96085afe6c 100644 --- a/lib/ansible/plugins/connection/libvirt_lxc.py +++ b/lib/ansible/plugins/connection/libvirt_lxc.py @@ -2,21 +2,27 @@ # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com> # (c) 2013, Michael Scherer <misc@zarb.org> # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Michael Scherer <misc@zarb.org> + connection: libvirt_lxc + short_description: Run tasks in lxc containers via libvirt + description: + - Run commands or put/fetch files to an existing lxc container using libvirt + version_added: "2.0" + options: + remote_addr: + description: + - Container identifier + default: The set user as per docker's configuration + vars: + - name: ansible_host + - name: ansible_libvirt_lxc_host +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/lxc.py b/lib/ansible/plugins/connection/lxc.py index 278c204f30..c7c51a20af 100644 --- a/lib/ansible/plugins/connection/lxc.py +++ b/lib/ansible/plugins/connection/lxc.py @@ -1,19 +1,31 @@ # (c) 2015, Joerg Thalheim <joerg@higgsboson.tk> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Joerg Thalheim <joerg@higgsboson.tk> + connection: lxc + short_description: Run tasks in lxc containers via lxc python library + description: + - Run commands or put/fetch files to an existing lxc container using lxc python library + version_added: "2.0" + options: + remote_addr: + description: + - Container identifier + default: The set user as per docker's configuration + vars: + - name: ansible_host + - name: ansible_lxc_host + executable: + default: /bin/sh + description: + - Shell executable + vars: + - name: ansible_executable + - name: ansible_lxc_executable +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/lxd.py b/lib/ansible/plugins/connection/lxd.py index d822bcfa21..ced61d9045 100644 --- a/lib/ansible/plugins/connection/lxd.py +++ b/lib/ansible/plugins/connection/lxd.py @@ -1,19 +1,31 @@ # (c) 2016 Matt Clay <matt@mystile.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Matt Clay <matt@mystile.com> + connection: lxd + short_description: Run tasks in lxc containers via lxc CLI + description: + - Run commands or put/fetch files to an existing lxc container using lxc CLI + version_added: "2.0" + options: + remote_addr: + description: + - Container identifier + default: The set user as per docker's configuration + vars: + - name: ansible_host + - name: ansible_lxd_host + executable: + description: + - shell to use for execution inside container + default: /bin/sh + vars: + - name: ansible_executable + - name: ansible_lxd_executable +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/netconf.py b/lib/ansible/plugins/connection/netconf.py index d7c542a9dc..854c0bb6f6 100644 --- a/lib/ansible/plugins/connection/netconf.py +++ b/lib/ansible/plugins/connection/netconf.py @@ -1,20 +1,71 @@ -# # (c) 2016 Red Hat Inc. -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Networking Team + connection: netconf + short_description: Use netconf to run command on network appliances + description: + - Use netconf to run command on network appliances + version_added: "2.3" + options: + network_os: + description: + - Appliance specific OS + default: 'default' + vars: + - name: ansible_netconf_network_os + password: + description: + - Secret used to authenticate + vars: + - name: ansible_pass + - name: ansible_netconf_pass + private_key_file: + description: + - Key or certificate file used for authentication + vars: + - name: ansible_private_key_file + - name: ansible_netconf_private_key_file + ssh_config: + type: boolean + default: False + description: + - Flag to decide if we use SSH configuration options with netconf + vars: + - name: ansible_netconf_ssh_config + env: + - name: ANSIBLE_NETCONF_SSH_CONFIG + user: + description: + - User to authenticate as + vars: + - name: ansible_user + - name: ansible_netconf_user + port: + type: int + description: + - port to connect to on the remote + default: 830 + vars: + - name: ansible_port + - name: ansible_netconf_port + timeout: + type: int + description: + - Connection timeout in seconds + default: 120 + host_key_checking: + type: boolean + description: + - Flag to control wether we check for validity of the host key of the remote + default: True +# TODO: +#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS, +#allow_agent=self.allow_agent, +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/network_cli.py b/lib/ansible/plugins/connection/network_cli.py index f506298385..365d045c75 100644 --- a/lib/ansible/plugins/connection/network_cli.py +++ b/lib/ansible/plugins/connection/network_cli.py @@ -1,20 +1,42 @@ -# # (c) 2016 Red Hat Inc. -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Networking Team + connection: network_cli + short_description: Use network_cli to run command on network appliances + description: + - This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance. + - Also this plugin ignores the become_method but still uses the becoe_user and become_pass to + do privilege escalation, method depending on network_os used. + version_added: "2.3" + options: + network_os: + description: + - Appliance specific OS + default: 'default' + vars: + - name: ansible_netconf_network_os + password: + description: + - Secret used to authenticate + vars: + - name: ansible_pass + - name: ansible_netconf_pass + private_key_file: + description: + - Key or certificate file used for authentication + vars: + - name: ansible_private_key_file + timeout: + type: int + description: + - Connection timeout in seconds + default: 120 +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/paramiko_ssh.py b/lib/ansible/plugins/connection/paramiko_ssh.py index 17cb287c24..a6d0e5c377 100644 --- a/lib/ansible/plugins/connection/paramiko_ssh.py +++ b/lib/ansible/plugins/connection/paramiko_ssh.py @@ -1,29 +1,55 @@ # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +""" +DOCUMENTATION: + author: Ansible Core Team + connection: paramiko + short_description: Run tasks via python ssh (paramiko) + description: + - Use the python ssh implementation (Paramiko) to connect to targets + - The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist + in their SSH implementations. + - This is needed on the Ansible control machine to be reasonably efficient with connections. + Thus paramiko is faster for most users on these platforms. + Users with ControlPersist capability can consider using -c ssh or configuring the transport in the configuration file. + version_added: "0.1" + options: + remote_addr: + description: + - Address of the remote target + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_ssh_host + - name: ansible_paramiko_host + remote_user: + description: + - User to login/authenticate as + vars: + - name: ansible_user + - name: ansible_ssh_user + - name: ansible_paramiko_user +# TODO: +#getattr(self._play_context, 'ssh_extra_args', '') or '', +#getattr(self._play_context, 'ssh_common_args', '') or '', +#getattr(self._play_context, 'ssh_args', '') or '', +#C.HOST_KEY_CHECKING +#C.PARAMIKO_HOST_KEY_AUTO_ADD +#C.USE_PERSISTENT_CONNECTIONS: +# ssh.connect( +# look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS, +# key_filename, +# password=self._play_context.password, +# timeout=self._play_context.timeout, +# port=port, +#proxy_command = proxy_command or C.PARAMIKO_PROXY_COMMAND +#C.PARAMIKO_PTY +#C.PARAMIKO_RECORD_HOST_KEYS +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type -# --- -# The paramiko transport is provided because many distributions, in particular EL6 and before -# do not support ControlPersist in their SSH implementations. This is needed on the Ansible -# control machine to be reasonably efficient with connections. Thus paramiko is faster -# for most users on these platforms. Users with ControlPersist capability can consider -# using -c ssh or configuring the transport in ansible.cfg. - import warnings import os import socket diff --git a/lib/ansible/plugins/connection/persistent.py b/lib/ansible/plugins/connection/persistent.py index 9cad2d5604..6abdf00d7d 100644 --- a/lib/ansible/plugins/connection/persistent.py +++ b/lib/ansible/plugins/connection/persistent.py @@ -1,19 +1,16 @@ # (c) 2017 Red Hat Inc. -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Core Team + connection: persistent + short_description: Use a persistent unix socket for connection + description: + - This is a helper plugin to allow making other connections persistent. + version_added: "2.3" +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/saltstack.py b/lib/ansible/plugins/connection/saltstack.py index a41797d2cb..250d92fdf2 100644 --- a/lib/ansible/plugins/connection/saltstack.py +++ b/lib/ansible/plugins/connection/saltstack.py @@ -2,26 +2,29 @@ # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com> # Based on func.py # (c) 2014, Michael Scherer <misc@zarb.org> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# --- -# The saltstack transport permit to use ansible over saltstack. For -# people who have already setup saltstack and that wish to play with -# ansible, this permit to use both of them. +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Michael Scherer <misc@zarb.org> + connection: saltstack + short_description: Allow ansible to piggyback on salt minions + description: + - This allows you to use existing Saltstack infrastructure to connect to targets. + version_added: "2.2" +""" + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +import re +import os +import pty +import subprocess + +from ansible.module_utils._text import to_bytes, to_text +from ansible.module_utils.six.moves import cPickle from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/ssh.py b/lib/ansible/plugins/connection/ssh.py index bbdef533da..6b3d1ab3fa 100644 --- a/lib/ansible/plugins/connection/ssh.py +++ b/lib/ansible/plugins/connection/ssh.py @@ -1,22 +1,9 @@ -# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> +# Copyright (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> # Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com> # Copyright 2017 Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. -# +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: connection: ssh @@ -26,114 +13,111 @@ DOCUMENTATION: author: ansible (@core) version_added: historical options: - host: - description: Hostname/ip to connect to. - default: inventory_hostname - vars: - - name: ansible_host - - name: ansible_ssh_host - host_key_checking: - constants: - - name: HOST_KEY_CHECKING - description: Determines if ssh should check host keys - type: boolean - ini: - - section: defaults - key: 'host_key_checking' - env: - - name: ANSIBLE_HOST_KEY_CHECKING - password: - description: Authentication password for the C(remote_user). Can be supplied as CLI option. - vars: - - name: ansible_password - - name: ansible_ssh_pass - ssh_args: - description: Arguments to pass to all ssh cli tools - default: '-C -o ControlMaster=auto -o ControlPersist=60s' - ini: - - section: 'ssh_connection' - key: 'ssh_args' - env: - - name: ANSIBLE_SSH_ARGS - ssh_common_args: - description: Common extra args for all ssh CLI tools - vars: - - name: ansible_ssh_common_args - ssh_executable: - default: ssh - description: - - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH. - - 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. - env: [{name: ANSIBLE_SSH_EXECUTABLE}] - ini: - - {key: ssh_executable, section: ssh_connection} - yaml: {key: ssh_connection.ssh_executable} - const: - - name: ANSIBLE_SSH_EXECUTABLE - version_added: "2.2" - scp_extra_args: - description: Extra exclusive to the 'scp' CLI - vars: - - name: ansible_scp_extra_args - sftp_extra_args: - description: Extra exclusive to the 'sftp' CLI - vars: - - name: ansible_sftp_extra_args - ssh_extra_args: - description: Extra exclusive to the 'ssh' CLI - vars: - - name: ansible_ssh_extra_args - ssh_retries: - # constant: ANSIBLE_SSH_RETRIES - description: Number of attempts to connect. - default: 3 - env: - - name: ANSIBLE_SSH_RETRIES - ini: - - section: connection - key: retries - - section: ssh_connection - key: retries - port: - description: Remote port to connect to. - type: int - default: 22 - ini: - - section: defaults - key: remote_port - env: - - name: ANSIBLE_REMOTE_PORT - vars: - - name: ansible_port - - name: ansible_ssh_port - remote_user: - description: - - User name with which to login to the remote server, normally set by the remote_user keyword. - - If no user is supplied, Ansible will let the ssh client binary choose the user as it normally - ini: + host: + description: Hostname/ip to connect to. + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_ssh_host + host_key_checking: + #constant: HOST_KEY_CHECKING + description: Determines if ssh should check host keys + type: boolean + ini: - section: defaults - key: remote_user - env: - - name: ANSIBLE_REMOTE_USER - vars: - - name: ansible_user - - name: ansible_ssh_user - pipelining: - default: ANSIBLE_PIPELINING - description: - - 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 this conflicts with privilege escalation (become). - For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts, - which is why this feature is disabled by default. - env: [{name: ANSIBLE_SSH_PIPELINING}] - ini: - - {key: pipelining, section: ssh_connection} - type: boolean - vars: [{name: ansible_ssh_pipelining}] - + key: 'host_key_checking' + env: + - name: ANSIBLE_HOST_KEY_CHECKING + password: + description: Authentication password for the C(remote_user). Can be supplied as CLI option. + vars: + - name: ansible_password + - name: ansible_ssh_pass + ssh_args: + description: Arguments to pass to all ssh cli tools + default: '-C -o ControlMaster=auto -o ControlPersist=60s' + ini: + - section: 'ssh_connection' + key: 'ssh_args' + env: + - name: ANSIBLE_SSH_ARGS + ssh_common_args: + description: Common extra args for all ssh CLI tools + vars: + - name: ansible_ssh_common_args + ssh_executable: + default: ssh + description: + - This defines the location of the ssh binary. It defaults to `ssh` which will use the first ssh binary available in $PATH. + - 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. + env: [{name: ANSIBLE_SSH_EXECUTABLE}] + ini: + - {key: ssh_executable, section: ssh_connection} + yaml: {key: ssh_connection.ssh_executable} + #const: ANSIBLE_SSH_EXECUTABLE + version_added: "2.2" + scp_extra_args: + description: Extra exclusive to the 'scp' CLI + vars: + - name: ansible_scp_extra_args + sftp_extra_args: + description: Extra exclusive to the 'sftp' CLI + vars: + - name: ansible_sftp_extra_args + ssh_extra_args: + description: Extra exclusive to the 'ssh' CLI + vars: + - name: ansible_ssh_extra_args + ssh_retries: + # constant: ANSIBLE_SSH_RETRIES + description: Number of attempts to connect. + default: 3 + env: + - name: ANSIBLE_SSH_RETRIES + ini: + - section: connection + key: retries + - section: ssh_connection + key: retries + port: + description: Remote port to connect to. + type: int + default: 22 + ini: + - section: defaults + key: remote_port + env: + - name: ANSIBLE_REMOTE_PORT + vars: + - name: ansible_port + - name: ansible_ssh_port + remote_user: + description: + - User name with which to login to the remote server, normally set by the remote_user keyword. + - If no user is supplied, Ansible will let the ssh client binary choose the user as it normally + ini: + - section: defaults + key: remote_user + env: + - name: ANSIBLE_REMOTE_USER + vars: + - name: ansible_user + - name: ansible_ssh_user + pipelining: + default: ANSIBLE_PIPELINING + description: + - 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 this conflicts with privilege escalation (become). + For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts, + which is why this feature is disabled by default. + env: [{name: ANSIBLE_SSH_PIPELINING}] + ini: + - {key: pipelining, section: ssh_connection} + type: boolean + vars: [{name: ansible_ssh_pipelining}] # TODO: # ANSIBLE_SSH_RETRIES @@ -152,7 +136,6 @@ import fcntl import hashlib import os import pty -import socket import subprocess import time @@ -850,7 +833,6 @@ class Connection(ConnectionBase): else: methods = ['sftp'] - success = False for method in methods: returncode = stdout = stderr = None if method == 'sftp': diff --git a/lib/ansible/plugins/connection/winrm.py b/lib/ansible/plugins/connection/winrm.py index 23248ee7f2..1243023f2b 100644 --- a/lib/ansible/plugins/connection/winrm.py +++ b/lib/ansible/plugins/connection/winrm.py @@ -1,19 +1,30 @@ # (c) 2014, Chris Church <chris@ninemoreminutes.com> -# -# This file is part of Ansible. -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Core Team + connection: winrm + short_description: Run tasks over Microsoft's WinRM + description: + - Run commands or put/fetch on a target via WinRM + version_added: "2.0" + options: + remote_addr: + description: + - Address of the windows machine + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_winrm_host + remote_user: + description: + - The user to log in as to the Windows machine + vars: + - name: ansible_user + - name: ansible_winrm_user +""" from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/connection/zone.py b/lib/ansible/plugins/connection/zone.py index e7b82ed669..62238195f3 100644 --- a/lib/ansible/plugins/connection/zone.py +++ b/lib/ansible/plugins/connection/zone.py @@ -3,21 +3,27 @@ # and jail.py (c) 2013, Michael Scherer <misc@zarb.org> # (c) 2015, Dagobert Michelsen <dam@baltic-online.de> # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +DOCUMENTATION: + author: Ansible Core Team + connection: zone + short_description: Run tasks in a zone instance + description: + - Run commands or put/fetch files to an existing zone + version_added: "2.0" + options: + remote_addr: + description: + - Zone identifire + default: inventory_hostname + vars: + - name: ansible_host + - name: ansible_zone_host +""" + from __future__ import (absolute_import, division, print_function) __metaclass__ = type diff --git a/lib/ansible/plugins/inventory/advanced_host_list.py b/lib/ansible/plugins/inventory/advanced_host_list.py index 751d210f71..a4c6934351 100644 --- a/lib/ansible/plugins/inventory/advanced_host_list.py +++ b/lib/ansible/plugins/inventory/advanced_host_list.py @@ -1,20 +1,6 @@ -# Copyright 2017 RedHat, inc -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. -############################################# +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: inventory: advanced_host_list diff --git a/lib/ansible/plugins/inventory/constructed.py b/lib/ansible/plugins/inventory/constructed.py index 7651394703..72d112e010 100644 --- a/lib/ansible/plugins/inventory/constructed.py +++ b/lib/ansible/plugins/inventory/constructed.py @@ -1,20 +1,6 @@ -# Copyright 2017 RedHat, inc -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. -############################################# +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: name: constructed @@ -27,25 +13,8 @@ DOCUMENTATION: - 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). - strict: - description: - - If true make invalid entries a fatal error, otherwise skip and continue - - Since it is possible to use facts in the expressions they might not always be available - and we ignore those errors by default. - type: boolean - default: False - compose: - description: create vars from jinja2 expressions - type: dictionary - default: {} - groups: - description: add hosts to group based on Jinja2 conditionals - type: dictionary - default: {} - keyed_groups: - description: add hosts to group based on the values of a variable - type: list - default: [] + extends_documentation_fragment: + - constructed EXAMPLES: | # inventory.config file in YAML format plugin: comstructed compose: diff --git a/lib/ansible/plugins/inventory/host_list.py b/lib/ansible/plugins/inventory/host_list.py index 0983e37ddd..6b1a8b8104 100644 --- a/lib/ansible/plugins/inventory/host_list.py +++ b/lib/ansible/plugins/inventory/host_list.py @@ -1,19 +1,6 @@ -# Copyright 2017 RedHat, inc -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + r''' DOCUMENTATION: inventory: host_list diff --git a/lib/ansible/plugins/inventory/ini.py b/lib/ansible/plugins/inventory/ini.py index 9351159adc..a84cdeee19 100644 --- a/lib/ansible/plugins/inventory/ini.py +++ b/lib/ansible/plugins/inventory/ini.py @@ -1,19 +1,5 @@ -# Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ''' DOCUMENTATION: diff --git a/lib/ansible/plugins/inventory/openstack.py b/lib/ansible/plugins/inventory/openstack.py index 6c9bae5fbe..61bb642ea2 100755..100644 --- a/lib/ansible/plugins/inventory/openstack.py +++ b/lib/ansible/plugins/inventory/openstack.py @@ -2,22 +2,9 @@ # Copyright (c) 2013, Jesse Keating <jesse.keating@rackspace.com> # Copyright (c) 2015, Hewlett-Packard Development Company, L.P. # Copyright (c) 2016, Rackspace Australia -# Copyright (c) 2017, Red Hat, Inc. -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: name: openstack diff --git a/lib/ansible/plugins/inventory/script.py b/lib/ansible/plugins/inventory/script.py index 3c8739ee49..a85be8f768 100644 --- a/lib/ansible/plugins/inventory/script.py +++ b/lib/ansible/plugins/inventory/script.py @@ -1,19 +1,7 @@ -# (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. +# Copyright (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: inventory: script diff --git a/lib/ansible/plugins/inventory/virtualbox.py b/lib/ansible/plugins/inventory/virtualbox.py index 5f24b393fb..5d105b984e 100644 --- a/lib/ansible/plugins/inventory/virtualbox.py +++ b/lib/ansible/plugins/inventory/virtualbox.py @@ -1,21 +1,6 @@ -# This file is part of Ansible, -# (c) 2012-2017, Michael DeHaan <michael.dehaan@gmail.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. -############################################# +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: name: virtualbox diff --git a/lib/ansible/plugins/inventory/yaml.py b/lib/ansible/plugins/inventory/yaml.py index a7ea874d85..2337fcf333 100644 --- a/lib/ansible/plugins/inventory/yaml.py +++ b/lib/ansible/plugins/inventory/yaml.py @@ -1,20 +1,6 @@ -# Copyright 2017 RedHat, inc -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. -############################################# +# Copyright (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + ''' DOCUMENTATION: inventory: yaml diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py index 4e4ddd33cc..1302bfbf5d 100644 --- a/lib/ansible/plugins/loader.py +++ b/lib/ansible/plugins/loader.py @@ -1,23 +1,9 @@ # (c) 2012, Daniel Hokka Zakrisson <daniel@hozac.com> # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> and others # (c) 2017, Toshio Kuratomi <tkuratomi@ansible.com> -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see <http://www.gnu.org/licenses/>. - -# Make coding more python3-ish +# (c) 2017 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + from __future__ import (absolute_import, division, print_function) __metaclass__ = type @@ -62,6 +48,8 @@ class PluginLoader: self.base_class = required_base_class self.package = package self.subdir = subdir + + # FIXME: remove alias dict in favor of alias by symlink? self.aliases = aliases if config and not isinstance(config, list): @@ -239,7 +227,7 @@ class PluginLoader: self._extra_dirs.append(directory) self._paths = None - def find_plugin(self, name, mod_type='', ignore_deprecated=False): + def find_plugin(self, name, mod_type='', ignore_deprecated=False, check_aliases=False): ''' Find a plugin named name ''' if mod_type: @@ -252,6 +240,9 @@ class PluginLoader: # they can have any suffix suffix = '' + if check_aliases: + name = self.aliases.get(name, name) + # The particular cache to look for modules within. This matches the # requested mod_type pull_cache = self._plugin_path_cache[suffix] diff --git a/lib/ansible/plugins/shell/__init__.py b/lib/ansible/plugins/shell/__init__.py index eafd88d6a2..4b057f23ae 100644 --- a/lib/ansible/plugins/shell/__init__.py +++ b/lib/ansible/plugins/shell/__init__.py @@ -25,13 +25,17 @@ import random from ansible.module_utils.six import text_type from ansible.module_utils.six.moves import shlex_quote +from ansible.plugins import AnsiblePlugin _USER_HOME_PATH_RE = re.compile(r'^~[_.A-Za-z0-9][-_.A-Za-z0-9]*$') -class ShellBase(object): +class ShellBase(AnsiblePlugin): def __init__(self): + + super(ShellBase, self).__init__() + self.env = dict() if C.DEFAULT_MODULE_SET_LOCALE: module_locale = C.DEFAULT_MODULE_LANG or os.getenv('LANG', 'en_US.UTF-8') diff --git a/lib/ansible/plugins/strategy/linear.py b/lib/ansible/plugins/strategy/linear.py index 250be3d6e0..05afae28ef 100644 --- a/lib/ansible/plugins/strategy/linear.py +++ b/lib/ansible/plugins/strategy/linear.py @@ -24,7 +24,7 @@ DOCUMENTATION: the next series of hosts until the batch is done, before going on to the next task. version_added: "2.0" notes: - - This was the default Ansible behaviour before 'strategy plugins' were introduces in 2.0. + - This was the default Ansible behaviour before 'strategy plugins' were introduced in 2.0. author: Ansible Core Team ''' # Make coding more python3-ish diff --git a/lib/ansible/plugins/vars/host_group_vars.py b/lib/ansible/plugins/vars/host_group_vars.py index 6bae92eae0..bc4fd0a9dd 100644 --- a/lib/ansible/plugins/vars/host_group_vars.py +++ b/lib/ansible/plugins/vars/host_group_vars.py @@ -27,6 +27,18 @@ DOCUMENTATION: - Only applies to inventory sources that are existing paths. notes: - It takes the place of the previously hardcoded group_vars/host_vars loading. + options: + _valid_extensions: + default: [".yml", ".yaml", ".json"] + description: + - "Check all of these extensions when looking for 'variable' files which should be YAML or JSON or vaulted versions of these." + - 'This affects vars_files, include_vars, inventory and vars plugins among others.' + env: + - name: ANSIBLE_YAML_FILENAME_EXT + ini: + - section: yaml_valid_extensions + key: defaults + type: list ''' from __future__ import (absolute_import, division, print_function) diff --git a/lib/ansible/utils/display.py b/lib/ansible/utils/display.py index 4b41f21671..d5edfa5c22 100644 --- a/lib/ansible/utils/display.py +++ b/lib/ansible/utils/display.py @@ -193,14 +193,14 @@ class Display: if not removed: if version: - new_msg = "[DEPRECATION WARNING]: %s.\nThis feature will be removed in version %s." % (msg, version) + new_msg = "[DEPRECATION WARNING]: %s. This feature will be removed in version %s." % (msg, version) else: - new_msg = "[DEPRECATION WARNING]: %s.\nThis feature will be removed in a future release." % (msg) + new_msg = "[DEPRECATION WARNING]: %s. This feature will be removed in a future release." % (msg) new_msg = new_msg + " Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.\n\n" else: raise AnsibleError("[DEPRECATED]: %s.\nPlease update your playbooks." % msg) - wrapped = textwrap.wrap(new_msg, self.columns, replace_whitespace=False, drop_whitespace=False) + wrapped = textwrap.wrap(new_msg, self.columns, drop_whitespace=False) new_msg = "\n".join(wrapped) + "\n" if new_msg not in self._deprecations: diff --git a/lib/ansible/utils/module_docs_fragments/constructed.py b/lib/ansible/utils/module_docs_fragments/constructed.py new file mode 100644 index 0000000000..3b7fcdb892 --- /dev/null +++ b/lib/ansible/utils/module_docs_fragments/constructed.py @@ -0,0 +1,43 @@ +# +# (c) 2016, Sumit Kumar <sumit4@netapp.com> +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see <http://www.gnu.org/licenses/>. + + +class ModuleDocFragment(object): + + DOCUMENTATION = """ +options: + strict: + description: + - If true make invalid entries a fatal error, otherwise skip and continue + - Since it is possible to use facts in the expressions they might not always be available + and we ignore those errors by default. + type: boolean + default: False + compose: + description: create vars from jinja2 expressions + type: dictionary + default: {} + groups: + description: add hosts to group based on Jinja2 conditionals + type: dictionary + default: {} + keyed_groups: + description: add hosts to group based on the values of a variable + type: list + default: [] +""" diff --git a/lib/ansible/vars/manager.py b/lib/ansible/vars/manager.py index 854b545966..22d6caced0 100644 --- a/lib/ansible/vars/manager.py +++ b/lib/ansible/vars/manager.py @@ -103,6 +103,9 @@ def remove_internal_keys(data): class VariableManager: + _ALLOWED = frozenset(['plugins_by_group', 'groups_plugins_play', 'groups_plugins_inventory', 'groups_inventory', + 'all_plugins_play', 'all_plugins_inventory', 'all_inventory']) + def __init__(self, loader=None, inventory=None): self._nonpersistent_fact_cache = defaultdict(dict) @@ -283,7 +286,7 @@ class VariableManager: data = combine_vars(data, _get_plugin_vars(plugin, basedir, entities)) return data - # configurable functions that are sortable via config + # configurable functions that are sortable via config, rememer to add to _ALLOWED if expanding this list def all_inventory(): return all_group.get_vars() @@ -317,12 +320,13 @@ class VariableManager: return data # Merge as per precedence config + # only allow to call the functions we want exposed for entry in C.VARIABLE_PRECEDENCE: - # only allow to call the functions we want exposed - if entry.startswith('_') or '.' in entry: - continue - display.debug('Calling %s to load vars for %s' % (entry, host.name)) - all_vars = combine_vars(all_vars, locals()[entry]()) + if entry in self._ALLOWED: + display.debug('Calling %s to load vars for %s' % (entry, host.name)) + all_vars = combine_vars(all_vars, locals()[entry]()) + else: + display.warning('Ignoring unknown variable precedence entry: %s' % (entry)) # host vars, from inventory, inventory adjacent and play adjacent via plugins all_vars = combine_vars(all_vars, host.get_vars()) @@ -332,13 +336,8 @@ class VariableManager: # finally, the facts caches for this host, if it exists try: host_facts = wrap_var(self._fact_cache.get(host.name, {})) - if not C.ONLY_NAMESPACE_FACTS: - # allow facts to polute main namespace - all_vars = combine_vars(all_vars, host_facts) - - # always return namespaced facts - all_vars = combine_vars(all_vars, {'ansible_facts': host_facts}) - + # push facts to main namespace + all_vars = combine_vars(all_vars, host_facts) except KeyError: pass |