Temporary (#31677)

* allow shells to have per host options, remote_tmp

added language to shell
removed module lang setting from general as  plugins have it now
use get to avoid bad powershell plugin
more resilient tmp discovery, fall back to `pwd`
add shell to docs
fixed options for when frags are only options
added shell set ops in t_e and fixed option frags
normalize tmp dir usag4e

- pass tmpdir/tmp/temp options as env var to commands, making it default for tempfile
- adjusted ansiballz tmpdir
- default local tempfile usage to the configured local tmp
- set env temp in action

add options to powershell
shift temporary to internal envvar/params
ensure tempdir is set if we pass var
ensure basic and url use expected tempdir
ensure localhost uses local tmp
give /var/tmp priority, less perms issues
more consistent tempfile mgmt for ansiballz
made async_dir configurable
better action handling, allow for finally rm tmp
fixed tmp issue and no more tempdir in ballz
hostvarize world readable and admin users
always set shell tempdir
added comment to discourage use of exception/flow control

* Mostly revert expand_user as it's not quite working.

This was an additional feature anyhow.

Kept the use of pwd as a fallback but moved it to a second ssh
connection.  This is not optimal but getting that to work in a single
ssh connection was part of the problem holding this up.

(cherry picked from commit 395b714120522f15e4c90a346f5e8e8d79213aca)

* fixed script and other action plugins

ensure tmpdir deletion
allow for connections that don't support new options (legacy, 3rd party)
fixed tests

lib/ansible/utils/module_docs_fragments/constructed.py

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

lib/ansible/utils/module_docs_fragments/shell_common.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2017 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+class ModuleDocFragment(object):
+
+    # common shelldocumentation fragment
+    DOCUMENTATION = """
+options:
+  remote_temp:
+    description:
+      - Temporary directory to use on targets when executing tasks.
+    default: '~/.ansible/tmp'
+    env: [{name: ANSIBLE_REMOTE_TEMP}]
+    ini:
+      - section: defaults
+        key: remote_tmp
+    vars:
+      - name: ansible_remote_tmp
+  system_temps:
+    description:
+       - List of valid system temporary directories for Ansible to choose when it cannot use ``remote_temp``, normally due to permission issues.
+    default: [ /var/tmp, /tmp ]
+    type: list
+    env: [{name: ANSIBLE_SYSTEM_TMPS}]
+    ini:
+      - section: defaults
+        key: system_tmps
+    vars:
+      - name: ansible_system_tmps
+  async_dir:
+    description:
+       - Directory in which ansible will keep async job inforamtion
+    default: '~/.ansible_async'
+    env: [{name: ANSIBLE_ASYNC_DIR}]
+    ini:
+      - section: defaults
+        key: async_dir
+    vars:
+      - name: ansible_async_dir
+  set_module_language:
+    default: False
+    description: Controls if we set locale for modules when executing on the target.
+    env:
+      - name: ANSIBLE_MODULE_SET_LOCALE
+    ini:
+      - section: defaults
+        key: module_set_locale
+    type: boolean
+    vars:
+      - name: ansible_module_set_locale
+  module_language:
+    description:
+      - "If 'set_module_language' is true, this is the language language/locale setting to use for modules when they execute on the target."
+      - "Defaults to match the controller's settings."
+    default: "{{CONTROLLER_LANG}}"
+    env:
+      - name: ANSIBLE_MODULE_LANG
+    ini:
+      - section: defaults
+        key: module_lang
+    vars:
+      - name: ansible_module_lang
+  environment:
+    type: dict
+    default: {}
+    description:
+      - dictionary of environment variables and their values to use when executing commands.
+  admin_users:
+    type: list
+    default: ['root', 'toor', 'admin']
+    description:
+      - list of users to be expected to have admin privileges, for BSD you might want to add 'toor' for windows 'Administrator'.
+    env:
+      - name: ANSIBLE_ADMIN_USERS
+    ini:
+      - section: defaults
+        key: admin_users
+    vars:
+      - name: ansible_admin_users
+  allow_world_readable_temp:
+    type: boolean
+    description:
+        - This makes the temporary files created on the machine to be world readable and will issue a warning instead of failing the task.
+        - It is useful when becoming an unprivileged user.
+    ini:
+      - section: defaults
+        key: allow_world_readable_tmpfiles
+    vars:
+      - name: ansible_world_readable_tmpfiles
+    version_added: "2.1"
+"""

lib/ansible/utils/plugin_docs.py

@@ -27,7 +27,6 @@ from ansible.module_utils.six import string_types
 from ansible.module_utils._text import to_native
 from ansible.parsing.plugin_docs import read_docstring
 from ansible.parsing.yaml.loader import AnsibleLoader
-from ansible.plugins.loader import fragment_loader
 
 try:
     from __main__ import display
@@ -59,7 +58,7 @@ def merge_fragment(target, source):
         target[key] = value
 
 
-def add_fragments(doc, filename):
+def add_fragments(doc, filename, fragment_loader):
 
     fragments = doc.pop('extends_documentation_fragment', [])
 
@@ -99,6 +98,8 @@ def add_fragments(doc, filename):
                 merge_fragment(doc['options'], fragment.pop('options'))
             except Exception as e:
                 raise AnsibleError("%s options (%s) of unknown type: %s" % (to_native(e), fragment_name, filename))
+        else:
+            doc['options'] = fragment.pop('options')
 
         # merge rest of the sections
         try:
@@ -107,15 +108,15 @@ def add_fragments(doc, filename):
             raise AnsibleError("%s (%s) of unknown type: %s" % (to_native(e), fragment_name, filename))
 
 
-def get_docstring(filename, verbose=False):
+def get_docstring(filename, fragment_loader, verbose=False, ignore_errors=False):
     """
     DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the module_docs_fragments directory.
     """
 
-    data = read_docstring(filename, verbose=verbose)
+    data = read_docstring(filename, verbose=verbose, ignore_errors=ignore_errors)
 
     # add fragments to documentation
     if data.get('doc', False):
-        add_fragments(data['doc'], filename)
+        add_fragments(data['doc'], filename, fragment_loader=fragment_loader)
 
     return data['doc'], data['plainexamples'], data['returndocs'], data['metadata']