You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.windows.win_psexec – Runs commands (remotely) as another (privileged) user

Note

This plugin is part of the community.windows collection (version 1.8.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_psexec.

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	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	Run the command with elevated privileges. Choices: no ← (default) yes
executable path	The location of the PsExec utility (in case it is not located in your PATH). Default: “psexec.exe”
hostnames list / elements=string	The hostnames to run the command. If not provided, the command is run locally.
interactive boolean	Run the program so that it interacts with the desktop on the remote system. Choices: no ← (default) yes
limited boolean	Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group). Choices: no ← (default) yes
nobanner boolean	Do not display the startup banner and copyright message. This only works for specific versions of the PsExec binary. Choices: no ← (default) yes
noprofile boolean	Run the command without loading the account’s profile. Choices: no ← (default) yes
password string	The password for the (remote) user to run the command as. This is mandatory in order authenticate yourself.
priority string	Used to run the command at a different priority. Choices: abovenormal background belownormal high low realtime
session integer	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	Run the remote command in the System account. Choices: no ← (default) yes
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	Wait for the application to terminate. Only use for non-interactive applications. Choices: no yes ← (default)

Notes

Note

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

See Also

See also

community.windows.psexec

The official documentation on the community.windows.psexec module.

ansible.builtin.raw

The official documentation on the ansible.builtin.raw module.

ansible.windows.win_command

The official documentation on the ansible.windows.win_command module.

ansible.windows.win_shell

The official documentation on the ansible.windows.win_shell module.

Examples

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

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

- name: Run the setup.exe installer on multiple servers using the Domain Administrator
  community.windows.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\
  community.windows.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	Description
cmd string	The complete command line used by the module, including PsExec call and additional options. Returned: always Sample: “psexec.exe -nobanner \\\\remote_server -u \”DOMAIN\\Administrator\” -p \”some_password\” -accepteula E:\\setup.exe”
pid integer	The PID of the async process created by PsExec. Returned: when wait=False Sample: 1532
rc integer	The return code for the command. Returned: always Sample: 0
stderr string	The error output from the command. Returned: always Sample: “Error 15 running E:\\setup.exe”
stdout string	The standard output from the command. Returned: always Sample: “Success.”

Authors

• Dag Wieers (@dagwieers)