- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_psexec – Runs commands (remotely) as another (privileged) user

- Synopsis

- Requirements

- Parameters

- Notes

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Run commands (remotely) through the PsExec service.

- Run commands as another (domain) user (with elevated privileges).

## Requirements

The below requirements are needed on the host that executes this module.

- Microsoft PsExec

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
chdir path |  | Run the command from this (remote) directory.
command string / required |  | The command line to run through PsExec (limited to 260 characters).
elevated boolean | Choices: no ← yes | Run the command with elevated privileges.
executable path | Default: "psexec.exe" | The location of the PsExec utility (in case it is not located in your PATH).
extra_opts list |  | Specify additional options to add onto the PsExec invocation. This module was undocumented in older releases and will be removed in Ansible 2.10.
hostnames list |  | The hostnames to run the command. If not provided, the command is run locally.
interactive boolean | Choices: no ← yes | Run the program so that it interacts with the desktop on the remote system.
limited boolean | Choices: no ← yes | Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group).
nobanner boolean added in 2.4 | Choices: no ← yes | Do not display the startup banner and copyright message. This only works for specific versions of the PsExec binary.
noprofile boolean | Choices: no ← yes | Run the command without loading the account's profile.
password string |  | The password for the (remote) user to run the command as. This is mandatory in order authenticate yourself.
priority - | Choices: abovenormal background belownormal high low realtime | Used to run the command at a different priority.
session integer added in 2.7 |  | Specifies the session ID to use. This parameter works in conjunction with interactive. It has no effect when interactive is set to `no`.
system boolean | Choices: no ← yes | Run the remote command in the System account.
timeout integer |  | The connection timeout in seconds
username string |  | The (remote) user to run the command as. If not provided, the current user is used.
wait boolean | Choices: no yes ← | Wait for the application to terminate. Only use for non-interactive applications.

## Notes

Note

- More information related to Microsoft PsExec is available from https://technet.microsoft.com/en-us/sysinternals/bb897553.aspx

## See Also

See also

psexec – Runs commands on a remote Windows host based on the PsExec model

  The official documentation on the psexec module.

raw – Executes a low-down and dirty command

  The official documentation on the raw module.

win_command – Executes a command on a remote Windows node

  The official documentation on the win_command module.

win_shell – Execute shell commands on target hosts

  The official documentation on the win_shell module.

## Examples

    - name: Test the PsExec connection to the local system (target node) with your user
      win_psexec:
        command: whoami.exe

    - name: Run regedit.exe locally (on target node) as SYSTEM and interactively
      win_psexec:
        command: regedit.exe
        interactive: yes
        system: yes

    - name: Run the setup.exe installer on multiple servers using the Domain Administrator
      win_psexec:
        command: E:\setup.exe /i /IACCEPTEULA
        hostnames:
        - remote_server1
        - remote_server2
        username: DOMAIN\Administrator
        password: some_password
        priority: high

    - name: Run PsExec from custom location C:\Program Files\sysinternals\
      win_psexec:
        command: netsh advfirewall set allprofiles state off
        executable: C:\Program Files\sysinternals\psexec.exe
        hostnames: [ remote_server ]
        password: some_password
        priority: low

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
cmd string | always | The complete command line used by the module, including PsExec call and additional options. Sample: psexec.exe -nobanner \\remote_server -u "DOMAIN\Administrator" -p "some_password" -accepteula E:\setup.exe
pid integer | when `wait=False` | The PID of the async process created by PsExec. Sample: 1532
rc integer | always | The return code for the command.
stderr string | always | The error output from the command. Sample: Error 15 running E:\setup.exe
stdout string | always | The standard output from the command. Sample: Success.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Dag Wieers (@dagwieers)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.