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, cmd ).The target shell must accept a /c parameter followed by the raw command line to be executed. | |
free_form string / required | The win_shell module takes a free form command to run.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)
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.8/modules/win_shell_module.html