Tricks Of The Trades

Ansible – Ad Hoc Commands and Modules (3)

Pinterest LinkedIn Tumblr

Several ad hoc commands were shown in the previous post but no real detail was given as to what they can fully offer. These ad hoc commands are often cited as being a good starter point for learning what’s possible with Ansible; without having to dive straight into writing a playbook.

Most of them incorporate the use of a module into their structure, so this post introduces modules too. Both from the point of view of an ad hoc command, and within the context of a task. Towards the end, the “special” Ansible module types are shown.

1 – Ad Hoc Commands

Sometimes you may not need nor want to write a fully-fledged playbook for simple operations. Either way, the concepts here for these commands port directly over to the playbook language for when you do begin writing them later on. These due to their impromptu nature and use.

In their simplest form, these commands are shell commands performed in parallel to each host by Ansible.

Here coreservers is the group name that contains several hosts and the ad hoc command -a we are running on them is /sbin/reboot using 10 Ansible forks.

  1. $ ansible coreservers -a “/sbin/reboot” -f 10 -b -K

The -f 10 in the above specifies the usage of 10 simultaneous processes to use (10 hosts at a time). You can also set this as an assumed default in the configuration file to avoid setting it here. The default is set to 5, which is lacking and conservative, so feel free to increase this value to a more optimal number.

Ansible defaults to running from your current user account (or from any hosts variables). To change this pass in the -u option. Where scarlz is the username you want to run the command as.

  1. $ ansible coreservers -a “/usr/bin/foo” -u scarlz

When not calling raw programs on the node through Ansible, modules are the main choice for carrying out operations.

In general, the -m option denotes a named module. Here is an example of the shell module that is used to issue precise commands on the Ansible node.

  1. $ ansible coreservers -u scarlz -m shell -a ‘echo $TERM’

There is a whole back-catalog of these inbuilt modules for you to make use of.

2 – Modules

Modules contain the actions or functionality we want to implement and run. Some commonly used modules are apt/yum, copy, ec2, file, service, template, and user. As shown in the previous section, modules can be used in ad-hoc commands as well as “tasks”.


This command transfers a “hosts” file directly to all servers in the “coreservers” group, using SCP and the copy module:

  1. $ ansible coreservers -m copy -a “src=/etc/hosts dest=/tmp/hosts” -b -K


The file module provides the ability to change system ownership and permissions on remote files.

  1. $ ansible coreservers -m file -a “dest=/var/www/index.html mode=755 owner=scarlz group=www” -b -K

To create directories with file, like when using the mkdir -p command in Linux, add the “directory” state-directory option.

  1. $ ansible coreservers -m file -a “dest=/var/www/new-vhost-dir mode=755 owner=scarlz group=www state=directory” -b -K

Delete directories recursively, and delete files through file with the state=absent option.

  1. $ ansible coreservers -m file -a “dest=/path/to/delete state=absent”


This module is referred to when you need to interact with the OS system services. Inclusive of BSD init, OpenRC, SysV, Solaris SMF, systemd, and upstart.

As an example of how this could work, this starts Nginx via systemd:

  1. $ ansible coreservers -m service -a “name=nginx.service state=started” -b -K

Changing the state option changes the result – this is to restart:

  1. $ ansible coreservers -m service -a “name=nginx.service state=restarted” -b -K

The value of “state” must be one of either: running, started, stopped, restarted, or reloaded.

Users and Groups

A module named the “user” module serves as an interface to creating, removing, and manipulating system user accounts.

Altering a user’s password only requires the username, in this next example this is scarlz, then the new password for the user which is substituted into the <user-password> field.

  1. $ ansible coreservers -m user -a “name=scarlz password=<user-password>”

Removing the user account completely once again needs the username (scarlz in my case) as well as the value absent for the state option.

  1. $ ansible coreservers -m user -a “name=scarlz state=absent” -b -K

Practical Ad Hoc Module Example

The first command updates the Apt package index – similar to running the usual apt-get update command.

  1. $ ansible coreservers -b -K -m apt -a update_cache=yes

Continuing on from before, upgrading the system packages (like with apt-get upgrade) uses:

  1. $ ansible coreservers -b -K -m apt -a upgrade=yes

Performing a dist-upgrade uses the full switch instead of just “yes”.

  1. $ ansible coreservers -b -K -m apt -a upgrade=full

Module Index

Here’s a page from the official Ansible documentation that acts as a catalogue for all the registered inbuilt modules available. There are many many modules, to cater for all specific needs.

3 – Modules in Tasks

Here are some examples of using the modules in a task (like you’d find in an Ansible playbook).

The file module (most shown before) creates a new directory to be used for caching purposes.

  1. – name: add cache directory
  2. file: path=/opt/cache state=directory

In more detail this time, the apt module handles packages for Ubuntu/Debian OS.

The state option here designates that the install of Nginx should be implemented via apt-get, but the state value could also be replaced with latest (to update the package) or absent (to remove the package) instead.

  1. – name: install nginx
  2. yum name=nginx state=present

This one’s pretty straight forward and is the “task” equivalent of the ad hoc command from earlier.

  1. – name: start nginx
  2. service: name=nginx enabled=yes state=started

One thing to notice here is with the name: field. Tasks can be defined as anything you want here but should be descriptive. Tasks are simple and declarative, they aim to pass the correct arguments to the module calls, to achieve what is needed.

4 – Special Modules

There are several modules that fall into their own category, that exist to provide special core use cases. The code examples here are in the form of a task you’d find within a playbook.

  • command module – Used for executing simple commands on remote nodes. (first example shown in step one).

  1. – name: Run the command if the specified file does not exist.
  2. command: /usr/bin/ arg1 arg2 creates=/path/to/database

  • shell module – Similar to the command module but allows the use of redirection, variables, and further operators. The shell module was also used in the first step.

  1. – name: Execute the command in remote shell; stdout goes to the specified file on the remote.
  2. shell: >> somelog.txt

  • script – Let’s you run a local script on a remote node – after transferring it.

  1. – script: /some/local/ –some-arguments 1234

  • raw – Executes a low-down and dirty SSH command. Mainly used for installing Python versions onto hosts that do not already have it.

  1. – name: Bootstrap a legacy python 2.4 host
  2. raw: yum -y install python-simplejson

The examples uses Yum package manager, so is in the context of an enterprise Linux OS.

With a basic understanding of how modules work within both ad hoc commands and tasks. It’s easy to now see how the bulk of an Ansible playbooks actions are laid out.

Write A Comment