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/modules/files/copy.py

@@ -97,32 +97,32 @@ notes:
 '''
 
 EXAMPLES = r'''
-# Example from Ansible Playbooks
-- copy:
+- name: example copying file with owner and permissions
+  copy:
     src: /srv/myfiles/foo.conf
     dest: /etc/foo.conf
     owner: foo
     group: foo
     mode: 0644
 
-# The same example as above, but using a symbolic mode equivalent to 0644
-- copy:
+- name: The same example as above, but using a symbolic mode equivalent to 0644
+  copy:
     src: /srv/myfiles/foo.conf
     dest: /etc/foo.conf
     owner: foo
     group: foo
     mode: u=rw,g=r,o=r
 
-# Another symbolic mode example, adding some permissions and removing others
-- copy:
+- name: Another symbolic mode example, adding some permissions and removing others
+  copy:
     src: /srv/myfiles/foo.conf
     dest: /etc/foo.conf
     owner: foo
     group: foo
     mode: u+rw,g-wx,o-rwx
 
-# Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
-- copy:
+- name: Copy a new "ntp.conf file into place, backing up the original if it differs from the copied version
+  copy:
     src: /mine/ntp.conf
     dest: /etc/ntp.conf
     owner: root
@@ -130,33 +130,23 @@ EXAMPLES = r'''
     mode: 0644
     backup: yes
 
-# Copy a new "sudoers" file into place, after passing validation with visudo
-- copy:
+- name: Copy a new "sudoers" file into place, after passing validation with visudo
+  copy:
     src: /mine/sudoers
     dest: /etc/sudoers
     validate: /usr/sbin/visudo -cf %s
 
-# Copy a "sudoers" file on the remote machine for editing
-- copy:
+- name: Copy a "sudoers" file on the remote machine for editing
+  copy:
     src: /etc/sudoers
     dest: /etc/sudoers.edit
     remote_src: yes
     validate: /usr/sbin/visudo -cf %s
 
-# Create a CSV file from your complete inventory using an inline template
-- hosts: all
-  tasks:
-  - copy:
-      content: |
-        HOSTNAME;IPADDRESS;FQDN;OSNAME;OSVERSION;PROCESSOR;ARCHITECTURE;MEMORY;
-        {% for host in hostvars %}
-        {%   set vars = hostvars[host|string] %}
-        {{ vars.ansible_hostname }};{{ vars.remote_host }};{{ vars.ansible_fqdn }};{{ vars.ansible_distribution }};{{ vars.ansible_distribution_version }};{{ vars.ansible_processor[1] }};{{ vars.ansible_architecture }};{{ (vars.ansible_memtotal_mb/1024)|round|int }};  # NOQA
-        {% endfor %}
-      dest: /some/path/systems.csv
-      backup: yes
-    run_once: yes
-    delegate_to: localhost
+- name: Copy using the 'content' for inline data
+  copy:
+    content: '# This file was moved to /etc/other.conf'
+    dest: /etc/mine.conf'
 '''
 
 RETURN = r'''

lib/ansible/modules/utilities/logic/async_status.py

@@ -28,8 +28,7 @@ options:
     required: true
   mode:
     description:
-      - if C(status), obtain the status; if C(cleanup), clean up the async job cache
-        located in C(~/.ansible_async/) for the specified job I(jid).
+      - if C(status), obtain the status; if C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
     choices: [ "status", "cleanup" ]
     default: "status"
 notes:
@@ -57,8 +56,10 @@ def main():
     mode = module.params['mode']
     jid = module.params['jid']
 
+    async_dir = os.environ.get('ANSIBLE_ASYNC_DIR', '~/.ansible_async')
+
     # setup logging directory
-    logdir = os.path.expanduser("~/.ansible_async")
+    logdir = os.path.expanduser(async_dir)
     log_path = os.path.join(logdir, jid)
 
     if not os.path.exists(log_path):

lib/ansible/modules/utilities/logic/async_wrapper.py

@@ -216,8 +216,10 @@ if __name__ == '__main__':
         cmd = wrapped_module
     step = 5
 
+    async_dir = os.environ.get('ANSIBLE_ASYNC_DIR', '~/.ansible_async')
+
     # setup job output directory
-    jobdir = os.path.expanduser("~/.ansible_async")
+    jobdir = os.path.expanduser(async_dir)
     job_path = os.path.join(jobdir, jid)
 
     if not os.path.exists(jobdir):