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

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

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

Authors

  • Dag Wieers (@dagwieers)

Hint

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