psexec – Runs commands on a remote Windows host based on the PsExec model¶
New in version 2.6.
Synopsis¶
Runs a remote command from a Linux host to a Windows host without WinRM being set up.
Can be run on the Ansible controller to bootstrap Windows hosts to get them ready for WinRM.
Requirements¶
The below requirements are needed on the host that executes this module.
pypsexec
smbprotocol[kerberos] for optional Kerberos authentication
Parameters¶
Notes¶
Note
This module requires the Windows host to have SMB configured and enabled, and port 445 opened on the firewall.
This module will wait until the process is finished unless asynchronous is
yes, ensure the process is run as a non-interactive command to avoid infinite hangs waiting for input.The connection_username must be a member of the local Administrator group of the Windows host. For non-domain joined hosts, the
LocalAccountTokenFilterPolicyshould be set to1to ensure this works, see https://support.microsoft.com/en-us/help/951016/description-of-user-account-control-and-remote-restrictions-in-windows.For more information on this module and the various host requirements, see https://github.com/jborean93/pypsexec.
See Also¶
See also
- 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_psexec – Runs commands (remotely) as another (privileged) user
The official documentation on the win_psexec module.
- win_shell – Execute shell commands on target hosts
The official documentation on the win_shell module.
Examples¶
- name: Run a cmd.exe command
psexec:
hostname: server
connection_username: username
connection_password: password
executable: cmd.exe
arguments: /c echo Hello World
- name: Run a PowerShell command
psexec:
hostname: server.domain.local
connection_username: username@DOMAIN.LOCAL
connection_password: password
executable: powershell.exe
arguments: Write-Host Hello World
- name: Send data through stdin
psexec:
hostname: 192.168.1.2
connection_username: username
connection_password: password
executable: powershell.exe
arguments: '-'
stdin: |
Write-Host Hello World
Write-Error Error Message
exit 0
- name: Run the process as a different user
psexec:
hostname: server
connection_user: username
connection_password: password
executable: whoami.exe
arguments: /all
process_username: anotheruser
process_password: anotherpassword
- name: Run the process asynchronously
psexec:
hostname: server
connection_username: username
connection_password: password
executable: cmd.exe
arguments: /c rmdir C:\temp
asynchronous: yes
- name: Use Kerberos authentication for the connection (requires smbprotocol[kerberos])
psexec:
hostname: host.domain.local
connection_username: user@DOMAIN.LOCAL
executable: C:\some\path\to\executable.exe
arguments: /s
- name: Disable encryption to work with WIndows 7/Server 2008 (R2)
psexec:
hostanme: windows-pc
connection_username: Administrator
connection_password: Password01
encrypt: no
integrity_level: elevated
process_username: Administrator
process_password: Password01
executable: powershell.exe
arguments: (New-Object -ComObject Microsoft.Update.Session).CreateUpdateInstaller().IsBusy
- name: Download and run ConfigureRemotingForAnsible.ps1 to setup WinRM
psexec:
hostname: '{{ hostvars[inventory_hostname]["ansible_host"] | default(inventory_hostname) }}'
connection_username: '{{ ansible_user }}'
connection_password: '{{ ansible_password }}'
encrypt: yes
executable: powershell.exe
arguments: '-'
stdin: |
$ErrorActionPreference = "Stop"
$sec_protocols = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::SystemDefault
$sec_protocols = $sec_protocols -bor [Net.SecurityProtocolType]::Tls12
[Net.ServicePointManager]::SecurityProtocol = $sec_protocols
$url = "https://github.com/ansible/ansible/raw/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
Invoke-Expression ((New-Object Net.WebClient).DownloadString($url))
exit
delegate_to: localhost
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Status¶
This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]
Authors¶
Jordan Borean (@jborean93)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.