1.. _become: 2 3****************************************** 4Understanding privilege escalation: become 5****************************************** 6 7Ansible uses existing privilege escalation systems to execute tasks with root privileges or with another user's permissions. Because this feature allows you to 'become' another user, different from the user that logged into the machine (remote user), we call it ``become``. The ``become`` keyword leverages existing privilege escalation tools like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu`, `runas`, `machinectl` and others. 8 9.. contents:: 10 :local: 11 12Using become 13============ 14 15You can control the use of ``become`` with play or task directives, connection variables, or at the command line. If you set privilege escalation properties in multiple ways, review the :ref:`general precedence rules<general_precedence_rules>` to understand which settings will be used. 16 17A full list of all become plugins that are included in Ansible can be found in the :ref:`become_plugin_list`. 18 19Become directives 20----------------- 21 22You can set the directives that control ``become`` at the play or task level. You can override these by setting connection variables, which often differ from one host to another. These variables and directives are independent. For example, setting ``become_user`` does not set ``become``. 23 24become 25 set to ``yes`` to activate privilege escalation. 26 27become_user 28 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. Default value is ``root``. 29 30become_method 31 (at play or task level) overrides the default method set in ansible.cfg, set to use any of the :ref:`become_plugins`. 32 33become_flags 34 (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. 35 36For example, to manage a system service (which requires ``root`` privileges) when connected as a non-``root`` user, you can use the default value of ``become_user`` (``root``): 37 38.. code-block:: yaml 39 40 - name: Ensure the httpd service is running 41 service: 42 name: httpd 43 state: started 44 become: yes 45 46To run a command as the ``apache`` user: 47 48.. code-block:: yaml 49 50 - name: Run a command as the apache user 51 command: somecommand 52 become: yes 53 become_user: apache 54 55To do something as the ``nobody`` user when the shell is nologin: 56 57.. code-block:: yaml 58 59 - name: Run a command as nobody 60 command: somecommand 61 become: yes 62 become_method: su 63 become_user: nobody 64 become_flags: '-s /bin/sh' 65 66Become connection variables 67--------------------------- 68 69You can define different ``become`` options for each managed node or group. You can define these variables in inventory or use them as normal variables. 70 71ansible_become 72 equivalent of the become directive, decides if privilege escalation is used or not. 73 74ansible_become_method 75 which privilege escalation method should be used 76 77ansible_become_user 78 set the user you become through privilege escalation; does not imply ``ansible_become: yes`` 79 80ansible_become_password 81 set the privilege escalation password. See :ref:`playbooks_vault` for details on how to avoid having secrets in plain text 82 83For 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: 84 85.. code-block:: text 86 87 webserver ansible_user=manager ansible_become=yes 88 89.. note:: 90 The variables defined above are generic for all become plugins but plugin specific ones can also be set instead. 91 Please see the documentation for each plugin for a list of all options the plugin has and how they can be defined. 92 A full list of become plugins in Ansible can be found at :ref:`become_plugins`. 93 94Become command-line options 95--------------------------- 96 97--ask-become-pass, -K 98 ask for privilege escalation password; does not imply become will be used. Note that this password will be used for all hosts. 99 100--become, -b 101 run operations with become (no password implied) 102 103--become-method=BECOME_METHOD 104 privilege escalation method to use (default=sudo), 105 valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | machinectl ] 106 107--become-user=BECOME_USER 108 run operations as this user (default=root), does not imply --become/-b 109 110Risks and limitations of become 111=============================== 112 113Although privilege escalation is mostly intuitive, there are a few limitations 114on how it works. Users should be aware of these to avoid surprises. 115 116Risks of becoming an unprivileged user 117-------------------------------------- 118 119Ansible modules are executed on the remote machine by first substituting the 120parameters into the module file, then copying the file to the remote machine, 121and finally executing it there. 122 123Everything is fine if the module file is executed without using ``become``, 124when the ``become_user`` is root, or when the connection to the remote machine 125is made as root. In these cases Ansible creates the module file with permissions 126that only allow reading by the user and root, or only allow reading by the unprivileged 127user being switched to. 128 129However, when both the connection user and the ``become_user`` are unprivileged, 130the module file is written as the user that Ansible connects as, but the file needs to 131be readable by the user Ansible is set to ``become``. In this case, Ansible makes 132the module file world-readable for the duration of the Ansible module execution. 133Once the module is done executing, Ansible deletes the temporary file. 134 135If any of the parameters passed to the module are sensitive in nature, and you do 136not trust the client machines, then this is a potential danger. 137 138Ways to resolve this include: 139 140* Use `pipelining`. When pipelining is enabled, Ansible does not save the 141 module to a temporary file on the client. Instead it pipes the module to 142 the remote python interpreter's stdin. Pipelining does not work for 143 python modules involving file transfer (for example: :ref:`copy <copy_module>`, 144 :ref:`fetch <fetch_module>`, :ref:`template <template_module>`), or for non-python modules. 145 146* Install POSIX.1e filesystem acl support on the 147 managed host. If the temporary directory on the remote host is mounted with 148 POSIX acls enabled and the :command:`setfacl` tool is in the remote ``PATH`` 149 then Ansible will use POSIX acls to share the module file with the second 150 unprivileged user instead of having to make the file readable by everyone. 151 152* Avoid becoming an unprivileged 153 user. Temporary files are protected by UNIX file permissions when you 154 ``become`` root or do not use ``become``. In Ansible 2.1 and above, UNIX 155 file permissions are also secure if you make the connection to the managed 156 machine as root and then use ``become`` to access an unprivileged account. 157 158.. warning:: Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs 159 are not POSIX.1e filesystem acls (they are NFSv4 ACLs instead). Ansible 160 cannot use these ACLs to manage its temp file permissions so you may have 161 to resort to ``allow_world_readable_tmpfiles`` if the remote machines use ZFS. 162 163.. versionchanged:: 2.1 164 165Ansible makes it hard to unknowingly use ``become`` insecurely. Starting in Ansible 2.1, 166Ansible defaults to issuing an error if it cannot execute securely with ``become``. 167If you cannot use pipelining or POSIX ACLs, you must connect as an unprivileged user, 168you must use ``become`` to execute as a different unprivileged user, 169and you decide that your managed nodes are secure enough for the 170modules you want to run there to be world readable, you can turn on 171``allow_world_readable_tmpfiles`` in the :file:`ansible.cfg` file. Setting 172``allow_world_readable_tmpfiles`` will change this from an error into 173a warning and allow the task to run as it did prior to 2.1. 174 175Not supported by all connection plugins 176--------------------------------------- 177 178Privilege escalation methods must also be supported by the connection plugin 179used. Most connection plugins will warn if they do not support become. Some 180will just ignore it as they always run as root (jail, chroot, etc). 181 182Only one method may be enabled per host 183--------------------------------------- 184 185Methods cannot be chained. You cannot use ``sudo /bin/su -`` to become a user, 186you need to have privileges to run the command as that user in sudo or be able 187to su directly to it (the same for pbrun, pfexec or other supported methods). 188 189Privilege escalation must be general 190------------------------------------ 191 192You cannot limit privilege escalation permissions to certain commands. 193Ansible does not always 194use a specific command to do something but runs modules (code) from 195a temporary file name which changes every time. If you have '/sbin/service' 196or '/bin/chmod' as the allowed commands this will fail with ansible as those 197paths won't match with the temporary file that Ansible creates to run the 198module. If you have security rules that constrain your sudo/pbrun/doas environment 199to running specific command paths only, use Ansible from a special account that 200does not have this constraint, or use :ref:`ansible_tower` to manage indirect access to SSH credentials. 201 202May not access environment variables populated by pamd_systemd 203-------------------------------------------------------------- 204 205For most Linux distributions using ``systemd`` as their init, the default 206methods used by ``become`` do not open a new "session", in the sense of 207systemd. Because the ``pam_systemd`` module will not fully initialize a new 208session, you might have surprises compared to a normal session opened through 209ssh: some environment variables set by ``pam_systemd``, most notably 210``XDG_RUNTIME_DIR``, are not populated for the new user and instead inherited 211or just emptied. 212 213This might cause trouble when trying to invoke systemd commands that depend on 214``XDG_RUNTIME_DIR`` to access the bus: 215 216.. code-block:: console 217 218 $ echo $XDG_RUNTIME_DIR 219 220 $ systemctl --user status 221 Failed to connect to bus: Permission denied 222 223To force ``become`` to open a new systemd session that goes through 224``pam_systemd``, you can use ``become_method: machinectl``. 225 226For more information, see `this systemd issue 227<https://github.com/systemd/systemd/issues/825#issuecomment-127917622>`_. 228 229.. _become_network: 230 231Become and network automation 232============================= 233 234As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable`` mode or privileged EXEC mode) on all :ref:`Ansible-maintained platforms<network_supported>` that support ``enable`` mode. Using ``become`` replaces the ``authorize`` and ``auth_pass`` options in a ``provider`` dictionary. 235 236You must set the connection type to either ``connection: network_cli`` or ``connection: httpapi`` to use ``become`` for privilege escalation on network devices. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details. 237 238You can use escalated privileges on only the specific tasks that need them, on an entire play, or on all plays. Adding ``become: yes`` and ``become_method: enable`` instructs Ansible to enter ``enable`` mode before executing the task, play, or playbook where those parameters are set. 239 240If you see this error message, the task that generated it requires ``enable`` mode to succeed: 241 242.. code-block:: console 243 244 Invalid input (privileged mode required) 245 246To set ``enable`` mode for a specific task, add ``become`` at the task level: 247 248.. code-block:: yaml 249 250 - name: Gather facts (eos) 251 eos_facts: 252 gather_subset: 253 - "!hardware" 254 become: yes 255 become_method: enable 256 257To set enable mode for all tasks in a single play, add ``become`` at the play level: 258 259.. code-block:: yaml 260 261 - hosts: eos-switches 262 become: yes 263 become_method: enable 264 tasks: 265 - name: Gather facts (eos) 266 eos_facts: 267 gather_subset: 268 - "!hardware" 269 270Setting enable mode for all tasks 271--------------------------------- 272 273Often you wish for all tasks in all plays to run using privilege mode, that is best achieved by using ``group_vars``: 274 275**group_vars/eos.yml** 276 277.. code-block:: yaml 278 279 ansible_connection: network_cli 280 ansible_network_os: eos 281 ansible_user: myuser 282 ansible_become: yes 283 ansible_become_method: enable 284 285Passwords for enable mode 286^^^^^^^^^^^^^^^^^^^^^^^^^ 287 288If you need a password to enter ``enable`` mode, you can specify it in one of two ways: 289 290* providing the :option:`--ask-become-pass <ansible-playbook --ask-become-pass>` command line option 291* setting the ``ansible_become_password`` connection variable 292 293.. warning:: 294 295 As a reminder passwords should never be stored in plain text. For information on encrypting your passwords and other secrets with Ansible Vault, see :ref:`vault`. 296 297authorize and auth_pass 298----------------------- 299 300Ansible still supports ``enable`` mode with ``connection: local`` for legacy network playbooks. To enter ``enable`` mode with ``connection: local``, use the module options ``authorize`` and ``auth_pass``: 301 302.. code-block:: yaml 303 304 - hosts: eos-switches 305 ansible_connection: local 306 tasks: 307 - name: Gather facts (eos) 308 eos_facts: 309 gather_subset: 310 - "!hardware" 311 provider: 312 authorize: yes 313 auth_pass: " {{ secret_auth_pass }}" 314 315We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode consistently. The use of ``authorize`` and of ``provider`` dictionaries will be deprecated in future. Check the :ref:`platform_options` and :ref:`network_modules` documentation for details. 316 317.. _become_windows: 318 319Become and Windows 320================== 321 322Since Ansible 2.3, ``become`` can be used on Windows hosts through the 323``runas`` method. Become on Windows uses the same inventory setup and 324invocation arguments as ``become`` on a non-Windows host, so the setup and 325variable names are the same as what is defined in this document. 326 327While ``become`` can be used to assume the identity of another user, there are other uses for 328it with Windows hosts. One important use is to bypass some of the 329limitations that are imposed when running on WinRM, such as constrained network 330delegation or accessing forbidden system calls like the WUA API. You can use 331``become`` with the same user as ``ansible_user`` to bypass these limitations 332and run commands that are not normally accessible in a WinRM session. 333 334Administrative rights 335--------------------- 336 337Many tasks in Windows require administrative privileges to complete. When using 338the ``runas`` become method, Ansible will attempt to run the module with the 339full privileges that are available to the remote user. If it fails to elevate 340the user token, it will continue to use the limited token during execution. 341 342A user must have the ``SeDebugPrivilege`` to run a become process with elevated 343privileges. This privilege is assigned to Administrators by default. If the 344debug privilege is not available, the become process will run with a limited 345set of privileges and groups. 346 347To determine the type of token that Ansible was able to get, run the following 348task: 349 350.. code-block:: yaml 351 352 - win_whoami: 353 become: yes 354 355The output will look something similar to the below: 356 357.. code-block:: ansible-output 358 359 ok: [windows] => { 360 "account": { 361 "account_name": "vagrant-domain", 362 "domain_name": "DOMAIN", 363 "sid": "S-1-5-21-3088887838-4058132883-1884671576-1105", 364 "type": "User" 365 }, 366 "authentication_package": "Kerberos", 367 "changed": false, 368 "dns_domain_name": "DOMAIN.LOCAL", 369 "groups": [ 370 { 371 "account_name": "Administrators", 372 "attributes": [ 373 "Mandatory", 374 "Enabled by default", 375 "Enabled", 376 "Owner" 377 ], 378 "domain_name": "BUILTIN", 379 "sid": "S-1-5-32-544", 380 "type": "Alias" 381 }, 382 { 383 "account_name": "INTERACTIVE", 384 "attributes": [ 385 "Mandatory", 386 "Enabled by default", 387 "Enabled" 388 ], 389 "domain_name": "NT AUTHORITY", 390 "sid": "S-1-5-4", 391 "type": "WellKnownGroup" 392 }, 393 ], 394 "impersonation_level": "SecurityAnonymous", 395 "label": { 396 "account_name": "High Mandatory Level", 397 "domain_name": "Mandatory Label", 398 "sid": "S-1-16-12288", 399 "type": "Label" 400 }, 401 "login_domain": "DOMAIN", 402 "login_time": "2018-11-18T20:35:01.9696884+00:00", 403 "logon_id": 114196830, 404 "logon_server": "DC01", 405 "logon_type": "Interactive", 406 "privileges": { 407 "SeBackupPrivilege": "disabled", 408 "SeChangeNotifyPrivilege": "enabled-by-default", 409 "SeCreateGlobalPrivilege": "enabled-by-default", 410 "SeCreatePagefilePrivilege": "disabled", 411 "SeCreateSymbolicLinkPrivilege": "disabled", 412 "SeDebugPrivilege": "enabled", 413 "SeDelegateSessionUserImpersonatePrivilege": "disabled", 414 "SeImpersonatePrivilege": "enabled-by-default", 415 "SeIncreaseBasePriorityPrivilege": "disabled", 416 "SeIncreaseQuotaPrivilege": "disabled", 417 "SeIncreaseWorkingSetPrivilege": "disabled", 418 "SeLoadDriverPrivilege": "disabled", 419 "SeManageVolumePrivilege": "disabled", 420 "SeProfileSingleProcessPrivilege": "disabled", 421 "SeRemoteShutdownPrivilege": "disabled", 422 "SeRestorePrivilege": "disabled", 423 "SeSecurityPrivilege": "disabled", 424 "SeShutdownPrivilege": "disabled", 425 "SeSystemEnvironmentPrivilege": "disabled", 426 "SeSystemProfilePrivilege": "disabled", 427 "SeSystemtimePrivilege": "disabled", 428 "SeTakeOwnershipPrivilege": "disabled", 429 "SeTimeZonePrivilege": "disabled", 430 "SeUndockPrivilege": "disabled" 431 }, 432 "rights": [ 433 "SeNetworkLogonRight", 434 "SeBatchLogonRight", 435 "SeInteractiveLogonRight", 436 "SeRemoteInteractiveLogonRight" 437 ], 438 "token_type": "TokenPrimary", 439 "upn": "vagrant-domain@DOMAIN.LOCAL", 440 "user_flags": [] 441 } 442 443Under the ``label`` key, the ``account_name`` entry determines whether the user 444has Administrative rights. Here are the labels that can be returned and what 445they represent: 446 447* ``Medium``: Ansible failed to get an elevated token and ran under a limited 448 token. Only a subset of the privileges assigned to user are available during 449 the module execution and the user does not have administrative rights. 450 451* ``High``: An elevated token was used and all the privileges assigned to the 452 user are available during the module execution. 453 454* ``System``: The ``NT AUTHORITY\System`` account is used and has the highest 455 level of privileges available. 456 457The output will also show the list of privileges that have been granted to the 458user. When the privilege value is ``disabled``, the privilege is assigned to 459the logon token but has not been enabled. In most scenarios these privileges 460are automatically enabled when required. 461 462If running on a version of Ansible that is older than 2.5 or the normal 463``runas`` escalation process fails, an elevated token can be retrieved by: 464 465* Set the ``become_user`` to ``System`` which has full control over the 466 operating system. 467 468* Grant ``SeTcbPrivilege`` to the user Ansible connects with on 469 WinRM. ``SeTcbPrivilege`` is a high-level privilege that grants 470 full control over the operating system. No user is given this privilege by 471 default, and care should be taken if you grant this privilege to a user or group. 472 For more information on this privilege, please see 473 `Act as part of the operating system <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn221957(v=ws.11)>`_. 474 You can use the below task to set this privilege on a Windows host: 475 476 .. code-block:: yaml 477 478 - name: grant the ansible user the SeTcbPrivilege right 479 win_user_right: 480 name: SeTcbPrivilege 481 users: '{{ansible_user}}' 482 action: add 483 484* Turn UAC off on the host and reboot before trying to become the user. UAC is 485 a security protocol that is designed to run accounts with the 486 ``least privilege`` principle. You can turn UAC off by running the following 487 tasks: 488 489 .. code-block:: yaml 490 491 - name: turn UAC off 492 win_regedit: 493 path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system 494 name: EnableLUA 495 data: 0 496 type: dword 497 state: present 498 register: uac_result 499 500 - name: reboot after disabling UAC 501 win_reboot: 502 when: uac_result is changed 503 504.. Note:: Granting the ``SeTcbPrivilege`` or turning UAC off can cause Windows 505 security vulnerabilities and care should be given if these steps are taken. 506 507Local service accounts 508---------------------- 509 510Prior to Ansible version 2.5, ``become`` only worked on Windows with a local or domain 511user account. Local service accounts like ``System`` or ``NetworkService`` 512could not be used as ``become_user`` in these older versions. This restriction 513has been lifted since the 2.5 release of Ansible. The three service accounts 514that can be set under ``become_user`` are: 515 516* System 517* NetworkService 518* LocalService 519 520Because local service accounts do not have passwords, the 521``ansible_become_password`` parameter is not required and is ignored if 522specified. 523 524Become without setting a password 525--------------------------------- 526 527As of Ansible 2.8, ``become`` can be used to become a Windows local or domain account 528without requiring a password for that account. For this method to work, the 529following requirements must be met: 530 531* The connection user has the ``SeDebugPrivilege`` privilege assigned 532* The connection user is part of the ``BUILTIN\Administrators`` group 533* The ``become_user`` has either the ``SeBatchLogonRight`` or ``SeNetworkLogonRight`` user right 534 535Using become without a password is achieved in one of two different methods: 536 537* Duplicating an existing logon session's token if the account is already logged on 538* Using S4U to generate a logon token that is valid on the remote host only 539 540In the first scenario, the become process is spawned from another logon of that 541user account. This could be an existing RDP logon, console logon, but this is 542not guaranteed to occur all the time. This is similar to the 543``Run only when user is logged on`` option for a Scheduled Task. 544 545In the case where another logon of the become account does not exist, S4U is 546used to create a new logon and run the module through that. This is similar to 547the ``Run whether user is logged on or not`` with the ``Do not store password`` 548option for a Scheduled Task. In this scenario, the become process will not be 549able to access any network resources like a normal WinRM process. 550 551To make a distinction between using become with no password and becoming an 552account that has no password make sure to keep ``ansible_become_password`` as 553undefined or set ``ansible_become_password:``. 554 555.. Note:: Because there are no guarantees an existing token will exist for a 556 user when Ansible runs, there's a high change the become process will only 557 have access to local resources. Use become with a password if the task needs 558 to access network resources 559 560Accounts without a password 561--------------------------- 562 563.. Warning:: As a general security best practice, you should avoid allowing accounts without passwords. 564 565Ansible can be used to become a Windows account that does not have a password (like the 566``Guest`` account). To become an account without a password, set up the 567variables like normal but set ``ansible_become_password: ''``. 568 569Before become can work on an account like this, the local policy 570`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)>`_ 571must be disabled. This can either be done through a Group Policy Object (GPO) 572or with this Ansible task: 573 574.. code-block:: yaml 575 576 - name: allow blank password on become 577 win_regedit: 578 path: HKLM:\SYSTEM\CurrentControlSet\Control\Lsa 579 name: LimitBlankPasswordUse 580 data: 0 581 type: dword 582 state: present 583 584.. Note:: This is only for accounts that do not have a password. You still need 585 to set the account's password under ``ansible_become_password`` if the 586 become_user has a password. 587 588Become flags for Windows 589------------------------ 590 591Ansible 2.5 added the ``become_flags`` parameter to the ``runas`` become method. 592This parameter can be set using the ``become_flags`` task directive or set in 593Ansible's configuration using ``ansible_become_flags``. The two valid values 594that are initially supported for this parameter are ``logon_type`` and 595``logon_flags``. 596 597.. Note:: These flags should only be set when becoming a normal user account, not a local service account like LocalSystem. 598 599The key ``logon_type`` sets the type of logon operation to perform. The value 600can be set to one of the following: 601 602* ``interactive``: The default logon type. The process will be run under a 603 context that is the same as when running a process locally. This bypasses all 604 WinRM restrictions and is the recommended method to use. 605 606* ``batch``: Runs the process under a batch context that is similar to a 607 scheduled task with a password set. This should bypass most WinRM 608 restrictions and is useful if the ``become_user`` is not allowed to log on 609 interactively. 610 611* ``new_credentials``: Runs under the same credentials as the calling user, but 612 outbound connections are run under the context of the ``become_user`` and 613 ``become_password``, similar to ``runas.exe /netonly``. The ``logon_flags`` 614 flag should also be set to ``netcredentials_only``. Use this flag if 615 the process needs to access a network resource (like an SMB share) using a 616 different set of credentials. 617 618* ``network``: Runs the process under a network context without any cached 619 credentials. This results in the same type of logon session as running a 620 normal WinRM process without credential delegation, and operates under the same 621 restrictions. 622 623* ``network_cleartext``: Like the ``network`` logon type, but instead caches 624 the credentials so it can access network resources. This is the same type of 625 logon session as running a normal WinRM process with credential delegation. 626 627For more information, see 628`dwLogonType <https://docs.microsoft.com/en-gb/windows/desktop/api/winbase/nf-winbase-logonusera>`_. 629 630The ``logon_flags`` key specifies how Windows will log the user on when creating 631the new process. The value can be set to none or multiple of the following: 632 633* ``with_profile``: The default logon flag set. The process will load the 634 user's profile in the ``HKEY_USERS`` registry key to ``HKEY_CURRENT_USER``. 635 636* ``netcredentials_only``: The process will use the same token as the caller 637 but will use the ``become_user`` and ``become_password`` when accessing a remote 638 resource. This is useful in inter-domain scenarios where there is no trust 639 relationship, and should be used with the ``new_credentials`` ``logon_type``. 640 641By default ``logon_flags=with_profile`` is set, if the profile should not be 642loaded set ``logon_flags=`` or if the profile should be loaded with 643``netcredentials_only``, set ``logon_flags=with_profile,netcredentials_only``. 644 645For more information, see `dwLogonFlags <https://docs.microsoft.com/en-gb/windows/desktop/api/winbase/nf-winbase-createprocesswithtokenw>`_. 646 647Here are some examples of how to use ``become_flags`` with Windows tasks: 648 649.. code-block:: yaml 650 651 - name: copy a file from a fileshare with custom credentials 652 win_copy: 653 src: \\server\share\data\file.txt 654 dest: C:\temp\file.txt 655 remote_src: yes 656 vars: 657 ansible_become: yes 658 ansible_become_method: runas 659 ansible_become_user: DOMAIN\user 660 ansible_become_password: Password01 661 ansible_become_flags: logon_type=new_credentials logon_flags=netcredentials_only 662 663 - name: run a command under a batch logon 664 win_whoami: 665 become: yes 666 become_flags: logon_type=batch 667 668 - name: run a command and not load the user profile 669 win_whomai: 670 become: yes 671 become_flags: logon_flags= 672 673 674Limitations of become on Windows 675-------------------------------- 676 677* Running a task with ``async`` and ``become`` on Windows Server 2008, 2008 R2 678 and Windows 7 only works when using Ansible 2.7 or newer. 679 680* By default, the become user logs on with an interactive session, so it must 681 have the right to do so on the Windows host. If it does not inherit the 682 ``SeAllowLogOnLocally`` privilege or inherits the ``SeDenyLogOnLocally`` 683 privilege, the become process will fail. Either add the privilege or set the 684 ``logon_type`` flag to change the logon type used. 685 686* Prior to Ansible version 2.3, become only worked when 687 ``ansible_winrm_transport`` was either ``basic`` or ``credssp``. This 688 restriction has been lifted since the 2.4 release of Ansible for all hosts 689 except Windows Server 2008 (non R2 version). 690 691* The Secondary Logon service ``seclogon`` must be running to use ``ansible_become_method: runas`` 692 693.. seealso:: 694 695 `Mailing List <https://groups.google.com/forum/#!forum/ansible-project>`_ 696 Questions? Help? Ideas? Stop by the list on Google Groups 697 `irc.libera.chat <https://libera.chat/>`_ 698 #ansible IRC chat channel 699