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
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
- / required
The win_command module takes a free form command to run.
There is no parameter actually named 'free form'. See the examples!
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
-
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. The win_command module is much more secure as it’s not affected by the user’s environment.
  • creates, removes, and chdir 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
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@master ...
stdout_lines
list
 always
The command standard output split in lines

Sample:
["u'Clustering node rabbit@slave1 with rabbit@master ...'"]


Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Matt Davis (@nitzmahone)

Hint

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