Updated April 14, 2023
Introduction to Ansible Shell Module
Ansible has a lot of such modules which are a direct replacement of your commands or set of commands on target systems. Even though we have almost all the things covered in Ansible, but still we sometimes need commands to be directly executed on remote target hosts as we use in Bash or Shell scripting. This enables us to keep the originality of execution mode in the available shell. For this kind of requirement, we use the Ansible shell module for Linux based operating systems and win_shell for Microsoft Windows-based operating systems. In this article, we will learn about it and how to use it.
What is Ansible Shell Module?
In Ansible, we have a shell module that is used to run commands on /bin/shell on target remote machines. This module takes the commands as input along with a set of arguments. There are few notes which one must remember while working with Ansible shell module:
- Freeform command or command separated by semicolon are accepted, they can be provided under cmd parameter, which we can see in the example section.
- This module is similar to the command module with a difference that commands will be run on a shell
(/bin/sh) on remote target machines. - If you want to run a command securely and predictably, then instead of this module, use
command module. - To use a variable and realized properly, use {{ var|quote }} rather than just {{ var }}. This will make sure no special characters like semicolon will be realized.
- When you need to run a script, then use the Ansible script module with a template module, if required.
- For reboot requirements, use the reboot or win_reboot module in playbooks.
How does the Ansible Shell Module Work?
For the Ansible shell module, like any other module, we have a set of acceptable parameters and accordingly acceptable values. For some of the parameters, there is a default value. Below we will go through most of those if not all.
- – cmd: Below this, we give the command to be executed.
- – chdir: Under this, we give the path of the directory to change into, before running the command.
- – creates: To mention the filename which if exists, then do not run the command.
- – executables: To give the absolute path of the executable which is a shell under which the command will run.
- – removes: To give the filename which if does not exists then do not run the command.
- – stdin: To set the stdin of command.
- – stdin_add_newline: Default is yes. This is to set for add newline to stdin data.
- – warn: Default is yes. This to enable task warning.
Now, we must understand the return values which can be provided by the Ansible shell module, based on the parameters and arguments provided to it. This is an important aspect, as our next tasks in a playbook may be dependent on the return value provided by the shell module. Below are a list and a small description for the return values for this module.
- cmd: The command executed by the task.
- delta: The time taken to run the command.
- msg: if changed was made or not, True and False will be provided.
- nd: The command execution end time.
- rc: Return code for command, zero (0) means success, anything other than zero means there is some issue.
- start: Start time of command.
- stderr: Error in the command execution output, if any.
- stdout: Standard output of the command.
- stdout_lines: Standard output of the command, split in lines.
Example of Ansible Shell Module
In this section, we will learn by doing looking at some examples where we tried to test the functionality of the Ansible shell module. But we shall know about our lab environment before moving ahead in this section.
Here we have one Ansible controller node named as ansible-controller. As target nodes, we have two remote machines. The first machine is a Red Hat Enterprise Linux machine named as the host-one and the second machine is an Ubuntu machine named as host-two. We will run our playbooks on the Ansible controller machine and make changes on remote target machines.
Example #1
In this example, we have a playbook like below, using which we will run some simple commands on remote target machines.
---
- hosts: all tasks:
- name: Here we will run a simple command on remote taret machines shell: cat /var/tmp/sample.txt
After running this command like below we get below output. Where we can see the stdout or stdout_lines section for the standard output of the command execution. Also, as we have used the verbose mode while running the ansible-playbook command, we can see other return values as well like command execution start, delta, end time and rc, etc.
ansible-playbook ansible_shell.yaml -v
Example #2
In this example, we have a playbook in which we have used Ansible facts, conditionals, and another way to give command using the cmd parameter.
---
hosts: all tasks:
name: Here we are checking & showing the /etc/redhat-release on rhel machine based on condition block:
name: Here we are showing the /etc/redhat-release on rhel shell: cat /etc/redhat-release
register: var_redhat
debug:
var: var_redhat.stdout_lines
when: ansible_distribution == "RedHat"
name: Here we are checking & showing the /etc/lsb-release on Ubuntu machine based on condition block:
name: Here we are showing the /etc/lsb-release on Ubuntu shell:
cmd: cat /etc/lsb-release register: var_ubuntu
debug:
var: var_ubuntu.stdout_lines
when: ansible_distribution == "Ubuntu"
Now running this playbook like below and having the below output, we can see that when the Linux distribution is RedHat, then it will print the /etc/redhat-release file using linux’s cat command. Also, on Ubuntu system /etc/lsb-release file’s content is printed. We checked the OS on remote machines using conditionals set over different Ansible blocks.
ansible-playbook ansible_shell_arguments.yaml
Recommended Articles
This is a guide to Ansible Shell Module. Here we also discuss the introduction and how does the ansible shell module works along with different examples and its code implementation. You may also have a look at the following articles to learn more –
