win_shell – Execute shell commands on target hosts
win_shell – Execute shell commands on target hosts
New in version 2.2.
Synopsis
- The
win_shell
module takes the command name followed by a list of space-delimited arguments. It is similar to the win_command module, but runs the command via a shell (defaults to PowerShell) on the target host. - For non-Windows targets, use the shell 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. | |
executable path |
Change the shell used to execute the command (eg, The target shell must accept a | |
free_form string / required |
The There is no parameter actually named 'free form'. See the examples! | |
no_profile boolean added in 2.8 |
|
Do not load the user profile before running a command. This is only valid when using PowerShell as the executable. |
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 added in 2.5 |
Set the stdin of the command directly to the specified value. |
Notes
Note
- If you want to run an executable securely and predictably, it may be better to use the win_command module instead. Best practices when writing playbooks will follow the trend of using win_command unless
win_shell
is explicitly required. When running ad-hoc commands, use your best judgement. - WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use
win_shell
to spawn long-running child or background processes. Consider creating a Windows service for managing background processes.
See Also
See also
- psexec – Runs commands on a remote Windows host based on the PsExec model
- The official documentation on the psexec module.
- raw – Executes a low-down and dirty command
- The official documentation on the raw module.
- script – Runs a local script on a remote node after transferring it
- The official documentation on the script module.
- shell – Execute shell commands on targets
- The official documentation on the shell 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.
Examples
# Execute a command in the remote shell; stdout goes to the specified
# file on the remote.
- win_shell: C:\somescript.ps1 >> C:\somelog.txt
# Change the working directory to somedir/ before executing the command.
- win_shell: C:\somescript.ps1 >> C:\somelog.txt chdir=C:\somedir
# You can also use the 'args' form to provide the options. This command
# will change the working directory to somedir/ and will only run when
# somedir/somelog.txt doesn't exist.
- win_shell: C:\somescript.ps1 >> C:\somelog.txt
args:
chdir: C:\somedir
creates: C:\somelog.txt
# Run a command under a non-Powershell interpreter (cmd in this case)
- win_shell: echo %HOMEDIR%
args:
executable: cmd
register: homedir_out
- name: Run multi-lined shell commands
win_shell: |
$value = Test-Path -Path C:\temp
if ($value) {
Remove-Item -Path C:\temp -Force
}
New-Item -Path C:\temp -ItemType Directory
- name: Retrieve the input based on stdin
win_shell: '$string = [Console]::In.ReadToEnd(); Write-Output $string.Trim()'
args:
stdin: Input message
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
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/win_shell_module.html