update Windows docs (ansible#30783)

* first round of splitting and expanding Windows docs

* Added info about WinRM and started the usage page

* more details onf usage around command/shell

* added more info

* missed a page

* added info about hotfix and ps upgrade script

* Added DSC information

* filled in FAQ and fixed up links

* changes per PR review and typo fixes found by myself

* fixed sanity check

* updated external script URLS

* Edits

* Edits

* Edits

* Copy edits.

* More copy edits.

* Added info about becoming a local service account

* some formatting changes on become and DSC indent fix

* Copy edits/rewrites

* Copy edits/rewrites

* minor updates to UAC text, typos

* minor wording updates

* minor wording tweaks/typos

* minor wording tweaks/typos

* minor tweaks/typos

* fix indent issue

* fix title underline length

* fix quote issue

docs/docsite/rst/become.rst

@@ -7,15 +7,12 @@ Ansible can use existing privilege escalation systems to allow a user to execute
 
 Become
 ``````
-Ansible allows you to 'become' another user, different from the user that logged into the machine (remote user). This is done using existing
-privilege escalation tools, which you probably already use or have configured, like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu` and others.
+Ansible allows you to 'become' another user, different from the user that logged into the machine (remote user). This is done using existing privilege escalation tools such as `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu`, `runas` and others.
 
 
-.. note:: Before 1.9 Ansible mostly allowed the use of `sudo` and a limited use of `su` to allow a login/remote user to become a different user
-    and execute tasks, create resources with the 2nd user's permissions. As of 1.9 `become` supersedes the old sudo/su, while still being backwards compatible.
-    This new system also makes it easier to add other privilege escalation tools like `pbrun` (Powerbroker), `pfexec`, `dzdo` (Centrify), and others.
+.. note:: Prior to version 1.9, Ansible mostly allowed the use of `sudo` and a limited use of `su` to allow a login/remote user to become a different user and execute tasks and create resources with the second user's permissions. As of Ansible version 1.9,  `become` supersedes the old sudo/su, while still being backwards compatible. This new implementation also makes it easier to add other privilege escalation tools, including `pbrun` (Powerbroker), `pfexec`, `dzdo` (Centrify), and others.
 
-.. note:: Become vars & directives are independent, i.e. setting `become_user` does not set `become`.
+.. note:: Become vars and directives are independent. For example, setting `become_user` does not set `become`.
 
 
 Directives
@@ -29,10 +26,10 @@ become_user
     set to user with desired privileges — the user you 'become', NOT the user you login as. Does NOT imply `become: yes`, to allow it to be set at host level.
 
 become_method
-    (at play or task level) overrides the default method set in ansible.cfg, set to `sudo`/`su`/`pbrun`/`pfexec`/`doas`/`dzdo`/`ksu`
+    (at play or task level) overrides the default method set in ansible.cfg, set to `sudo`/`su`/`pbrun`/`pfexec`/`doas`/`dzdo`/`ksu`/`runas`
 
 become_flags
-    (at play or task level) permit to use specific flags for the tasks or role. One common use is to change user to nobody when the shell is set to no login. Added in Ansible 2.2.
+    (at play or task level) permit the use of specific flags for the tasks or role. One common use is to change the user to nobody when the shell is set to no login. Added in Ansible 2.2.
 
 For example, to manage a system service (which requires ``root`` privileges) when connected as a non-``root`` user (this takes advantage of the fact that the default value of ``become_user`` is ``root``)::
 
@@ -89,7 +86,7 @@ Command line options
 
 --become-method=BECOME_METHOD
     privilege escalation method to use (default=sudo),
-    valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu ]
+    valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas ]
 
 --become-user=BECOME_USER
     run operations as this user (default=root), does not imply --become/-b
@@ -205,6 +202,108 @@ or '/bin/chmod' as the allowed commands this will fail with ansible as those
 paths won't match with the temporary file that ansible creates to run the
 module.
 
+Become and Windows
+``````````````````
+
+Since Ansible 2.3, ``become`` can be used on Windows hosts through the
+``runas`` method. Become on Windows uses the same inventory setup and
+invocation arguments as ``become`` on a non-Windows host, so the setup and
+variable names are the same as what is defined in this document.
+
+While ``become`` can be used to assume the identity of another user, there are other uses for
+it with Windows hosts. One important use is to bypass some of the
+limitations that are imposed when running on WinRM, such as constrained network
+delegation or accessing forbidden system calls like the WUA API. You can use
+``become`` with the same user as ``ansible_user`` to bypass these limitations
+and run commands that are not normally accessible in a WinRM session.
+
+.. note:: While become support was added for Windows starting with Ansible 
+    version 2.3, this functionality is still considered experimental and can 
+    change in the future based on issues and limitations that are found. Prior to 
+    Ansible 2.4, become would only work when ``ansible_winrm_transport`` was 
+    set to either ``basic`` or ``credssp``, but since Ansible 2.4 become now works on 
+    all transport types.
+
+Administrative Rights
+---------------------
+
+Many tasks in Windows require administrative privileges to complete. When using
+the ``runas`` become method, Ansible will automatically run the module with the
+full privileges of the remote user, unless User Account Control (UAC) Admin Approval
+Mode is enabled on the target hosts. When UAC is enabled, Ansible attempts to elevate
+module processes with administrative privileges, but uses a limited token if elevation
+fails.
+
+There are several ways to use the ``runas`` become method with full privileges
+when UAC is enabled:
+
+* Set the ``become_user`` to ``System`` which has full control over the
+  operating system.
+
+* Grant ``SeTcbPrivilege`` to the user Ansible connects with on
+  WinRM. ``SeTcbPrivilege`` is a high-level privilege that grants
+  full control over the operating system. No user is given this privilege by
+  default, and care should be taken if you grant this privilege to a user or group. 
+  For more information on this privilege, please see
+  `Act as part of the operating system <https://technet.microsoft.com/en-us/library/dn221957(v=ws.11).aspx>`_.
+  You can use the below task to set this privilege on a Windows host::
+
+    - name: grant the ansible user the SeTcbPrivilege right
+      win_user_right:
+        name: SeTcbPrivilege
+        users: '{{ansible_user}}'
+        action: add
+
+* Turn UAC off on the host and reboot before trying to become the user. UAC is
+  a security protocol that is designed to run accounts with the
+  ``least privilege`` principle. You can turn UAC off by running the following
+  tasks::
+
+    - name: turn UAC off
+      win_regedit:
+        path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system
+        name: EnableLUA
+        data: 0
+        type: dword
+        state: present
+      register: uac_result
+    
+    - name: reboot after disabling UAC
+      win_reboot:
+      when: uac_result|changed
+
+Local Service Accounts
+----------------------
+
+Prior to Ansible version 2.5, ``become`` only worked with a local or domain
+user account. Local service accounts like ``System`` or ``NetworkService``
+could not be used as ``become_user`` in these older versions. This restriction
+has been lifted since the 2.5 release of Ansible. The three service accounts
+that can be set under ``become_user`` are:
+
+* System
+* NetworkService
+* LocalService
+
+Because local service accounts do not have passwords, the
+``ansible_become_password`` parameter is not required and is ignored if
+specified.
+
+Limitations
+-----------
+
+Be aware of the following limitations with ``become`` on Windows:
+
+* Running a task with ``async`` and ``become`` does not work.
+
+* The become user logs on with an interactive session, so it must have the
+  ability to do so on the Windows host. If it does not inherit the
+  ``SeAllowLogOnLocally`` privilege or inherits the ``SeDenyLogOnLocally``
+  privilege, the become process will fail.
+
+* Prior to Ansible version 2.3, become only worked when ``ansible_winrm_transport`` was
+  either ``basic`` or ``credssp``. This restriction has been lifted since the
+  2.4 release of Ansible.
 
 .. seealso::
 

docs/docsite/rst/index.rst

@@ -47,3 +47,4 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
    porting_guides
    python_3_support
    release_and_maintenance
+   windows