ansible.windows.win_shell – Execute shell commands on target hosts
ansible.windows.win_shell – Execute shell commands on target hosts
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_shell
.
Synopsis
- The ansible.windows.win_shell module takes the command name followed by a list of space-delimited arguments. It is similar to the ansible.windows.win_command module, but runs the command via a shell (defaults to PowerShell) on the target host.
- For non-Windows targets, use the ansible.builtin.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 ansible.windows.win_shell module takes a free form command to run. There is no parameter actually named 'free form'. See the examples! | |
no_profile boolean |
|
Do not load the user profile before running a command. This is only valid when using PowerShell as the executable. |
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 an executable securely and predictably, it may be better to use the ansible.windows.win_command module instead. Best practices when writing playbooks will follow the trend of using ansible.windows.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 ansible.windows.win_shell to spawn long-running child or background processes. Consider creating a Windows service for managing background processes.
See Also
See also
- community.windows.psexec
- The official documentation on the community.windows.psexec module.
- ansible.builtin.raw
- The official documentation on the ansible.builtin.raw module.
- ansible.builtin.script
- The official documentation on the ansible.builtin.script module.
- ansible.builtin.shell
- The official documentation on the ansible.builtin.shell module.
- ansible.windows.win_command
- The official documentation on the ansible.windows.win_command module.
- community.windows.win_psexec
- The official documentation on the community.windows.win_psexec module.
Examples
- name: Execute a comand in the remote shell, stdout goes to the specified file on the remote
ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt
- name: Change the working directory to somedir/ before executing the command
ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt
args:
chdir: C:\somedir
- name: Run a command with an idempotent check on what it creates, will only run when somedir/somelog.txt does not exist
ansible.windows.win_shell: C:\somescript.ps1 >> C:\somelog.txt
args:
chdir: C:\somedir
creates: C:\somelog.txt
- name: Run a command under a non-Powershell interpreter (cmd in this case)
ansible.windows.win_shell: echo %HOMEDIR%
args:
executable: cmd
register: homedir_out
- name: Run multi-lined shell commands
ansible.windows.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
ansible.windows.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@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_shell_module.html