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

CHANGELOG.md

@@ -72,7 +72,7 @@ Ansible Changes By Release
 
 
 ### Minor Changes
-* Removed previously deprecated config option `hostfile` and env var `ANSIBLE_HOSTS`
+* Now deprecated configuration options issue warnings when set.
 * Removed unused and deprecated config option `pattern`
 * Updated the copy of six bundled for modules to use from 1.4.1 to 1.10.0
 * The `include_dir` var is not a global anymore, as we now allow multiple inventory sources, it is now host dependant.

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_@)

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

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

lib/ansible/config/manager.py

@@ -23,7 +23,8 @@ from ansible.utils.path import unfrackpath
 from ansible.utils.path import makedirs_safe
 
 Plugin = namedtuple('Plugin', 'name type')
-Setting = namedtuple('Setting','name value origin')
+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,6 +91,7 @@ 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 '''
@@ -92,6 +100,7 @@ def resolve_path(path):
 
     return unfrackpath(path, follow=False)
 
+
 # FIXME: generic file type?
 def get_config_type(cfile):
 
@@ -107,6 +116,7 @@ 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 '''
@@ -118,6 +128,7 @@ def get_ini_config_value(p, entry):
             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,7 +168,6 @@ class ConfigManager(object):
         self._config_file = conf_file
         self.data = ConfigData()
 
-
         # 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__))
@@ -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 '''
 
@@ -232,7 +241,8 @@ class ConfigManager(object):
                 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
 
@@ -277,7 +287,8 @@ class ConfigManager(object):
                         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':
@@ -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:

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?
+            value = ensure_type(eval(eval_string), setting.type)  # FIXME: safe eval?
-            continue
         except:
-            pass
+            value = setting.value
 
-    vars()[setting.name] = setting.value
+    set_constant(setting.name, setting.value)
 
 

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')

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, ''))
 

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):
+    def __init__(self):
-        return C.get_plugin_option(get_plugin_class(self), self.name, option)
+        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

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!
 

lib/ansible/plugins/cache/jsonfile.py

@@ -1,19 +1,7 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     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

lib/ansible/plugins/cache/memcached.py

@@ -1,19 +1,45 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    cache: memcached
-# (at your option) any later version.
+    short_description: Use memcached DB for cache
-#
+    description:
-# Ansible is distributed in the hope that it will be useful,
+        - This cache uses JSON formatted, per host records saved in memcached.
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    version_added: "1.9"
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    requirements:
-# GNU General Public License for more details.
+      - memcache (python lib)
-#
+    options:
-# You should have received a copy of the GNU General Public License
+      _uri:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+        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
 

lib/ansible/plugins/cache/memory.py

@@ -1,25 +1,15 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     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)
 '''

lib/ansible/plugins/cache/pickle.py

@@ -1,27 +1,41 @@
 # (c) 2017, Brian Coca
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
-    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

lib/ansible/plugins/cache/redis.py

@@ -1,19 +1,42 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+'''
-# Ansible is free software: you can redistribute it and/or modify
+DOCUMENTATION:
-# it under the terms of the GNU General Public License as published by
+    cache: redis
-# the Free Software Foundation, either version 3 of the License, or
+    short_description: Use Redis DB for cache
-# (at your option) any later version.
+    description:
-#
+        - This cache uses JSON formatted, per host records saved in Redis.
-# Ansible is distributed in the hope that it will be useful,
+    version_added: "1.9"
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    requirements:
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      - redis (python lib)
-# GNU General Public License for more details.
+    options:
-#
+      _uri:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+          - 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
 

lib/ansible/plugins/cache/yaml.py

@@ -1,19 +1,7 @@
 # (c) 2017, Brian Coca
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     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

lib/ansible/plugins/callback/actionable.py

@@ -1,20 +1,19 @@
 # (c) 2015, Andrew Gaffney <andrew@agaffney.org>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: actionable
-# (at your option) any later version.
+    type: stdout
-#
+    short_description: shows only items that need attention
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+      - Use this callback when you dont care about OK nor Skipped.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      - This callback suppreses any non Failed or Changed status.
-# GNU General Public License for more details.
+    version_added: "2.1"
-#
+    requirements:
-# You should have received a copy of the GNU General Public License
+      - set as stdout callback in configuration
-# 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

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
 

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
 

lib/ansible/plugins/callback/default.py

@@ -1,28 +1,40 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     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
 

lib/ansible/plugins/callback/dense.py

@@ -1,21 +1,18 @@
 # (c) 2016, Dag Wieers <dag@wieers.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# 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
+'''
+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
 

lib/ansible/plugins/callback/foreman.py

@@ -1,21 +1,42 @@
 # -*- coding: utf-8 -*-
-# (C) 2015, 2016 Daniel Lobato <elobatocs@gmail.com>
+# (c) 2015, 2016 Daniel Lobato <elobatocs@gmail.com>
-#     2016 Guido Günther <agx@sigxcpu.org>
+# (c) 2016 Guido Günther <agx@sigxcpu.org>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: foreman
-# (at your option) any later version.
+    type: notification
-#
+    short_description: Sends events to Foreman
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+      - This callback will report facts and task events to Foreman https://theforeman.org/
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.2"
-# GNU General Public License for more details.
+    requirements:
-#
+      - whitelisting in configuration
-# You should have received a copy of the GNU General Public License
+      - requests (python library)
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+    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

lib/ansible/plugins/callback/full_skip.py

@@ -1,20 +1,18 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# 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:
+    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

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
 

lib/ansible/plugins/callback/jabber.py

@@ -1,18 +1,41 @@
-# Ansible CallBack module for Jabber (XMPP)
 # Copyright (C) 2016 maxn nikolaev.makc@gmail.com
-#
+# Copyright (c) 2017 Ansible Project
-# This module is free software: you can redistribute it and/or modify
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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.
+DOCUMENTATION:
-#
+    callback: jabber
-# This program is distributed in the hope that it will be useful,
+    type: notification
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    short_description: post task events to a jabber server
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    description:
-# GNU General Public License for more details.
+      - 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.
-# You should have received a copy of the GNU General Public License
+    version_added: "2.2"
-# along with this program.  If not, see http://www.gnu.org/licenses/
+    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"""

lib/ansible/plugins/callback/json.py

@@ -1,29 +1,17 @@
 # (c) 2016, Matt Martz <matt@sivel.net>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# 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:
     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

lib/ansible/plugins/callback/junit.py

@@ -1,19 +1,44 @@
 # (c) 2016 Matt Clay <matt@mystile.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: junit
-# (at your option) any later version.
+    type: aggregate
-#
+    short_description: write playbook output to a JUnit file.
-# Ansible is distributed in the hope that it will be useful,
+    version_added: historical
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    description:
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      - This callback writes playbook output to a JUnit formatted XML file.
-# GNU General Public License for more details.
+      - "Tasks show up in the report as follows:
-#
+        'ok': pass
-# You should have received a copy of the GNU General Public License
+        'failed' with 'EXPECTED FAILURE' in the task name: pass
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+        '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

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
 

lib/ansible/plugins/callback/logentries.py

@@ -1,46 +1,84 @@
-""" (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com>
+# (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com>
-
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: logentries
-# (at your option) any later version.
+    type: notification
-#
+    short_description: Sends events to Logentries
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+      - This callback plugin will generate JSON objects and send them to Logentries for auditing/debugging purposes.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      - If you want to use an ini configuration, the file must be placed in the same directory as this plugin and named logentries.ini
-# GNU General Public License for more details.
+    version_added: "2.0"
-#
+    requirements:
-# You should have received a copy of the GNU General Public License
+      - whitelisting in configuration
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+      - certifi (python library)
-
+      - flatdict (pytnon library)
-This callback plugin will generate json objects to be sent to logentries
+    options:
-for auditing/debugging purposes.
+      api:
-
+        description: URI to the Logentries API
-Todo:
+        env:
-
+          - name: LOGENTRIES_API
-* Better formatting of output before sending out to logentries data/api nodes.
+        default: data.logentries.com
-
+        ini:
-To use:
+          - section: defaults
-
+            key: api
-Add this to your ansible.cfg file in the defaults block
+      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
-
     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
-
     [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 "
+        self.INVALID_TOKEN = ("\n\nIt appears the LOGENTRIES_TOKEN parameter you entered is incorrect!\n\n")
-                              "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. '
+            warn += 'The `certifi` python module is not installed.'
-                                  'Disabling the Logentries callback plugin.')
 
         if not HAS_FLATDICT:
             self.disabled = True
-            self._display.warning('The `flatdict` python module is not installed. '
+            warn += 'The `flatdict` python module is not installed.'
-                                  'Disabling the Logentries callback plugin.')
+
+        if warn:
+            self._display.warning('%s\nDisabling the Logentries callback plugin.' % warn)
 
         config_path = os.path.abspath(os.path.dirname(__file__))
         config = configparser.ConfigParser()

lib/ansible/plugins/callback/logstash.py

@@ -1,19 +1,35 @@
 # (C) 2016, Ievgen Khmelenko <ujenmr@gmail.com>
-#
+# (C) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: logstash
-# (at your option) any later version.
+    type: notification
-#
+    short_description: Sends events to Logstash
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+      - This callback will report facts and task events to Foreman https://theforeman.org/
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.3"
-# GNU General Public License for more details.
+    requirements:
-#
+      - whitelisting in configuration
-# You should have received a copy of the GNU General Public License
+      - logstash (python library)
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+    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

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
 

lib/ansible/plugins/callback/minimal.py

@@ -1,20 +1,18 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# 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:
+    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

lib/ansible/plugins/callback/oneline.py

@@ -1,19 +1,16 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: oneline
-# (at your option) any later version.
+    type: stdout
-#
+    short_description: oneline Ansible screen output
-# Ansible is distributed in the hope that it will be useful,
+    version_added: historical
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    description:
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        - This is the output callback used by the -o/--one-line command line option.
-# 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)

lib/ansible/plugins/callback/osx_say.py

@@ -1,20 +1,19 @@
-
+# (c) 2012, Michael DeHaan, <michael.dehaan@gmail.com>
-# (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)
-# This file is part of Ansible
+
-#
+'''
-# Ansible is free software: you can redistribute it and/or modify
+DOCUMENTATION:
-# it under the terms of the GNU General Public License as published by
+    callback: osx_say
-# the Free Software Foundation, either version 3 of the License, or
+    type: notification
-# (at your option) any later version.
+    requirements:
-#
+      - whitelising in configuration
-# Ansible is distributed in the hope that it will be useful,
+      - the '/usr/bin/say' command line program (standard on OS X)
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    short_description: oneline Ansible screen output
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: historical
-# GNU General Public License for more details.
+    description:
-#
+      - This plugin will use the 'say' program to "speak" about play events.
-# 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)

lib/ansible/plugins/callback/skippy.py

@@ -1,19 +1,17 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+'''
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    callback: skippy
-# (at your option) any later version.
+    callback_type: stdout
-#
+    requires: set as display
-# Ansible is distributed in the hope that it will be useful,
+    short_description: Ansible screen output that ignores skipped status
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    version_added: "2.0"
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    description:
-# GNU General Public License for more details.
+        - This callback does the same as the default except it does not output skipped host/task/item status
-#
+'''
-# 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)

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

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

lib/ansible/plugins/connection/buildah.py

@@ -1,29 +1,16 @@
 # 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)
@@ -33,13 +20,13 @@ DOCUMENTATION:
         description:
             - The ID of the container you want to access.
         default: inventory_hostname
-            config:
         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.
-            config:
         ini:
           - section: defaults
             key: remote_user
@@ -47,6 +34,8 @@ DOCUMENTATION:
           - name: ANSIBLE_REMOTE_USER
         vars:
           - name: ansible_user
+#        keyword:
+#            - name: remote_user
 """
 
 from __future__ import (absolute_import, division, print_function)

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>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Maykel Moya <mmoya@speedyrails.com>
-# (at your option) any later version.
+    connection: chroot
-#
+    short_description: Interact with local chroot
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing chroot on the Ansible controller.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "1.1"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

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>
-#
+# Copyright (c) 2017 Ansible Project
-# Maintainer: Leendert Brouwer (https://github.com/objectified)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# This file is part of Ansible
+"""
-#
+DOCUMENTATION:
-# Ansible is free software: you can redistribute it and/or modify
+    author:
-# it under the terms of the GNU General Public License as published by
+        - Lorin Hochestein
-# the Free Software Foundation, either version 3 of the License, or
+        - Leendert Brouwer
-# (at your option) any later version.
+    connection: docker
-#
+    short_description: Run tasks in docker containers
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing docker container.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_user:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

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>
+# Copyright (c) 2013, Michael Scherer <misc@zarb.org>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Michael Scherer (@msherer) <misc@zarb.org>
-# (at your option) any later version.
+    connection: funcd
-#
+    short_description: Use funcd to connect to target
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - This transport permits you to use Ansible over Func.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        - For people who have already setup func and that wish to play with ansible,
-# GNU General Public License for more details.
+          this permit to move gradually to ansible without having to redo completely the setup of the network.
-#
+    version_added: "1.1"
-# You should have received a copy of the GNU General Public License
+    options:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+      remote_addr:
-
+        description:
-# ---
+            - The path of the chroot you want to access.
-# The func transport permit to use ansible over func. For people who have already setup
+        default: inventory_hostname
-# func and that wish to play with ansible, this permit to move gradually to ansible
+        vars:
-# without having to redo completely the setup of the network.
+            - 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,
+    def exec_command(self, cmd, become_user=None, sudoable=False, executable='/bin/sh', in_data=None):
-                     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)),
+        shutil.move(os.path.join(tmpdir, self.host, os.path.basename(in_path)), out_path)
-                    out_path)
         shutil.rmtree(tmpdir)
 
     def close(self):

lib/ansible/plugins/connection/iocage.py

@@ -1,21 +1,33 @@
-# based on jail.py    (c) 2013, Michael Scherer <misc@zarb.org>
+# 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>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Stephan Lohse <dev-github@ploek.org>
-# (at your option) any later version.
+    connection: iocage
-#
+    short_description: Run tasks in iocage jails
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing iocage jail
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

lib/ansible/plugins/connection/jail.py

@@ -1,22 +1,34 @@
-# Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+# Based on local.py by Michael DeHaan <michael.dehaan@gmail.com>
-# and chroot.py     (c) 2013, Maykel Moya <mmoya@speedyrails.com>
+# and chroot.py by  Maykel Moya <mmoya@speedyrails.com>
-# (c) 2013, Michael Scherer <misc@zarb.org>
+# Copyright (c) 2013, Michael Scherer <misc@zarb.org>
-# (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
+# Copyright (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Core Team
-# (at your option) any later version.
+    connection: jail
-#
+    short_description: Run tasks in jails
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing jail
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

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>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Michael Scherer <misc@zarb.org>
-# (at your option) any later version.
+    connection: libvirt_lxc
-#
+    short_description: Run tasks in lxc containers via libvirt
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing lxc container using libvirt
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

lib/ansible/plugins/connection/lxc.py

@@ -1,19 +1,31 @@
 # (c) 2015, Joerg Thalheim <joerg@higgsboson.tk>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Joerg Thalheim <joerg@higgsboson.tk>
-# (at your option) any later version.
+    connection: lxc
-#
+    short_description: Run tasks in lxc containers via lxc python library
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing lxc container using lxc python library
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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

lib/ansible/plugins/connection/lxd.py

@@ -1,19 +1,31 @@
 # (c) 2016 Matt Clay <matt@mystile.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Matt Clay <matt@mystile.com>
-# (at your option) any later version.
+    connection: lxd
-#
+    short_description: Run tasks in lxc containers via lxc CLI
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing lxc container using lxc CLI
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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

lib/ansible/plugins/connection/netconf.py

@@ -1,20 +1,71 @@
-#
 # (c) 2016 Red Hat Inc.
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Networking Team
-# (at your option) any later version.
+    connection: netconf
-#
+    short_description: Use netconf to run command on network appliances
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Use netconf to run command on network appliances
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.3"
-# GNU General Public License for more details.
+    options:
-#
+      network_os:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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
 

lib/ansible/plugins/connection/network_cli.py

@@ -1,20 +1,42 @@
-#
 # (c) 2016 Red Hat Inc.
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Networking Team
-# (at your option) any later version.
+    connection: network_cli
-#
+    short_description: Use network_cli to run command on network appliances
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        - Also this plugin ignores the become_method but still uses the becoe_user and become_pass to
-# GNU General Public License for more details.
+          do privilege escalation, method depending on network_os used.
-#
+    version_added: "2.3"
-# You should have received a copy of the GNU General Public License
+    options:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+      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
 

lib/ansible/plugins/connection/paramiko_ssh.py

@@ -1,29 +1,55 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+"""
-# Ansible is free software: you can redistribute it and/or modify
+DOCUMENTATION:
-# it under the terms of the GNU General Public License as published by
+    author: Ansible Core Team
-# the Free Software Foundation, either version 3 of the License, or
+    connection: paramiko
-# (at your option) any later version.
+    short_description: Run tasks via python ssh (paramiko)
-#
+    description:
-# Ansible is distributed in the hope that it will be useful,
+        - Use the python ssh implementation (Paramiko) to connect to targets
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+          in their SSH implementations.
-# GNU General Public License for more details.
+        - This is needed on the Ansible control machine to be reasonably efficient with connections.
-#
+          Thus paramiko is faster for most users on these platforms.
-# You should have received a copy of the GNU General Public License
+          Users with ControlPersist capability can consider using -c ssh or configuring the transport in the configuration file.
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+    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

lib/ansible/plugins/connection/persistent.py

@@ -1,19 +1,16 @@
 # (c) 2017 Red Hat Inc.
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Core Team
-# (at your option) any later version.
+    connection: persistent
-#
+    short_description: Use a persistent unix socket for connection
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - This is a helper plugin to allow making other connections persistent.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.3"
-# 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/>.
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

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>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Michael Scherer <misc@zarb.org>
-# (at your option) any later version.
+    connection: saltstack
-#
+    short_description: Allow ansible to piggyback on salt minions
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - This allows you to use existing Saltstack infrastructure to connect to targets.
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.2"
-# GNU General Public License for more details.
+"""
-#
+
-# You should have received a copy of the GNU General Public License
+from __future__ import (absolute_import, division, print_function)
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+__metaclass__ = type
-
+
-# ---
+import re
-# The saltstack transport permit to use ansible over saltstack. For
+import os
-# people who have already setup saltstack and that wish to play with
+import pty
-# ansible, this permit to use both of them.
+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
 

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>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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: ssh
@@ -33,8 +20,7 @@ DOCUMENTATION:
                - name: ansible_host
                - name: ansible_ssh_host
       host_key_checking:
-            constants:
+          #constant: HOST_KEY_CHECKING
-                - name: HOST_KEY_CHECKING
           description: Determines if ssh should check host keys
           type: boolean
           ini:
@@ -69,8 +55,7 @@ DOCUMENTATION:
           ini:
           - {key: ssh_executable, section: ssh_connection}
           yaml: {key: ssh_connection.ssh_executable}
-            const:
+          #const: ANSIBLE_SSH_EXECUTABLE
-                - name: ANSIBLE_SSH_EXECUTABLE
           version_added: "2.2"
       scp_extra_args:
           description: Extra exclusive to the 'scp' CLI
@@ -133,7 +118,6 @@ DOCUMENTATION:
           - {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':

lib/ansible/plugins/connection/winrm.py

@@ -1,19 +1,30 @@
 # (c) 2014, Chris Church <chris@ninemoreminutes.com>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible.
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Core Team
-# (at your option) any later version.
+    connection: winrm
-#
+    short_description: Run tasks over Microsoft's WinRM
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch on a target via WinRM
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - 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

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>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+"""
-# it under the terms of the GNU General Public License as published by
+DOCUMENTATION:
-# the Free Software Foundation, either version 3 of the License, or
+    author: Ansible Core Team
-# (at your option) any later version.
+    connection: zone
-#
+    short_description: Run tasks in a zone instance
-# Ansible is distributed in the hope that it will be useful,
+    description:
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+        - Run commands or put/fetch files to an existing zone
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    version_added: "2.0"
-# GNU General Public License for more details.
+    options:
-#
+      remote_addr:
-# You should have received a copy of the GNU General Public License
+        description:
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+            - Zone identifire
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+            - name: ansible_zone_host
+"""
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 

lib/ansible/plugins/inventory/advanced_host_list.py

@@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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:
     inventory: advanced_host_list

lib/ansible/plugins/inventory/constructed.py

@@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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:
     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:
+    extends_documentation_fragment:
-        description:
+      - constructed
-            - 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: []
 EXAMPLES: | # inventory.config file in YAML format
     plugin: comstructed
     compose:

lib/ansible/plugins/inventory/host_list.py

@@ -1,19 +1,6 @@
-# Copyright 2017 RedHat, inc
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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/>.
 r'''
 DOCUMENTATION:
     inventory: host_list

lib/ansible/plugins/inventory/ini.py

@@ -1,19 +1,5 @@
-# Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com>
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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:

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.
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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:
     name: openstack

lib/ansible/plugins/inventory/script.py

@@ -1,19 +1,7 @@
-# (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
+# Copyright (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
+# Copyright (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     inventory: script

lib/ansible/plugins/inventory/virtualbox.py

@@ -1,21 +1,6 @@
-# This file is part of Ansible,
+# Copyright (c) 2017 Ansible Project
-# (c) 2012-2017, Michael DeHaan <michael.dehaan@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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:
     name: virtualbox

lib/ansible/plugins/inventory/yaml.py

@@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
+# Copyright (c) 2017 Ansible Project
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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:
     inventory: yaml

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>
-#
+# (c) 2017 Ansible Project
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# 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
 
@@ -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]

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')

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

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)

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:

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: []
+"""

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
-            for entry in C.VARIABLE_PRECEDENCE:
             # only allow to call the functions we want exposed
-                if entry.startswith('_') or '.' in entry:
+            for entry in C.VARIABLE_PRECEDENCE:
-                    continue
+                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:
+                # push facts to main namespace
-                    # 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})
-
             except KeyError:
                 pass