win_command - Executes a command on a remote Windows node
New in version 2.2.
Synopsis
- The
win_command
module takes the command name followed by a list of space-delimited arguments. - The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like
$env:HOME
and operations like"<"
,">"
,"|"
, and";"
will not work (use the win_shell module if you need these features). - For non-Windows targets, use the command module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
chdir | Set the specified path as the current working directory before executing a command. | |
creates | A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. | |
free_form required | The win_command module takes a free form command to run.There is no parameter actually named 'free form'. See the examples! | |
removes | A path or path filter pattern; when the referenced path does not exist on the target host, the task will be skipped. | |
stdin (added in 2.5) | Set the stdin of the command directly to the specified value. |
Notes
Note
- If you want to run a command through a shell (say you are using
<
,>
,|
, etc), you actually want the win_shell module instead. Thewin_command
module is much more secure as it’s not affected by the user’s environment. -
creates
,removes
, andchdir
can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this. - For non-Windows targets, use the command module instead.
Examples
- name: Save the result of 'whoami' in 'whoami_out' win_command: whoami register: whoami_out - name: Run command that only runs if folder exists and runs from a specific folder win_command: wbadmin -backupTarget:C:\backup\ args: chdir: C:\somedir\ creates: C:\backup\ - name: Run an executable and send data to the stdin for the executable win_command: powershell.exe - args: stdin: Write-Host test
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
cmd string | always | The command executed by the task Sample: rabbitmqctl join_cluster rabbit@master |
delta string | always | The command execution delta time Sample: 0:00:00.325771 |
end string | always | The command execution end time Sample: 2016-02-25 09:18:26.755339 |
msg boolean | always | changed Sample: True |
rc int | always | The command return code (0 means success) |
start string | always | The command execution start time Sample: 2016-02-25 09:18:26.429568 |
stderr string | always | The command standard error Sample: ls: cannot access foo: No such file or directory |
stdout string | always | The command standard output Sample: Clustering node rabbit@slave1 with rabbit@master ... |
stdout_lines list | always | The command standard output split in lines Sample: ["u'Clustering node rabbit@slave1 with rabbit@master ...'"] |
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Maintenance
This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.
For a list of other modules that are also maintained by the Ansible Core Team, see here.
Support
For more information about Red Hat’s support of this module, please refer to this Knowledge Base article
Author
- Matt Davis (@nitzmahone)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.6/modules/win_command_module.html