How become Works

become lets a task execute under a different user identity than the one used to connect to the target. This page explains when to reach for it, how the runtime handles identity switching on each platform, and how become settings propagate through the task hierarchy.

When To Use become

Use become when a task produces results that belong to a specific user:

• Writing to HKCU:\ registry keys for a named account
• Setting user-scoped environment variables
• Creating files in %APPDATA% or %USERPROFILE%
• Running an application’s first-launch setup in the context of a kiosk account
• Any task where the user identity changes the outcome

Do not use become when the task only needs elevated privilege on Windows — on Windows that is handled by the transport account’s privilege level, not by become. On POSIX, the opposite holds: become: {enabled: true} (which means root) is the documented way to run a requires_root module (service, user, system_package, reboot) from an unprivileged SSH session.

Runtime Methods

Windows — runas

On Windows, become defaults to method: runas. How the identity switch happens depends on the target type:

• Local target — Preflight relaunches itself as a child process under the target user’s credentials, with stdio redirected so module input and output flow through normally.
• Remote targets (WinRM and Windows-over-SSH) — a remote session is non-interactive and has no window station, so starting a process directly under alternate credentials fails inside it. Preflight instead stages the task script on the target, grants the become user the batch-logon right if needed, registers and runs a one-shot scheduled task as that user, waits for it to finish, and replays its output. A non-zero exit code from the task is surfaced as the task’s failure.

Staged files and the scheduled task are cleaned up after the task regardless of outcome.

A password is required for all Windows become users. Preflight rejects a task with become.user set but no password.

POSIX — sudo

On POSIX targets (SSH with a POSIX shell runtime, and the local target on a POSIX machine), become defaults to method: sudo. The recommended posture is unprivileged SSH user + become: connect as an ordinary user and escalate per task, rather than allowing root SSH login. Root login over SSH is a stated working alternative — it passes the requires_root check with no become.

A bare become: {enabled: true} with no user means root on POSIX. This fixes the former empty-user sudo wrap. Windows keeps requiring an explicit become.user.

Preflight wraps the command as:

sudo -n -u <user> /bin/sh -lc <command>

The -n flag makes a password-requiring sudo fail deterministically instead of hanging the run on a prompt. When a password is provided, it is fed via sudo -S -p '' on stdin.

Password-first posture. The documented primary path is become.password backed by a secret: reference; relying on NOPASSWD sudoers is the fallback, not the headline. See Run tasks as another user for the defaults.become + host-var sudo_password pattern.

requires_root modules. Some modules (service, user, system_package, reboot) require an effective root user. Preflight probes id -u once per target (cached with runtime detection) and fails the task before Check() with a requires-root-violation reason code when the effective user is not root. The effective user is become.user when become is enabled, otherwise the session user — so become-to-a-non-root-user is caught by the same check. The wording names the module and offers both fixes: run as root, or set become: {enabled: true}.

sudo availability. sudo is required only when become is used. A POSIX target with become enabled but no sudo binary fails fast with a sudo-missing reason code. A no-password sudo -n run that needs a password fails with sudo-password-required; a rejected password fails with sudo-auth-failed.

When no password is provided, sudo must already be configured to allow the transport user to switch to the target user without a password prompt (for example, via a NOPASSWD rule in /etc/sudoers).

load_profile

On the local Windows target, runas does not automatically load the target user’s profile. When load_profile: true is set, the child process is started with the user’s profile loaded, which populates the user’s environment variables (APPDATA, USERPROFILE, HOME, etc.) before the task runs. Use load_profile: true any time a local task depends on user profile paths or user-specific environment variables.

On remote Windows targets (WinRM and Windows-over-SSH), the scheduled task’s password logon always loads the target user’s profile, so load_profile has no additional effect there.

become:
  user: exhibit
  password: secret:exhibit-password
  load_profile: true

On POSIX, sudo -u <user> /bin/sh -lc already loads a login shell, so load_profile has no additional effect.

Inheritance Model

become flows down through three levels, with more-specific settings winning:

playbook defaults.become
  -> action defaults.become
    -> task become

Each level performs a shallow merge — keys present in the override layer replace keys from the parent. This means you can set a default user and password at the playbook level and override only load_profile on a single task:

defaults:
  become:
    user: exhibit
    password: secret:exhibit-password

tasks:
  - name: Write profile-dependent config
    become:
      load_profile: true
    powershell:
      script: New-Item -ItemType Directory "$env:APPDATA\ExhibitApp" -Force | Out-Null

Setting enabled: false on a task disables the inherited become for that task regardless of any parent defaults:

  - name: Create exhibit user (runs as transport account)
    become:
      enabled: false
    user:
      name: exhibit
      password: secret:exhibit-password
      ensure: present

Secret Resolution

become.password supports the same secret:<name> reference syntax as module params. Preflight resolves the secret immediately before task execution. Secret values are never written into staged bundles — playbooks that use become with secret-backed passwords cannot be staged.

State And Redaction

become metadata is recorded alongside task params in the state file. The password value is redacted in all state output and diffs.

Related Docs

• Run tasks as another user — step-by-step how-to
• Playbook and action YAML reference — become field reference
• Error reference — the sudo-* and requires-root-violation reason codes
• Manage secrets