Ansible Modules and Ad-Hoc Commands


When you want to run something on the remote managed hosts using Ansible, you perform either a single task or a set of tasks. For a single task, you use ad-hoc commands and for a set of tasks, you will need playbooks.

You use ad-hoc commands if you want to do something really quick for only one time that does not necessarily needs a playbook, like powering off or rebooting a group of servers or stopping a specific service.

Both Ansible ad-hoc commands and playbooks use modules, which are unites of code that performs the actual task. There are many modules in Ansible that can be used to run all kind of tasks.

Use the ansible-doc -l command to get the list of all modules available.

To get more information about a module, you can use ansible-doc along with the module name. This is a very useful command as it provides a full description of the module, all arguments that can be used with it, a clear and concise help on how to use them, and some very helpful examples.

Here we want to get more information about the win_service module, which is used to manage Windows services.

A practical example

Let’s sat we want to find out the module syntax that needs to be run to install the nginx server on your RHEL/CentOS remote server, so it is already assumed that yum package manager is used for package installation.

We first start by searching in the Ansible modules documentation for any yum module.

We will then have a closer look on how this module is used and what are its arguments with ansible-doc yum. This command will provide detailed information but the ones that are of interest for us is the name and state arguments. The mandatory arguments like name are preceded by = sign.

Both argments are mandatory here. name will tell Ansible which package is needed and state with the value “installed” to effectively install the package. This will be enough to install the nginx server. Below is the command:

  • -m is used to provide the name of the module.
  • -a is used to pass the module arguments.
  • -b is for privilege escalation. If used, Ansible will use root privileges to run the command.

If you have any doubts to figure out the minimal syntax for your command to work, you can find some great examples at the end of the ansible-doc. These are mainly for describing playbooks syntax, but you can also use them for ad-hoc commands. You just need to write the module arguments in one line and replace the collon (:) with equal sign (=) as done in the previous example.


Ad-Hoc Commands

Ansible ad-hoc commands are run using the “ansible” command, followed by the IP, hostname, or hostgroup on which the task needs to be run, then the actual module and its arguments, if any.

For example, the following ad-hoc command will test the connectivity to the all group

The only thing ping module does is checking that Ansible is able to start an SSH session with the server. The “changed”: false part of the output tells us that executing the module did not change the state of the server.

This one will check the uptime of the appservers group.

The command module is so commonly used that it’s the default module, so we can omit it.

This following command will reboot all servers in appservers group.


If we need root access access, we pass in the -b argument to become root and the -K argument to allow root password input while executing the ad-hoc command. Obviously, with the use of a configuration file, there is no need to pass these arguments.

Let’s run some common admin tasks using ad-hoc commands.

  • Installing Apache on the the webservers group

We can check the successful installation on the remote host

  • Starting the httpd service on all servers in the webservers group

  • Creating files and directories

Another example would be creating a files or directories on remote hosts using the file module. Again, if you have any doubt about which module does which task, the ansible-doc -l and the ansible-doc file commands will be your friends.

In this example, the file is called /tmp/testFile.txt and will be created in the appservers group. The state argument is used here creates the file if it does not exist.

The file has been created successfully. You might want to ssh to server2 to check the file is effectively there.

To create a directory, the state argument is also used, simply by defining state=directory.

  • Copying files and directories

If you have a an existing file or directory that needs to be copied to your remote servers, the copy module is used for this purpose. We have here a directory called AppFiles containing three files.

To copy this directory along with the files inside it to the appservers, the following command will do it.

In the above command, the src and dest arguments are mandatory with the copy module. All the other arguments are optional.s

Let’s check the result!

As you can see, ad-hoc commands are very useful for one-off kind of things but you won’t use them that often for complex repetitive and automated tasks. Instead, you will use playbooks most of the time, and this is what we will see in the next post.


Find this post interesting. Share it!

1 Comment

  1. Pingback: Ansible for the Impatient Beginners – vAdmin-Land

Leave a Comment

Your email address will not be published. Required fields are marked *