standardize connection variable names (#51776)

* standardize user/password connection vars

* docs: use ansible_user and ansible_password

* docs: var precedence for connection vars

* docs: ansible_become_pass -> ansible_become_password etc

docs/docsite/rst/user_guide/become.rst

@@ -73,7 +73,7 @@ ansible_become_method
 ansible_become_user
     set the user you become through privilege escalation; does not imply ``ansible_become: yes``
 
-ansible_become_pass
+ansible_become_password
     set the privilege escalation password. See :doc:`playbooks_vault` for details on how to avoid having secrets in plain text
 
 For example, if you want to run all tasks as ``root`` on a server named ``webserver``, but you can only connect as the ``manager`` user, you could use an inventory entry like this::
@@ -298,7 +298,7 @@ Passwords for enable mode
 If you need a password to enter ``enable`` mode, you can specify it in one of two ways:
 
 * providing the :option:`--ask-become-pass <ansible-playbook --ask-become-pass>` command line option
-* setting the ``ansible_become_pass`` connection variable
+* setting the ``ansible_become_password`` connection variable
 
 .. warning::
 
@@ -553,8 +553,8 @@ option for a Scheduled Task. In this scenario, the become process will not be
 able to access any network resources like a normal WinRM process.
 
 To make a distinction between using become with no password and becoming an
-account that has no password make sure to keep ``ansible_become_pass`` as
-undefined or set ``ansible_become_pass:``.
+account that has no password make sure to keep ``ansible_become_password`` as
+undefined or set ``ansible_become_password:``.
 
 .. Note:: Because there are no guarantees an existing token will exist for a
   user when Ansible runs, there's a high change the become process will only
@@ -568,7 +568,7 @@ Accounts without a Password
 
 Ansible can be used to become an account that does not have a password (like the
 ``Guest`` account). To become an account without a password, set up the
-variables like normal but set ``ansible_become_pass: ''``.
+variables like normal but set ``ansible_become_password: ''``.
 
 Before become can work on an account like this, the local policy
 `Accounts: Limit local account use of blank passwords to console logon only <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/jj852174(v=ws.11)>`_
@@ -586,7 +586,7 @@ or with this Ansible task:
        state: present
 
 .. Note:: This is only for accounts that do not have a password. You still need
-    to set the account's password under ``ansible_become_pass`` if the
+    to set the account's password under ``ansible_become_password`` if the
     become_user has a password.
 
 Become Flags
@@ -661,7 +661,7 @@ Here are some examples of how to use ``become_flags`` with Windows tasks:
       ansible_become: yes
       ansible_become_method: runas
       ansible_become_user: DOMAIN\user
-      ansible_become_pass: Password01
+      ansible_become_password: Password01
       ansible_become_flags: logon_type=new_credentials logon_flags=netcredentials_only
 
   - name: run a command under a batch logon

docs/docsite/rst/user_guide/intro_inventory.rst

@@ -515,15 +515,15 @@ General for all connections:
 ansible_host
     The name of the host to connect to, if different from the alias you wish to give to it.
 ansible_port
-    The ssh port number, if not 22
+    The connection port number, if not the default (22 for ssh)
 ansible_user
-    The default ssh user name to use.
+    The user name to use when connecting to the host
+ansible_password
+    The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
 
 
 Specific to the SSH connection:
 
-ansible_ssh_pass
-    The ssh password to use (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
 ansible_ssh_private_key_file
     Private key file used by ssh.  Useful if using multiple keys and you don't want to use SSH agent.
 ansible_ssh_common_args
@@ -550,8 +550,8 @@ ansible_become_method
     Allows to set privilege escalation method
 ansible_become_user
     Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation
-ansible_become_pass
-    Equivalent to ``ansible_sudo_pass`` or ``ansible_su_pass``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
+ansible_become_password
+    Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
 ansible_become_exe
     Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected
 ansible_become_flags

docs/docsite/rst/user_guide/playbooks_variables.rst

@@ -1047,7 +1047,7 @@ Basically, anything that goes into "role defaults" (the defaults folder inside t
           This last one can be superceeded by the user via ``ansible_group_priority``, which defaults to ``1`` for all groups.
           This variable, ``ansible_group_priority``, can only be set in the inventory source and not in group_vars/ as the variable is used in the loading of group_vars/.
 
-Another important thing to consider (for all versions) is that connection variables override config, command line and play/role/task specific options and keywords.  For example, if your inventory specifies ``ansible_ssh_user: ramon`` and you run::
+Another important thing to consider (for all versions) is that connection variables override config, command line and play/role/task specific options and keywords.  For example, if your inventory specifies ``ansible_user: ramon`` and you run::
 
     ansible -u lola myhost
 
@@ -1060,7 +1060,7 @@ For plays/tasks this is also true for ``remote_user``. Assuming the same invento
     - command: I'll connect as ramon still
       remote_user: lola
 
-will have the value of ``remote_user`` overwritten by ``ansible_ssh_user`` in the inventory.
+will have the value of ``remote_user`` overwritten by ``ansible_user`` in the inventory.
 
 This is done so host-specific settings can override the general settings. These variables are normally defined per host or group in inventory,
 but they behave like other variables.
@@ -1069,7 +1069,11 @@ If you want to override the remote user globally (even over inventory) you can u
 
     ansible... -e "ansible_user=maria" -u lola
 
-the ``lola`` value is still ignored, but ``ansible_user=maria`` takes precedence over all other places where ``ansible_user`` (or ``ansible_ssh_user``, or ``remote_user``) might be set.
+the ``lola`` value is still ignored, but ``ansible_user=maria`` takes precedence over all other places where ``ansible_user`` (or ``remote_user``) might be set.
+
+A connection-specific version of a variable takes precedence over more generic
+versions.  For example, ``ansible_ssh_user`` specified as a group_var would have
+a higher precedence than ``ansible_user`` specified as a host_var.
 
 You can also override as a normal variable in a play::