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

From Get docs
Ansible/docs/2.10/collections/community/windows/win psexec module


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

Note

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

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 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

  • 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).

hostnames

list / elements=string

The hostnames to run the command.

If not provided, the command is run locally.

interactive

boolean

  • no

  • yes

Run the program so that it interacts with the desktop on the remote system.

limited

boolean

  • no

  • yes

Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group).

nobanner

boolean

  • no

  • yes

Do not display the startup banner and copyright message.

This only works for specific versions of the PsExec binary.

noprofile

boolean

  • 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

string

  • abovenormal
  • background
  • belownormal
  • high
  • low
  • realtime

Used to run the command at a different priority.

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

  • 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

  • no
  • yes

Wait for the application to terminate.

Only use for non-interactive applications.



Notes

Note


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 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.




Authors

  • Dag Wieers (@dagwieers)

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