ansible.windows.win_command – Executes a command on a remote Windows node
ansible.windows.win_command – Executes a command on a remote Windows node
Note
This plugin is part of the ansible.windows collection (version 1.3.0).
To install it use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_command
.
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 ansible.windows.win_shell module if you need these features). - For non-Windows targets, use the ansible.builtin.command module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
chdir path |
Set the specified path as the current working directory before executing a command. | |
creates path |
A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. | |
free_form string / required |
The There is no parameter actually named 'free form'. See the examples! | |
output_encoding_override string |
This option overrides the encoding of stdout/stderr output. You can use this option when you need to run a command which ignore the console's codepage. You should only need to use this option in very rare circumstances. This value can be any valid encoding | |
removes path |
A path or path filter pattern; when the referenced path does not exist on the target host, the task will be skipped. | |
stdin string |
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 ansible.windows.win_shell module instead. The ansible.windows.win_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.
See Also
See also
- ansible.builtin.command
- The official documentation on the ansible.builtin.command module.
- community.windows.psexec
- The official documentation on the community.windows.psexec module.
- ansible.builtin.raw
- The official documentation on the ansible.builtin.raw module.
- community.windows.win_psexec
- The official documentation on the community.windows.win_psexec module.
- ansible.windows.win_shell
- The official documentation on the ansible.windows.win_shell module.
Examples
- name: Save the result of 'whoami' in 'whoami_out'
ansible.windows.win_command: whoami
register: whoami_out
- name: Run command that only runs if folder exists and runs from a specific folder
ansible.windows.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
ansible.windows.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@main |
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 integer |
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@main ... |
stdout_lines list / elements=string |
always |
The command standard output split in lines
Sample: ["u'Clustering node rabbit@slave1 with rabbit@main ...'"] |
Authors
- Matt Davis (@nitzmahone)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/windows/win_command_module.html