ansible.builtin.shell – Execute shell commands on targets¶
Note
This module is part of ansible-base
and included in all Ansible
installations. In most cases, you can use the short module name
shell even without specifying the collections:
keyword.
Despite that, we recommend you use the FQCN for easy linking to the module
documentation and to avoid conflicting with other collections that may have
the same module name.
New in version 0.2: of ansible.builtin
Synopsis¶
The
shell
module takes the command name followed by a list of space-delimited arguments.Either a free form command or
cmd
parameter is required, see the examples.It is almost exactly like the ansible.builtin.command module but runs the command through a shell (
/bin/sh
) on the remote node.For Windows targets, use the ansible.windows.win_shell module instead.
Note
This module has a corresponding action plugin.
Parameters¶
Notes¶
Note
If you want to execute a command securely and predictably, it may be better to use the ansible.builtin.command module instead. Best practices when writing playbooks will follow the trend of using ansible.builtin.command unless the ansible.builtin.shell module is explicitly required. When running ad-hoc commands, use your best judgement.
Check mode is supported when passing
creates
orremoves
. If running in check mode and either of these are specified, the module will check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.To sanitize any variables passed to the shell module, you should use
{{ var | quote }}
instead of just{{ var }}
to make sure they do not include evil things like semicolons.An alternative to using inline shell scripts with this module is to use the ansible.builtin.script module possibly together with the ansible.builtin.template module.
For rebooting systems, use the ansible.builtin.reboot or ansible.windows.win_reboot module.
See Also¶
See also
- ansible.builtin.command
The official documentation on the ansible.builtin.command 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.windows.win_shell
The official documentation on the ansible.windows.win_shell module.
Examples¶
- name: Execute the command in remote shell; stdout goes to the specified file on the remote
ansible.builtin.shell: somescript.sh >> somelog.txt
- name: Change the working directory to somedir/ before executing the command
ansible.builtin.shell: somescript.sh >> somelog.txt
args:
chdir: somedir/
# You can also use the 'args' form to provide the options.
- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
ansible.builtin.shell: somescript.sh >> somelog.txt
args:
chdir: somedir/
creates: somelog.txt
# You can also use the 'cmd' parameter instead of free form format.
- name: This command will change the working directory to somedir/
ansible.builtin.shell:
cmd: ls -l | grep log
chdir: somedir/
- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
ansible.builtin.shell: cat < /tmp/*txt
args:
executable: /bin/bash
- name: Run a command using a templated variable (always use quote filter to avoid injection)
ansible.builtin.shell: cat {{ myfile|quote }}
# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
ansible.builtin.shell: |
set timeout 300
spawn ssh admin@{{ cimc_host }}
expect "password:"
send "{{ cimc_password }}\n"
expect "\n{{ cimc_name }}"
send "connect host\n"
expect "pxeboot.n12"
send "\n"
exit 0
args:
executable: /usr/bin/expect
delegate_to: localhost
# Disabling warnings
- name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning
ansible.builtin.shell: curl --socks5 localhost:9000 http://www.ansible.com
args:
warn: no
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Ansible Core Team
Michael DeHaan