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
2017-08-20 11:20:30 -04:00 · 2017-08-20 11:20:30 -04:00 · 075ead8fb0
commit 075ead8fb0
parent f88750d665
70 changed files with 1862 additions and 1292 deletions
--- a/CHANGELOG.md
+++ b/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.
--- a/lib/ansible/cli/init.py
+++ b/lib/ansible/cli/init.py
@ -168,6 +168,17 @@ class CLI(with_metaclass(ABCMeta, object)):
        else:
            display.v(u"No config file found; using defaults")

+        # warn about deprecated options
+        for deprecated in C.config.DEPRECATED:
+            name = deprecated[0]
+            why = deprecated[1]['why']
+            if 'alternative' in deprecated[1]:
+                alt = ', use %s instead' % deprecated[1]['alternative']
+            else:
+                alt = ''
+            ver = deprecated[1]['version']
+            display.deprecated("%s option, %s %s" % (name, why, alt), version=ver)
+
    @staticmethod
    def split_vault_id(vault_id):
        # return (before_@, after_@)
--- a/lib/ansible/cli/config.py
+++ b/lib/ansible/cli/config.py
@ -44,7 +44,7 @@ except ImportError:
 class ConfigCLI(CLI):
    """ Config command line class """

-    VALID_ACTIONS = ("view", "edit", "update", "dump", "list")
+    VALID_ACTIONS = ("view", "dump", "list") # TODO: edit, update, search

    def __init__(self, args, callback=None):

@ -59,7 +59,6 @@ class ConfigCLI(CLI):
            epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]),
            desc="View, edit, and manage ansible configuration.",
        )
-
        self.parser.add_option('-c', '--config', dest='config_file', help="path to configuration file, defaults to first file found in precedence.")

        self.set_action()
@ -70,14 +69,11 @@ class ConfigCLI(CLI):
        if self.action == "dump":
            self.parser.add_option('--only-changed', dest='only_changed', action='store_true',
                                   help="Only show configurations that have changed from the default")
-            self.parser.set_usage("usage: %prog dump [options] [-c ansible.cfg]")
-        elif self.action == "view":
-            self.parser.set_usage("usage: %prog view [options] [-c ansible.cfg] ")
-        elif self.action == "edit":
-            self.parser.set_usage("usage: %prog edit [options] [-c ansible.cfg]")
        elif self.action == "update":
            self.parser.add_option('-s', '--setting', dest='setting', help="config setting, the section defaults to 'defaults'")
            self.parser.set_usage("usage: %prog update [options] [-c ansible.cfg] -s '[section.]setting=value'")
+        elif self.action == "search":
+            self.parser.set_usage("usage: %prog update [options] [-c ansible.cfg] <search term>")

        self.options, self.args = self.parser.parse_args()
        display.verbosity = self.options.verbosity
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@ -30,7 +30,8 @@ from ansible.cli import CLI
 from ansible.errors import AnsibleError, AnsibleOptionsError
 from ansible.module_utils.six import string_types
 from ansible.parsing.yaml.dumper import AnsibleDumper
-from ansible.plugins.loader import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, connection_loader, strategy_loader, PluginLoader
+from ansible.plugins.loader import module_loader, action_loader, lookup_loader, callback_loader, cache_loader, \
+    vars_loader, connection_loader, strategy_loader, PluginLoader
 from ansible.utils import plugin_docs
 try:
    from __main__ import display
@ -53,7 +54,7 @@ class DocCLI(CLI):
    def parse(self):

        self.parser = CLI.base_parser(
-            usage='usage: %prog [options] [plugin]',
+            usage='usage: %prog [-l|-s|-a] [options] [-t <plugin type] [plugin]',
            module_opts=True,
            desc="plugin documentation tool",
            epilog="See man pages for Ansible CLI options or website for tutorials https://docs.ansible.com"
@ -67,10 +68,13 @@ class DocCLI(CLI):
                               help='Show documentation for all plugins')
        self.parser.add_option("-t", "--type", action="store", default='module', dest='type', type='choice',
                               help='Choose which plugin type (defaults to "module")',
-                               choices=['cache', 'callback', 'connection', 'inventory', 'lookup', 'module', 'strategy'])
+                               choices=['cache', 'callback', 'connection', 'inventory', 'lookup', 'module', 'strategy', 'vars'])

        super(DocCLI, self).parse()

+        if [self.options.all_plugins, self.options.list_dir, self.options.show_snippet].count(True) > 1:
+            raise AnsibleOptionsError("Only one of -l, -a or -s can be used at the same time.")
+
        display.verbosity = self.options.verbosity

    def run(self):
@ -90,6 +94,8 @@ class DocCLI(CLI):
            loader = lookup_loader
        elif plugin_type == 'strategy':
            loader = strategy_loader
+        elif plugin_type == 'vars':
+            loader = vars_loader
        elif plugin_type == 'inventory':
            loader = PluginLoader('InventoryModule', 'ansible.plugins.inventory', 'inventory_plugins', 'inventory_plugins')
        else:
@ -118,6 +124,7 @@ class DocCLI(CLI):
            paths = loader._get_paths()
            for path in paths:
                self.find_plugins(path, plugin_type)
+            self.args = sorted(set(self.plugin_list))

        if len(self.args) == 0:
            raise AnsibleOptionsError("Incorrect options passed")
@ -128,7 +135,7 @@ class DocCLI(CLI):

            try:
                # if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
-                filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True)
+                filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True)
                if filename is None:
                    display.warning("%s %s not found in:\n%s\n" % (plugin_type, plugin, search_paths))
                    continue
@ -221,7 +228,7 @@ class DocCLI(CLI):
        for plugin in sorted(self.plugin_list):

            # if the module lives in a non-python file (eg, win_X.ps1), require the corresponding python file for docs
-            filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True)
+            filename = loader.find_plugin(plugin, mod_type='.py', ignore_deprecated=True, check_aliases=True)

            if filename is None:
                continue
--- a/lib/ansible/config/base.yml
+++ b/lib/ansible/config/base.yml
--- a/lib/ansible/config/manager.py
+++ b/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:
--- a/lib/ansible/constants.py
+++ b/lib/ansible/constants.py
@ -6,14 +6,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

-import os  # used to set lang
-
+import os  # used to set lang and for backwards compat get_config
 from string import ascii_letters, digits

 from ansible.module_utils._text import to_text
 from ansible.module_utils.parsing.convert_bool import boolean, BOOLEANS_TRUE
 from ansible.module_utils.six import string_types
-from ansible.config.manager import ConfigManager
+from ansible.config.manager import ConfigManager, ensure_type

 def _deprecated(msg):
    ''' display is not guaranteed here, nor it being the full class, but try anyways, fallback to sys.stderr.write '''
@ -33,8 +32,6 @@ def get_config(parser, section, key, env_var, default_value, value_type=None, ex
    ''' kept for backwarsd compatibility, but deprecated '''
    _deprecated('ansible.constants.get_config() is deprecated. There is new config API, see porting docs.')

-    import os
-
    value = None
    # small reconstruction of the old code env/ini/default
    value = os.environ.get(env_var, None)
@ -52,6 +49,10 @@ def get_config(parser, section, key, env_var, default_value, value_type=None, ex

    return value

+def set_constant(name, value, export=vars()):
+    ''' sets constants and returns resolved options dict '''
+    export[name] = value
+
 ### CONSTANTS ### yes, actual ones
 BLACKLIST_EXTS = ('.pyc', '.pyo', '.swp', '.bak', '~', '.rpm', '.md', '.txt')
 BECOME_METHODS = ['sudo', 'su', 'pbrun', 'pfexec', 'doas', 'dzdo', 'ksu', 'runas', 'pmrun']
@ -98,15 +99,15 @@ config = ConfigManager()
 # Generate constants from config
 for setting in config.data.get_settings():

-    # FIXME: find better way to do in manager class and/or ensure types
+    value = None
    if isinstance(setting.value, string_types) and (setting.value.startswith('eval(') and setting.value.endswith(')')):
        try:
+            # FIXME: find better way to do in manager class and/or ensure types
            eval_string = setting.value.replace('eval(', '', 1)[:-1]
-            vars()[setting.name] = eval(eval_string) # FIXME: safe eval?
-            continue
+            value = ensure_type(eval(eval_string), setting.type)  # FIXME: safe eval?
        except:
-            pass
+            value = setting.value

-    vars()[setting.name] = setting.value
+    set_constant(setting.name, setting.value)


--- a/lib/ansible/executor/task_executor.py
+++ b/lib/ansible/executor/task_executor.py
@ -414,6 +414,8 @@ class TaskExecutor:
            # We also add "magic" variables back into the variables dict to make sure
            # a certain subset of variables exist.
            self._play_context.update_vars(variables)
+
+            # FIXME: update connection/shell plugin options
        except AnsibleError as e:
            # save the error, which we'll raise later if we don't end up
            # skipping this task during the conditional evaluation step
@ -731,11 +733,11 @@ class TaskExecutor:
            conn_type = self._play_context.connection

        connection = self._shared_loader_obj.connection_loader.get(conn_type, self._play_context, self._new_stdin)
-        self._play_context.set_options_from_plugin(connection)
-
        if not connection:
            raise AnsibleError("the connection plugin '%s' was not found" % conn_type)

+        self._play_context.set_options_from_plugin(connection)
+
        if self._play_context.accelerate:
            # accelerate is deprecated as of 2.1...
            display.deprecated('Accelerated mode is deprecated. Consider using SSH with ControlPersist and pipelining enabled instead', version='2.6')
--- a/lib/ansible/playbook/play_context.py
+++ b/lib/ansible/playbook/play_context.py
@ -307,7 +307,7 @@ class PlayContext(Base):
            self.force_handlers = play.force_handlers

    def set_options_from_plugin(self, plugin):
-        # generic derived from connection plugin
+        # generic derived from connection plugin, temporary for backwards compat, in the end we should not set play_context properties

        # get options for plugins
        options = C.config.get_configuration_definitions(get_plugin_class(plugin), plugin._load_name)
@ -318,7 +318,7 @@ class PlayContext(Base):
                    setattr(self, flag, self.connection.get_option(flag))

        # TODO: made irrelavent by above
-        # get ssh options FIXME: make these common to all connections
+        # get ssh options
        # for flag in ('ssh_common_args', 'docker_extra_args', 'sftp_extra_args', 'scp_extra_args', 'ssh_extra_args'):
        #     setattr(self, flag, getattr(options, flag, ''))

--- a/lib/ansible/plugins/init.py
+++ b/lib/ansible/plugins/init.py
@ -44,5 +44,17 @@ def get_plugin_class(obj):

 class AnsiblePlugin(with_metaclass(ABCMeta, object)):

-    def get_option(self, option):
-        return C.get_plugin_option(get_plugin_class(self), self.name, option)
+    def __init__(self):
+        self.options = {}
+
+    def get_option(self, option, hostvars=None):
+        if option not in self.options:
+            option_value = C.config.get_config_value(option, plugin_type=get_plugin_class(self), plugin_name=self.name, variables=hostvars)
+            self.set_option(option, option_value)
+        return self.options.get(option)
+
+    def set_option(self, option, value):
+        self.options[option] = value
+
+    def set_options(self, options):
+        self.options = options
--- a/lib/ansible/plugins/action/init.py
+++ b/lib/ansible/plugins/action/init.py
@ -392,7 +392,7 @@ class ActionBase(with_metaclass(ABCMeta, object)):
            # we have a need for it, at which point we'll have to do something different.
            return remote_paths

-        if self._play_context.become and self._play_context.become_user not in ('root', remote_user):
+        if self._play_context.become and self._play_context.become_user and self._play_context.become_user not in ('root', remote_user):
            # Unprivileged user that's different than the ssh user.  Let's get
            # to work!

--- a/lib/ansible/plugins/cache/jsonfile.py
+++ b/lib/ansible/plugins/cache/jsonfile.py
@ -1,19 +1,7 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    cache: jsonfile
@ -21,8 +9,36 @@ DOCUMENTATION:
    description:
        - This cache uses JSON formatted, per host, files saved to the filesystem.
    version_added: "1.9"
-    author: Brian Coca (@bcoca)
+    author: Ansible Core
+    options:
+      _uri:
+        required: True
+        description:
+          - Path in which the cache plugin will save the JSON files
+        type: list
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+        ini:
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the JSON files
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+        ini:
+          - key: fact_caching_prefix
+          - section: defaults
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
+        type: integer
 '''
+
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/cache/memcached.py
+++ b/lib/ansible/plugins/cache/memcached.py
@ -1,19 +1,45 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    cache: memcached
+    short_description: Use memcached DB for cache
+    description:
+        - This cache uses JSON formatted, per host records saved in memcached.
+    version_added: "1.9"
+    requirements:
+      - memcache (python lib)
+    options:
+      _uri:
+        description:
+          - List of connection information for the memcached DBs
+        default: ['127.0.0.1:11211']
+        type: list
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+        ini:
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the DB entries
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+        ini:
+          - key: fact_caching_prefix
+          - section: defaults
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
+        type: integer
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/cache/memory.py
+++ b/lib/ansible/plugins/cache/memory.py
@ -1,25 +1,15 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    cache: memory
    short_description: RAM backed, non persistent
    description:
        - RAM backed cache that is not persistent.
+        - This is the default used if no other plugin is specified.
+        - There are no options to configure.
    version_added: historical
    author: core team (@ansible-core)
 '''
--- a/lib/ansible/plugins/cache/pickle.py
+++ b/lib/ansible/plugins/cache/pickle.py
@ -1,27 +1,41 @@
 # (c) 2017, Brian Coca
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
-    cache: yaml
+    cache: pickle
    short_description: Pickle formatted files.
    description:
        - This cache uses Python's pickle serialization format, in per host files, saved to the filesystem.
    version_added: "2.3"
    author: Brian Coca (@bcoca)
+    options:
+      _uri:
+        required: True
+        description:
+          - Path in which the cache plugin will save the files
+        type: list
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+        ini:
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the files
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+        ini:
+          - key: fact_caching_prefix
+          - section: defaults
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
 '''

 # Make coding more python3-ish
--- a/lib/ansible/plugins/cache/redis.py
+++ b/lib/ansible/plugins/cache/redis.py
@ -1,19 +1,42 @@
 # (c) 2014, Brian Coca, Josh Drake, et al
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+'''
+DOCUMENTATION:
+    cache: redis
+    short_description: Use Redis DB for cache
+    description:
+        - This cache uses JSON formatted, per host records saved in Redis.
+    version_added: "1.9"
+    requirements:
+      - redis (python lib)
+    options:
+      _uri:
+        description:
+          - A colon separated string of connection information for Redis.
+        required: True
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+        ini:
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the DB entries
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+        ini:
+          - key: fact_caching_prefix
+          - section: defaults
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
+        type: integer
+'''
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/cache/yaml.py
+++ b/lib/ansible/plugins/cache/yaml.py
@ -1,19 +1,7 @@
 # (c) 2017, Brian Coca
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    cache: yaml
@ -22,6 +10,33 @@ DOCUMENTATION:
        - This cache uses YAML formatted, per host, files saved to the filesystem.
    version_added: "2.3"
    author: Brian Coca (@bcoca)
+    options:
+      _uri:
+        required: True
+        description:
+          - Path in which the cache plugin will save the files
+        type: list
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
+        ini:
+          - key: fact_caching_connection
+            section: defaults
+      _prefix:
+        description: User defined prefix to use when creating the files
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_PREFIX
+        ini:
+          - key: fact_caching_prefix
+          - section: defaults
+      _timeout:
+        default: 86400
+        description: Expiration timeout for the cache plugin data
+        env:
+          - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
+        ini:
+          - key: fact_caching_timeout
+            section: defaults
+        type: integer
 '''

 # Make coding more python3-ish
--- a/lib/ansible/plugins/callback/actionable.py
+++ b/lib/ansible/plugins/callback/actionable.py
@ -1,20 +1,19 @@
 # (c) 2015, Andrew Gaffney <andrew@agaffney.org>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

+'''
+DOCUMENTATION:
+    callback: actionable
+    type: stdout
+    short_description: shows only items that need attention
+    description:
+      - Use this callback when you dont care about OK nor Skipped.
+      - This callback suppreses any non Failed or Changed status.
+    version_added: "2.1"
+    requirements:
+      - set as stdout callback in configuration
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/callback/context_demo.py
+++ b/lib/ansible/plugins/callback/context_demo.py
@ -1,21 +1,20 @@
 # (C) 2012, Michael DeHaan, <michael.dehaan@gmail.com>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# 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:
+    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
+'''

-# Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/debug.py
+++ b/lib/ansible/plugins/callback/debug.py
@ -1,3 +1,17 @@
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    callback: debug
+    type: stdout
+    short_description: formated stdout/stderr display
+    description:
+      - Use this callback to sort though extensive debug output
+    version_added: "2.4"
+    requirements:
+      - set as stdout in configuration
+'''
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/default.py
+++ b/lib/ansible/plugins/callback/default.py
@ -1,28 +1,40 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    callback: default
+    type: stdout
    short_description: default Ansible screen output
    version_added: historical
    description:
        - This is the default output callback for ansible-playbook.
+    options:
+      show_skipped_hosts:
+        name: Show skipped hosts
+        description: "Toggle to control displaying skipped task/host results in a task"
+        env:
+          - name: DISPLAY_SKIPPED_HOSTS
+        ini:
+          - key: display_skipped_hosts
+            section: defaults
+        type: boolean
+        default: True
+      show_custom_stats:
+        name: Show custom stats
+        default: False
+        description: 'This adds the custom stats set via the set_stats plugin to the play recap'
+        env:
+          - name: ANSIBLE_SHOW_CUSTOM_STATS
+        ini:
+          - key: show_custom_stats
+            section: defaults
+        type: bool
+    requirements:
+      - set as stdout in configuration
 '''
-# Make coding more python3-ish
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/dense.py
+++ b/lib/ansible/plugins/callback/dense.py
@ -1,21 +1,18 @@
 # (c) 2016, Dag Wieers <dag@wieers.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# 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

--- a/lib/ansible/plugins/callback/foreman.py
+++ b/lib/ansible/plugins/callback/foreman.py
@ -1,21 +1,42 @@
 # -*- coding: utf-8 -*-
-# (C) 2015, 2016 Daniel Lobato <elobatocs@gmail.com>
-#     2016 Guido Günther <agx@sigxcpu.org>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2015, 2016 Daniel Lobato <elobatocs@gmail.com>
+# (c) 2016 Guido Günther <agx@sigxcpu.org>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    callback: foreman
+    type: notification
+    short_description: Sends events to Foreman
+    description:
+      - This callback will report facts and task events to Foreman https://theforeman.org/
+    version_added: "2.2"
+    requirements:
+      - whitelisting in configuration
+      - requests (python library)
+    options:
+      url:
+        description: URL to the Foreman server
+        env:
+          - name: FOREMAN_URL
+        required: True
+      ssl_cert:
+        description: X509 certificate to authenticate to Foreman if https is used
+        env:
+            - name: FOREMAN_SSL_CERT
+      ssl_key:
+        description: the corresponding private key
+        env:
+          - name: FOREMAN_SSL_KEY
+      verify_certs:
+        description:
+          - Toggle to decidewhether to verify the Foreman certificate.
+          - It can be set to '1' to verify SSL certificates using the installed CAs or to a path pointing to a CA bundle.
+          - Set to '0' to disable certificate checking.
+        env:
+          - name: FOREMAN_SSL_VERIFY
+'''

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/callback/full_skip.py
+++ b/lib/ansible/plugins/callback/full_skip.py
@ -1,20 +1,18 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

+'''
+DOCUMENTATION:
+    callback: full_skip
+    type: stdout
+    short_description: suppreses tasks if all hosts skipped
+    description:
+      - Use this plugin when you dont care about any output for tasks that were completly skipped
+    version_added: "2.4"
+    requirements:
+      - set as stdout in configuation
+'''
 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/callback/hipchat.py
+++ b/lib/ansible/plugins/callback/hipchat.py
@ -1,21 +1,42 @@
 # (C) 2014, Matt Martz <matt@sivel.net>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# 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:
+    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
+'''

-# Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/jabber.py
+++ b/lib/ansible/plugins/callback/jabber.py
@ -1,18 +1,41 @@
-# Ansible CallBack module for Jabber (XMPP)
 # Copyright (C) 2016 maxn nikolaev.makc@gmail.com
-#
-# This module is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see http://www.gnu.org/licenses/
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    callback: jabber
+    type: notification
+    short_description: post task events to a jabber server
+    description:
+      - The chatty part of ChatOps with a Hipchat server as a target
+      - This callback plugin sends status updates to a HipChat channel during playbook execution.
+    version_added: "2.2"
+    requirements:
+      - xmpp (python lib https://github.com/ArchipelProject/xmpppy)
+    options:
+      server:
+        description: connection info to jabber server
+        required: True
+        env:
+          - name: JABBER_SERV
+      user:
+        description: Jabber user to authenticate as
+        required: True
+        env:
+          - name: JABBER_USER
+      password:
+        description: Password for the user to the jabber server
+        required: True
+        env:
+          - name: JABBER_PASS
+      to:
+        description: chat identifier that will recieve the message
+        required: True
+        env:
+          - name: JABBER_TO
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

@ -48,9 +71,9 @@ class CallbackModule(CallbackBase):
        self.j_pass = os.getenv('JABBER_PASS')
        self.j_to = os.getenv('JABBER_TO')

-        if (self.j_user or self.j_pass or self.serv) is None:
+        if (self.j_user or self.j_pass or self.serv or self.j_to) is None:
            self.disabled = True
-            self._display.warning('Jabber CallBack want JABBER_USER and JABBER_PASS env variables')
+            self._display.warning('Jabber CallBack wants the JABBER_SERV, JABBER_USER, JABBER_PASS and JABBER_TO environment variables')

    def send_msg(self, msg):
        """Send message"""
--- a/lib/ansible/plugins/callback/json.py
+++ b/lib/ansible/plugins/callback/json.py
@ -1,29 +1,17 @@
 # (c) 2016, Matt Martz <matt@sivel.net>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 '''
 DOCUMENTATION:
    callback: json
-    short_description: Ansbile screen output asjson
+    short_description: Ansbile screen output as JSON
    version_added: "2.2"
    description:
-        - This callback converts all events into JSON output
+        - This callback converts all events into JSON output to stdout
    type: stdout
-    plugin_api_version: "2.0"
+    requirements:
+      - Set as stdout in config
 '''

 # Make coding more python3-ish
--- a/lib/ansible/plugins/callback/junit.py
+++ b/lib/ansible/plugins/callback/junit.py
@ -1,19 +1,44 @@
 # (c) 2016 Matt Clay <matt@mystile.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    callback: junit
+    type: aggregate
+    short_description: write playbook output to a JUnit file.
+    version_added: historical
+    description:
+      - This callback writes playbook output to a JUnit formatted XML file.
+      - "Tasks show up in the report as follows:
+        'ok': pass
+        'failed' with 'EXPECTED FAILURE' in the task name: pass
+        'failed' due to an exception: error
+        'failed' for other reasons: failure
+        'skipped': skipped"
+    options:
+      output_dir:
+        name: JUnit output dir
+        default: ~/.ansible.log
+        description: Directory to write XML files to.
+        env:
+          - name: JUNIT_OUTPUT_DIR
+      task_class:
+        name: JUnit Task class
+        default: False
+        description: Configure the output to be one class per yaml file
+        env:
+          - name: JUNIT_TASK_CLASS
+      fail_on_change:
+        name: JUnit fail on change
+        default: False
+        description: Consider any tasks reporting "changed" as a junit test failure
+        env:
+          - name: JUNIT_FAIL_ON_CHANGE
+    requirements:
+      - whitelist in configuration
+      - junit_xml (python lib)
+'''

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/callback/log_plays.py
+++ b/lib/ansible/plugins/callback/log_plays.py
@ -1,21 +1,21 @@
 # (C) 2012, Michael DeHaan, <michael.dehaan@gmail.com>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# 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:
+    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
+'''

-# Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/logentries.py
+++ b/lib/ansible/plugins/callback/logentries.py
@ -1,46 +1,84 @@
-""" (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com>
+# (c) 2015, Logentries.com, Jimmy Tang <jimmy.tang@logentries.com>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
-This callback plugin will generate json objects to be sent to logentries
-for auditing/debugging purposes.
-
-Todo:
-
-* Better formatting of output before sending out to logentries data/api nodes.
-
-To use:
-
-Add this to your ansible.cfg file in the defaults block
+'''
+DOCUMENTATION:
+    callback: logentries
+    type: notification
+    short_description: Sends events to Logentries
+    description:
+      - This callback plugin will generate JSON objects and send them to Logentries for auditing/debugging purposes.
+      - If you want to use an ini configuration, the file must be placed in the same directory as this plugin and named logentries.ini
+    version_added: "2.0"
+    requirements:
+      - whitelisting in configuration
+      - certifi (python library)
+      - flatdict (pytnon library)
+    options:
+      api:
+        description: URI to the Logentries API
+        env:
+          - name: LOGENTRIES_API
+        default: data.logentries.com
+        ini:
+          - section: defaults
+            key: api
+      port:
+        description: Http port to use when connecting to the API
+        env:
+            - name: LOGENTRIES_PORT
+        default: 80
+        ini:
+          - section: defaults
+            key: port
+      tls_port:
+        description: Port to use when connecting to the API when TLS is enabled
+        env:
+            - name: LOGENTRIES_TLS_PORT
+        default: 443
+        ini:
+          - section: defaults
+            key: tls_port
+      token:
+        description: the authentication token
+        env:
+          - name: LOGENTRIES_ANSIBLE_TOKEN
+        required: True
+        ini:
+          - section: defaults
+            key: token
+      use_tls:
+        description:
+          - Toggle to decidewhether to use TLS to encrypt the communications with the API server
+        env:
+          - name: LOGENTRIES_USE_TLS
+        default: False
+        type: boolean
+        ini:
+          - section: defaults
+            key: use_tls
+      flatten:
+        description: flatten complex data structures into a single dictionary with complex keys
+        type: boolean
+        default: False
+        env:
+          - name: LOGENTRIES_FLATTEN
+        ini:
+          - section: defaults
+            key: flatten
+EXAMPLES: >
+  To enable, add this to your ansible.cfg file in the defaults block

    [defaults]
-    callback_plugins = ./callback_plugins
-    callback_stdout = logentries
    callback_whitelist = logentries

-Copy the callback plugin into the callback_plugins directory
-
  Either set the environment variables
-
    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 "
-                              "parameter you entered is incorrect!\n\n")
+        self.INVALID_TOKEN = ("\n\nIt appears the LOGENTRIES_TOKEN parameter you entered is incorrect!\n\n")
        # Unicode Line separator character   \u2028
        self.LINE_SEP = u'\u2028'

@ -189,15 +226,17 @@ class CallbackModule(CallbackBase):
        if not HAS_SSL:
            self._display.warning("Unable to import ssl module. Will send over port 80.")

+        warn = ''
        if not HAS_CERTIFI:
            self.disabled = True
-            self._display.warning('The `certifi` python module is not installed. '
-                                  'Disabling the Logentries callback plugin.')
+            warn += 'The `certifi` python module is not installed.'

        if not HAS_FLATDICT:
            self.disabled = True
-            self._display.warning('The `flatdict` python module is not installed. '
-                                  'Disabling the Logentries callback plugin.')
+            warn += 'The `flatdict` python module is not installed.'
+
+        if warn:
+            self._display.warning('%s\nDisabling the Logentries callback plugin.' % warn)

        config_path = os.path.abspath(os.path.dirname(__file__))
        config = configparser.ConfigParser()
--- a/lib/ansible/plugins/callback/logstash.py
+++ b/lib/ansible/plugins/callback/logstash.py
@ -1,19 +1,35 @@
 # (C) 2016, Ievgen Khmelenko <ujenmr@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (C) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+'''
+DOCUMENTATION:
+    callback: logstash
+    type: notification
+    short_description: Sends events to Logstash
+    description:
+      - This callback will report facts and task events to Foreman https://theforeman.org/
+    version_added: "2.3"
+    requirements:
+      - whitelisting in configuration
+      - logstash (python library)
+    options:
+      server:
+        description: Address of the Logstash server
+        env:
+          - name: LOGSTASH_SERVER
+        default: localhost
+      port:
+        description: Port on which logstash is listening
+        env:
+            - name: LOGSTASH_PORT
+        default: 5000
+      type:
+        description: Message type
+        env:
+          - name: LOGSTASH_TYPE
+        default: ansible
+'''

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/callback/mail.py
+++ b/lib/ansible/plugins/callback/mail.py
@ -1,8 +1,28 @@
 # -*- coding: utf-8 -*-
-
 # Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

+'''
+DOCUMENTATION:
+    callback: mail
+    type: notification
+    short_description: Sends failure events via email
+    description:
+      - This callback will report failures via email
+    version_added: "2.3"
+    requirements:
+      - whitelisting in configuration
+      - logstash (python library)
+    options:
+      mta:
+        description: Mail Transfer Agent, server that accepts SMTP
+        env:
+          - name: SMTPHOST
+        default: localhost
+    note:
+      - "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/callback/minimal.py
+++ b/lib/ansible/plugins/callback/minimal.py
@ -1,20 +1,18 @@
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

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

 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
--- a/lib/ansible/plugins/callback/osx_say.py
+++ b/lib/ansible/plugins/callback/osx_say.py
@ -1,20 +1,19 @@
+# (c) 2012, Michael DeHaan, <michael.dehaan@gmail.com>
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

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

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

 # Make coding more python3-ish
 from __future__ import (absolute_import, division, print_function)
--- a/lib/ansible/plugins/connection/init.py
+++ b/lib/ansible/plugins/connection/init.py
@ -70,6 +70,9 @@ class ConnectionBase(AnsiblePlugin):
    allow_executable = True

    def __init__(self, play_context, new_stdin, *args, **kwargs):
+
+        super(ConnectionBase, self).__init__()
+
        # All these hasattrs allow subclasses to override these parameters
        if not hasattr(self, '_play_context'):
            self._play_context = play_context
--- a/lib/ansible/plugins/connection/accelerate.py
+++ b/lib/ansible/plugins/connection/accelerate.py
@ -14,6 +14,18 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+"""
+DOCUMENTATION:
+    author: Ansible Core Team
+    connection: accelerate
+    short_description: Temporary 0mq agent
+    description:
+        - This plugin uses one of the other ssh plugins to setup a temporary 0mq daemon on the target to execute subsequent tasks
+    deprecated:
+        why: paramiko and ssh + controlpersist perform the same or better without the problems of having an agent.
+        version: 2.5
+        alternative: paramiko and ssh with conrol persistence.
+"""

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/connection/buildah.py
+++ b/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)
--- a/lib/ansible/plugins/connection/chroot.py
+++ b/lib/ansible/plugins/connection/chroot.py
@ -1,21 +1,37 @@
 # Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+#
 # (c) 2013, Maykel Moya <mmoya@speedyrails.com>
 # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Maykel Moya <mmoya@speedyrails.com>
+    connection: chroot
+    short_description: Interact with local chroot
+    description:
+        - Run commands or put/fetch files to an existing chroot on the Ansible controller.
+    version_added: "1.1"
+    options:
+      remote_addr:
+        description:
+            - The path of the chroot you want to access.
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+      executable:
+        description:
+            - User specified executable shell
+        ini:
+          - section: defaults
+            key: executable
+        env:
+          - name: ANSIBLE_EXECUTABLE
+        vars:
+          - name: ansible_executable
+"""
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/connection/docker.py
+++ b/lib/ansible/plugins/connection/docker.py
@ -1,26 +1,42 @@
 # Based on the chroot connection plugin by Maykel Moya
 #
-# Connection plugin for configuring docker containers
 # (c) 2014, Lorin Hochstein
-# (c) 2015, Leendert Brouwer
+# (c) 2015, Leendert Brouwer (https://github.com/objectified)
 # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# Maintainer: Leendert Brouwer (https://github.com/objectified)
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author:
+        - Lorin Hochestein
+        - Leendert Brouwer
+    connection: docker
+    short_description: Run tasks in docker containers
+    description:
+        - Run commands or put/fetch files to an existing docker container.
+    version_added: "2.0"
+    options:
+      remote_user:
+        description:
+            - The user to execute as inside the container
+        default: The set user as per docker's configuration
+        vars:
+            - name: ansible_user
+            - name: ansible_docker4_user
+      docker_extra_args:
+        description:
+            - Extra arguments to pass to the docker command line
+        default: ''
+      remote_addr:
+        description:
+            - The path of the chroot you want to access.
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+            - name: ansible_docker_host
+"""
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/connection/funcd.py
+++ b/lib/ansible/plugins/connection/funcd.py
@ -1,26 +1,28 @@
 # Based on local.py (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com>
-# (c) 2013, Michael Scherer <misc@zarb.org>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2013, Michael Scherer <misc@zarb.org>
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# ---
-# The func transport permit to use ansible over func. For people who have already setup
-# func and that wish to play with ansible, this permit to move gradually to ansible
-# without having to redo completely the setup of the network.
+"""
+DOCUMENTATION:
+    author: Michael Scherer (@msherer) <misc@zarb.org>
+    connection: funcd
+    short_description: Use funcd to connect to target
+    description:
+        - This transport permits you to use Ansible over Func.
+        - For people who have already setup func and that wish to play with ansible,
+          this permit to move gradually to ansible without having to redo completely the setup of the network.
+    version_added: "1.1"
+    options:
+      remote_addr:
+        description:
+            - The path of the chroot you want to access.
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+            - name: ansible_func_host
+"""
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

@ -61,8 +63,7 @@ class Connection(object):
        self.client = fc.Client(self.host)
        return self

-    def exec_command(self, cmd, become_user=None, sudoable=False,
-                     executable='/bin/sh', in_data=None):
+    def exec_command(self, cmd, become_user=None, sudoable=False, executable='/bin/sh', in_data=None):
        ''' run a command on the remote minion '''

        if in_data:
@ -96,8 +97,7 @@ class Connection(object):
        # take a file directly
        tmpdir = tempfile.mkdtemp(prefix="func_ansible")
        self.client.local.getfile.get(in_path, tmpdir)
-        shutil.move(os.path.join(tmpdir, self.host, os.path.basename(in_path)),
-                    out_path)
+        shutil.move(os.path.join(tmpdir, self.host, os.path.basename(in_path)), out_path)
        shutil.rmtree(tmpdir)

    def close(self):
--- a/lib/ansible/plugins/connection/iocage.py
+++ b/lib/ansible/plugins/connection/iocage.py
@ -1,21 +1,33 @@
-# based on jail.py    (c) 2013, Michael Scherer <misc@zarb.org>
+# Based on jail.py
+# (c) 2013, Michael Scherer <misc@zarb.org>
 # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
 # (c) 2016, Stephan Lohse <dev-github@ploek.org>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Stephan Lohse <dev-github@ploek.org>
+    connection: iocage
+    short_description: Run tasks in iocage jails
+    description:
+        - Run commands or put/fetch files to an existing iocage jail
+    version_added: "2.0"
+    options:
+      remote_addr:
+        description:
+            - Path to the jail
+        default: The set user as per docker's configuration
+        vars:
+            - name: ansible_host
+            - name: ansible_iocage_host
+      remote_user:
+        description:
+            - User to execute as inside the jail
+        vars:
+            - name: ansible_user
+            - name: ansible_iocage_user
+"""
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

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

--- a/lib/ansible/plugins/connection/libvirt_lxc.py
+++ b/lib/ansible/plugins/connection/libvirt_lxc.py
@ -2,21 +2,27 @@
 # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com>
 # (c) 2013, Michael Scherer <misc@zarb.org>
 # (c) 2015, Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Michael Scherer <misc@zarb.org>
+    connection: libvirt_lxc
+    short_description: Run tasks in lxc containers via libvirt
+    description:
+        - Run commands or put/fetch files to an existing lxc container using libvirt
+    version_added: "2.0"
+    options:
+      remote_addr:
+        description:
+            - Container identifier
+        default: The set user as per docker's configuration
+        vars:
+            - name: ansible_host
+            - name: ansible_libvirt_lxc_host
+"""
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

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

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/connection/lxd.py
+++ b/lib/ansible/plugins/connection/lxd.py
@ -1,19 +1,31 @@
 # (c) 2016 Matt Clay <matt@mystile.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Matt Clay <matt@mystile.com>
+    connection: lxd
+    short_description: Run tasks in lxc containers via lxc CLI
+    description:
+        - Run commands or put/fetch files to an existing lxc container using lxc CLI
+    version_added: "2.0"
+    options:
+      remote_addr:
+        description:
+            - Container identifier
+        default: The set user as per docker's configuration
+        vars:
+            - name: ansible_host
+            - name: ansible_lxd_host
+      executable:
+        description:
+            - shell to use for execution inside container
+        default: /bin/sh
+        vars:
+            - name: ansible_executable
+            - name: ansible_lxd_executable
+"""

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/connection/netconf.py
+++ b/lib/ansible/plugins/connection/netconf.py
@ -1,20 +1,71 @@
-#
 # (c) 2016 Red Hat Inc.
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Ansible Networking Team
+    connection: netconf
+    short_description: Use netconf to run command on network appliances
+    description:
+        - Use netconf to run command on network appliances
+    version_added: "2.3"
+    options:
+      network_os:
+        description:
+            - Appliance specific OS
+        default: 'default'
+        vars:
+            - name: ansible_netconf_network_os
+      password:
+        description:
+            - Secret used to authenticate
+        vars:
+            - name: ansible_pass
+            - name: ansible_netconf_pass
+      private_key_file:
+        description:
+            - Key or certificate file used for authentication
+        vars:
+            - name: ansible_private_key_file
+            - name: ansible_netconf_private_key_file
+      ssh_config:
+        type: boolean
+        default: False
+        description:
+            - Flag to decide if we use SSH configuration options with netconf
+        vars:
+            - name: ansible_netconf_ssh_config
+        env:
+            - name: ANSIBLE_NETCONF_SSH_CONFIG
+      user:
+        description:
+          - User to authenticate as
+        vars:
+          - name: ansible_user
+          - name: ansible_netconf_user
+      port:
+        type: int
+        description:
+          - port to connect to on the remote
+        default: 830
+        vars:
+          - name: ansible_port
+          - name: ansible_netconf_port
+      timeout:
+        type: int
+        description:
+          - Connection timeout in seconds
+        default: 120
+      host_key_checking:
+        type: boolean
+        description:
+          - Flag to control wether we check for validity of the host key of the remote
+        default: True
+# TODO:
+#look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
+#allow_agent=self.allow_agent,
+"""
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/connection/network_cli.py
+++ b/lib/ansible/plugins/connection/network_cli.py
@ -1,20 +1,42 @@
-#
 # (c) 2016 Red Hat Inc.
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Ansible Networking Team
+    connection: network_cli
+    short_description: Use network_cli to run command on network appliances
+    description:
+        - This plugin actually forces use of 'local' execution but using paramiko to establish a remote ssh shell on the appliance.
+        - Also this plugin ignores the become_method but still uses the becoe_user and become_pass to
+          do privilege escalation, method depending on network_os used.
+    version_added: "2.3"
+    options:
+      network_os:
+        description:
+            - Appliance specific OS
+        default: 'default'
+        vars:
+            - name: ansible_netconf_network_os
+      password:
+        description:
+            - Secret used to authenticate
+        vars:
+            - name: ansible_pass
+            - name: ansible_netconf_pass
+      private_key_file:
+        description:
+            - Key or certificate file used for authentication
+        vars:
+            - name: ansible_private_key_file
+      timeout:
+        type: int
+        description:
+          - Connection timeout in seconds
+        default: 120
+"""
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/connection/paramiko_ssh.py
+++ b/lib/ansible/plugins/connection/paramiko_ssh.py
@ -1,29 +1,55 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+"""
+DOCUMENTATION:
+    author: Ansible Core Team
+    connection: paramiko
+    short_description: Run tasks via python ssh (paramiko)
+    description:
+        - Use the python ssh implementation (Paramiko) to connect to targets
+        - The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist
+          in their SSH implementations.
+        - This is needed on the Ansible control machine to be reasonably efficient with connections.
+          Thus paramiko is faster for most users on these platforms.
+          Users with ControlPersist capability can consider using -c ssh or configuring the transport in the configuration file.
+    version_added: "0.1"
+    options:
+      remote_addr:
+        description:
+            - Address of the remote target
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+            - name: ansible_ssh_host
+            - name: ansible_paramiko_host
+      remote_user:
+        description:
+            - User to login/authenticate as
+        vars:
+            - name: ansible_user
+            - name: ansible_ssh_user
+            - name: ansible_paramiko_user
+# TODO:
+#getattr(self._play_context, 'ssh_extra_args', '') or '',
+#getattr(self._play_context, 'ssh_common_args', '') or '',
+#getattr(self._play_context, 'ssh_args', '') or '',
+#C.HOST_KEY_CHECKING
+#C.PARAMIKO_HOST_KEY_AUTO_ADD
+#C.USE_PERSISTENT_CONNECTIONS:
+#            ssh.connect(
+#                look_for_keys=C.PARAMIKO_LOOK_FOR_KEYS,
+#                key_filename,
+#                password=self._play_context.password,
+#                timeout=self._play_context.timeout,
+#                port=port,
+#proxy_command = proxy_command or C.PARAMIKO_PROXY_COMMAND
+#C.PARAMIKO_PTY
+#C.PARAMIKO_RECORD_HOST_KEYS
+"""
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

-# ---
-# The paramiko transport is provided because many distributions, in particular EL6 and before
-# do not support ControlPersist in their SSH implementations.  This is needed on the Ansible
-# control machine to be reasonably efficient with connections.  Thus paramiko is faster
-# for most users on these platforms.  Users with ControlPersist capability can consider
-# using -c ssh or configuring the transport in ansible.cfg.
-
 import warnings
 import os
 import socket
--- a/lib/ansible/plugins/connection/persistent.py
+++ b/lib/ansible/plugins/connection/persistent.py
@ -1,19 +1,16 @@
 # (c) 2017 Red Hat Inc.
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Ansible Core Team
+    connection: persistent
+    short_description: Use a persistent unix socket for connection
+    description:
+        - This is a helper plugin to allow making other connections persistent.
+    version_added: "2.3"
+"""

 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
--- a/lib/ansible/plugins/connection/saltstack.py
+++ b/lib/ansible/plugins/connection/saltstack.py
@ -2,26 +2,29 @@
 # Based on chroot.py (c) 2013, Maykel Moya <mmoya@speedyrails.com>
 # Based on func.py
 # (c) 2014, Michael Scherer <misc@zarb.org>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# ---
-# The saltstack transport permit to use ansible over saltstack. For
-# people who have already setup saltstack and that wish to play with
-# ansible, this permit to use both of them.
+"""
+DOCUMENTATION:
+    author: Michael Scherer <misc@zarb.org>
+    connection: saltstack
+    short_description: Allow ansible to piggyback on salt minions
+    description:
+        - This allows you to use existing Saltstack infrastructure to connect to targets.
+    version_added: "2.2"
+"""
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import re
+import os
+import pty
+import subprocess
+
+from ansible.module_utils._text import to_bytes, to_text
+from ansible.module_utils.six.moves import cPickle
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type

--- a/lib/ansible/plugins/connection/ssh.py
+++ b/lib/ansible/plugins/connection/ssh.py
@ -1,22 +1,9 @@
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+# Copyright (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com>
 # Copyright 2017 Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    connection: ssh
@ -33,8 +20,7 @@ DOCUMENTATION:
               - name: ansible_host
               - name: ansible_ssh_host
      host_key_checking:
-            constants:
-                - name: HOST_KEY_CHECKING
+          #constant: 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:
-                - name: ANSIBLE_SSH_EXECUTABLE
+          #const: 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':
--- a/lib/ansible/plugins/connection/winrm.py
+++ b/lib/ansible/plugins/connection/winrm.py
@ -1,19 +1,30 @@
 # (c) 2014, Chris Church <chris@ninemoreminutes.com>
-#
-# This file is part of Ansible.
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""
+DOCUMENTATION:
+    author: Ansible Core Team
+    connection: winrm
+    short_description: Run tasks over Microsoft's WinRM
+    description:
+        - Run commands or put/fetch on a target via WinRM
+    version_added: "2.0"
+    options:
+      remote_addr:
+        description:
+            - Address of the windows machine
+        default: inventory_hostname
+        vars:
+            - name: ansible_host
+            - name: ansible_winrm_host
+      remote_user:
+        description:
+            - The user to log in as to the Windows machine
+        vars:
+            - name: ansible_user
+            - name: ansible_winrm_user
+"""

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

--- a/lib/ansible/plugins/inventory/advanced_host_list.py
+++ b/lib/ansible/plugins/inventory/advanced_host_list.py
@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#############################################
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    inventory: advanced_host_list
--- a/lib/ansible/plugins/inventory/constructed.py
+++ b/lib/ansible/plugins/inventory/constructed.py
@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#############################################
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    name: constructed
@ -27,25 +13,8 @@ DOCUMENTATION:
        - The JInja2 exprpessions are calculated and assigned to the variables
        - Only variables already available from previous inventories can be used for templating.
        - Failed expressions will be ignored (assumes vars were missing).
-    strict:
-        description:
-            - If true make invalid entries a fatal error, otherwise skip and continue
-            - Since it is possible to use facts in the expressions they might not always be available
-              and we ignore those errors by default.
-        type: boolean
-        default: False
-    compose:
-        description: create vars from jinja2 expressions
-        type: dictionary
-        default: {}
-    groups:
-        description: add hosts to group based on Jinja2 conditionals
-        type: dictionary
-        default: {}
-    keyed_groups:
-        description: add hosts to group based on the values of a variable
-        type: list
-        default: []
+    extends_documentation_fragment:
+      - constructed
 EXAMPLES: | # inventory.config file in YAML format
    plugin: comstructed
    compose:
--- a/lib/ansible/plugins/inventory/host_list.py
+++ b/lib/ansible/plugins/inventory/host_list.py
@ -1,19 +1,6 @@
-# Copyright 2017 RedHat, inc
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 r'''
 DOCUMENTATION:
    inventory: host_list
--- a/lib/ansible/plugins/inventory/ini.py
+++ b/lib/ansible/plugins/inventory/ini.py
@ -1,19 +1,5 @@
-# Copyright 2015 Abhijit Menon-Sen <ams@2ndQuadrant.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 '''
 DOCUMENTATION:
--- a/lib/ansible/plugins/inventory/openstack.py
+++ b/lib/ansible/plugins/inventory/openstack.py
@ -2,22 +2,9 @@
 # Copyright (c) 2013, Jesse Keating <jesse.keating@rackspace.com>
 # Copyright (c) 2015, Hewlett-Packard Development Company, L.P.
 # Copyright (c) 2016, Rackspace Australia
-# Copyright (c) 2017, Red Hat, Inc.
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    name: openstack
--- a/lib/ansible/plugins/inventory/script.py
+++ b/lib/ansible/plugins/inventory/script.py
@ -1,19 +1,7 @@
-# (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com>
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    inventory: script
--- a/lib/ansible/plugins/inventory/virtualbox.py
+++ b/lib/ansible/plugins/inventory/virtualbox.py
@ -1,21 +1,6 @@
-# This file is part of Ansible,
-# (c) 2012-2017, Michael DeHaan <michael.dehaan@gmail.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#############################################
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    name: virtualbox
--- a/lib/ansible/plugins/inventory/yaml.py
+++ b/lib/ansible/plugins/inventory/yaml.py
@ -1,20 +1,6 @@
-# Copyright 2017 RedHat, inc
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#############################################
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 '''
 DOCUMENTATION:
    inventory: yaml
--- a/lib/ansible/plugins/loader.py
+++ b/lib/ansible/plugins/loader.py
@ -1,23 +1,9 @@
 # (c) 2012, Daniel Hokka Zakrisson <daniel@hozac.com>
 # (c) 2012-2014, Michael DeHaan <michael.dehaan@gmail.com> and others
 # (c) 2017, Toshio Kuratomi <tkuratomi@ansible.com>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# 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]
--- a/lib/ansible/plugins/shell/init.py
+++ b/lib/ansible/plugins/shell/init.py
@ -25,13 +25,17 @@ import random

 from ansible.module_utils.six import text_type
 from ansible.module_utils.six.moves import shlex_quote
+from ansible.plugins import AnsiblePlugin

 _USER_HOME_PATH_RE = re.compile(r'^~[_.A-Za-z0-9][-_.A-Za-z0-9]*$')


-class ShellBase(object):
+class ShellBase(AnsiblePlugin):

    def __init__(self):
+
+        super(ShellBase, self).__init__()
+
        self.env = dict()
        if C.DEFAULT_MODULE_SET_LOCALE:
            module_locale = C.DEFAULT_MODULE_LANG or os.getenv('LANG', 'en_US.UTF-8')
--- a/lib/ansible/plugins/strategy/linear.py
+++ b/lib/ansible/plugins/strategy/linear.py
@ -24,7 +24,7 @@ DOCUMENTATION:
          the next series of hosts until the batch is done, before going on to the next task.
    version_added: "2.0"
    notes:
-     - This was the default Ansible behaviour before 'strategy plugins' were introduces in 2.0.
+     - This was the default Ansible behaviour before 'strategy plugins' were introduced in 2.0.
    author: Ansible Core Team
 '''
 # Make coding more python3-ish
--- a/lib/ansible/plugins/vars/host_group_vars.py
+++ b/lib/ansible/plugins/vars/host_group_vars.py
@ -27,6 +27,18 @@ DOCUMENTATION:
        - Only applies to inventory sources that are existing paths.
    notes:
        - It takes the place of the previously hardcoded group_vars/host_vars loading.
+    options:
+      _valid_extensions:
+        default: [".yml", ".yaml", ".json"]
+        description:
+          - "Check all of these extensions when looking for 'variable' files which should be YAML or JSON or vaulted versions of these."
+          - 'This affects vars_files, include_vars, inventory and vars plugins among others.'
+        env:
+          - name: ANSIBLE_YAML_FILENAME_EXT
+        ini:
+          - section: yaml_valid_extensions
+            key: defaults
+        type: list
 '''

 from __future__ import (absolute_import, division, print_function)
--- a/lib/ansible/utils/display.py
+++ b/lib/ansible/utils/display.py
@ -193,14 +193,14 @@ class Display:

        if not removed:
            if version:
-                new_msg = "[DEPRECATION WARNING]: %s.\nThis feature will be removed in version %s." % (msg, version)
+                new_msg = "[DEPRECATION WARNING]: %s. This feature will be removed in version %s." % (msg, version)
            else:
-                new_msg = "[DEPRECATION WARNING]: %s.\nThis feature will be removed in a future release." % (msg)
+                new_msg = "[DEPRECATION WARNING]: %s. This feature will be removed in a future release." % (msg)
            new_msg = new_msg + " Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.\n\n"
        else:
            raise AnsibleError("[DEPRECATED]: %s.\nPlease update your playbooks." % msg)

-        wrapped = textwrap.wrap(new_msg, self.columns, replace_whitespace=False, drop_whitespace=False)
+        wrapped = textwrap.wrap(new_msg, self.columns, drop_whitespace=False)
        new_msg = "\n".join(wrapped) + "\n"

        if new_msg not in self._deprecations:
--- a/lib/ansible/utils/module_docs_fragments/constructed.py
+++ b/lib/ansible/utils/module_docs_fragments/constructed.py
@ -0,0 +1,43 @@
+#
+# (c) 2016, Sumit Kumar <sumit4@netapp.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = """
+options:
+  strict:
+    description:
+        - If true make invalid entries a fatal error, otherwise skip and continue
+        - Since it is possible to use facts in the expressions they might not always be available
+          and we ignore those errors by default.
+    type: boolean
+    default: False
+  compose:
+    description: create vars from jinja2 expressions
+    type: dictionary
+    default: {}
+  groups:
+    description: add hosts to group based on Jinja2 conditionals
+    type: dictionary
+    default: {}
+  keyed_groups:
+    description: add hosts to group based on the values of a variable
+    type: list
+    default: []
+"""
--- a/lib/ansible/vars/manager.py
+++ b/lib/ansible/vars/manager.py
@ -103,6 +103,9 @@ def remove_internal_keys(data):

 class VariableManager:

+    _ALLOWED = frozenset(['plugins_by_group', 'groups_plugins_play', 'groups_plugins_inventory', 'groups_inventory',
+                          'all_plugins_play', 'all_plugins_inventory', 'all_inventory'])
+
    def __init__(self, loader=None, inventory=None):

        self._nonpersistent_fact_cache = defaultdict(dict)
@ -283,7 +286,7 @@ class VariableManager:
                    data = combine_vars(data, _get_plugin_vars(plugin, basedir, entities))
                return data

-            # configurable functions that are sortable via config
+            # configurable functions that are sortable via config, rememer to add to _ALLOWED if expanding this list
            def all_inventory():
                return all_group.get_vars()

@ -317,12 +320,13 @@ class VariableManager:
                return data

            # Merge as per precedence config
-            for entry in C.VARIABLE_PRECEDENCE:
            # only allow to call the functions we want exposed
-                if entry.startswith('_') or '.' in entry:
-                    continue
+            for entry in C.VARIABLE_PRECEDENCE:
+                if entry in self._ALLOWED:
                    display.debug('Calling %s to load vars for %s' % (entry, host.name))
                    all_vars = combine_vars(all_vars, locals()[entry]())
+                else:
+                    display.warning('Ignoring unknown variable precedence entry: %s' % (entry))

            # host vars, from inventory, inventory adjacent and play adjacent via plugins
            all_vars = combine_vars(all_vars, host.get_vars())
@ -332,13 +336,8 @@ class VariableManager:
            # finally, the facts caches for this host, if it exists
            try:
                host_facts = wrap_var(self._fact_cache.get(host.name, {}))
-                if not C.ONLY_NAMESPACE_FACTS:
-                    # allow facts to polute main namespace
+                # push facts to 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