win_psexec - Runs commands (remotely) as another (privileged) user

New in version 2.3.

Synopsis

  • Run commands (remotely) through the PsExec service
  • Run commands as another (domain) user (with elevated privileges)

Requirements (on host that executes module)

  • Microsoft PsExec

Options

parameter required default choices comments
chdir
 no
Run the command from this (remote) directory.
command
 yes
The command line to run through PsExec (limited to 260 characters).
elevated
 no no
  • yes
  • no
Run the command with elevated privileges.
executable
 no psexec.exe
The location of the PsExec utility (in case it is not located in your PATH).
hostnames
 no
The hostnames to run the command.
If not provided, the command is run locally.
interactive
 no no
  • yes
  • no
Run the program so that it interacts with the desktop on the remote system.
limited
 no no
  • yes
  • no
Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group).
nobanner
(added in 2.4)
 no no
  • yes
  • no
Do not display the startup banner and copyright message.
This only works for specific versions of the PsExec binary.
noprofile
 no no
  • yes
  • no
Run the command without loading the account's profile.
password
 no
The password for the (remote) user to run the command as.
This is mandatory in order authenticate yourself.
priority
 no
  • background
  • low
  • belownormal
  • abovenormal
  • high
  • realtime
Used to run the command at a different priority.
system
 no no
  • yes
  • no
Run the remote command in the System account.
timeout
 no
The connection timeout in seconds
username
 no
The (remote) user to run the command as.
If not provided, the current user is used.
wait
 no yes
  • yes
  • no
Wait for the application to terminate.
Only use for non-interactive applications.

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 Return Values, the following are the fields unique to this module:

name description returned type sample
changed
Whether or not any changes were made.
 always bool True
cmd
The complete command line used by the module, including PsExec call and additional options.
 always string psexec.exe -nobanner \\remote_server -u "DOMAIN\Administrator" -p "some_password" -accepteula E:\setup.exe
msg
Possible error message on failure
 failed string The 'password' parameter is a required parameter.
rc
The return code for the command
 always int 0
stderr
The error output from the command
 always string Error 15 running E:\setup.exe
stdout
The standard output from the command
 always string Success.

Notes

Note

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/win_psexec_module.html