Ansible Modules¶

Introduction¶

Ansible ships with a number of modules (called the ‘module library’) that can be executed directly on remote hosts or through Playbooks. Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or handle executing system commands.

Let’s review how we execute three different modules from the command line:

ansible webservers -m service -a "name=httpd state=running"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"

Each module supports taking arguments. Nearly all modules take key=value arguments, space delimited. Some modules take no arguments, and the command/shell modules simply take the string of the command you want to run.

From playbooks, Ansible modules are executed in a very similar way:

- name: reboot the servers
  action: command /sbin/reboot -t now

All modules technically return JSON format data, though if you are using the command line or playbooks, you don’t really need to know much about that. If you’re writing your own module, you care, and this means you do not have to write modules in any particular language – you get to choose.

Modules are idempotent, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible playbooks, these modules can trigger ‘change events’ in the form of notifying ‘handlers’ to run additional tasks.

Let’s see what’s available in the Ansible module library, out of the box:

subversion¶

New in version 0.7.

This module is really simple, so for now this checks out from the given branch of a repo at a particular SHA or tag. Latest is not supported, you should not be doing that.

Export subversion repository in a specified folder

subversion repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout

Notes

Requires subversion and grep on the client.

git¶

New in version 0.0.1.

Manage git checkouts of repositories to deploy files or software.

Example git checkout from Ansible Playbooks

git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22

get_url¶

New in version 0.6.

Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource.

Example from Ansible Playbooks

get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440

Notes

This module doesn't yet support configuration for proxies or passwords.

shell¶

New in version 0.2.

The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the command module but runs the command through the user’s configured shell on the remote node.

Execute the command in remote shell

shell somescript.sh >> somelog.txt

Notes

If you want to execute a command securely and predicably, it may be better to use the command module instead. Best practices when writing playbooks will follow the trend of using command unless shell is explicitly required. When running ad-hoc commands, use your best judgement.

raw¶

Executes a low-down and dirty SSH command, not going through the module subsystem. This is useful and should only be done in two cases. The first case is installing python-simplejson on older (Python 2.4 and before) hosts that need it as a dependency to run modules, since nearly all core modules require it. Another is speaking to any devices such as routers that do not have any Python installed. In any other case, using the shell or command module is much more appropriate. Arguments given to raw are run directly through the configured remote shell and only output is returned. There is no error detection or change handler support for this module

Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host

ansible newhost.example.com -m raw -a "yum -y install python-simplejson"

pause¶

New in version 0.8.

Pauses playbook execution for a set amount of time, or until a prompt is acknowledged. All parameters are optional. The default behavior is to pause with a prompt. You can use ctrl+c if you wish to advance a pause earlier than it is set to expire or if you need to abort a playbook run entirely. To continue early: press ctrl+c and then c. To abort a playbook: press ctrl+c and then a. The pause module integrates into async/parallelized playbooks without any special considerations (see also: Rolling Updates). When using pauses with the serial playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts.

Pause for 5 minutes to build app cache.

pause minutes=5

Pause until you can verify updates to an application were successful.

pause

A helpful reminder of what to look out for post-update.

pause prompt=Make sure org.foo.FooOverload exception is not present

postgresql_db¶

New in version 0.6.

Add or remove PostgreSQL databases from a remote host.

Create a new database with name 'acme'

postgresql_db db=acme

Notes

The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.

This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.

easy_install¶

New in version 0.7.

Installs Python libraries, optionally in a virtualenv

Examples from Ansible Playbooks

easy_install name=pip

Install Flask (http://flask.pocoo.org/) into the specified virtualenv

easy_install name=flask virtualenv=/webapps/myapp/venv

Notes

Please note that the easy_install module can only install Python libraries. Thus this module is not able to remove libraries. It is generally recommended to use the pip module which you can first install using easy_install.

Also note that virtualenv must be installed on the remote host if the virtualenv parameter is specified.

user¶

New in version 0.2.

Manage user accounts and user attributes.

seboolean¶

New in version 0.7.

Toggles SELinux booleans.

Set httpd_can_network_connect SELinux flag to true and persistent

seboolean name=httpd_can_network_connect state=true persistent=yes

Notes

Not tested on any debian based system

selinux¶

New in version 0.7.

Configures the SELinux mode and policy. A reboot may be required after usage. Ansible will not issue this reboot but will let you know when it is required.

selinux policy=targeted state=enforcing

selinux policy=targeted state=disabled

Notes

Not tested on any debian based system

nagios¶

New in version 0.7.

The nagios module has two basic functions: scheduling downtime and toggling alerts for services or hosts. All actions require the host parameter to be given explicitly. In playbooks you can use the $inventory_hostname variable to refer to the host the playbook is currently running on. You can specify multiple services at once by separating them with commas, .e.g., services=httpd,nfs,puppet. When specifying what service to handle there is a special service value, host, which will handle alerts/downtime for the host itself, e.g., service=host. This keyword may not be given with other services at the same time. Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it. When using the nagios module you will need to specify your nagios server using the delegate_to parameter.

set 30 minutes of apache downtime

nagios action=downtime minutes=30 service=httpd host=$inventory_hostname

schedule an hour of HOST downtime

nagios action=downtime minutes=60 service=host host=$inventory_hostname

schedule downtime for a few services

nagios action=downtime services=frob,foobar,qeuz host=$inventory_hostname

enable SMART disk alerts

nagios action=enable_alerts service=smart host=$inventory_hostname

two services at once: disable httpd and nfs alerts

nagios action=disable_alerts service=httpd,nfs host=$inventory_hostname

disable HOST alerts

nagios action=disable_alerts service=host host=$inventory_hostname

silence ALL alerts

nagios action=silence host=$inventory_hostname

unsilence all alerts

nagios action=unsilence host=$inventory_hostname

command¶

The command module takes the command name followed by a list of space-delimited arguments. The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like $HOME and operations like "<", ">", "|", and "&" will not work. As such, all paths to commands must be fully qualified

Example from Ansible Playbooks

command /sbin/shutdown -t now

creates, removes, and chdir can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this.

command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database

Notes

If you want to run a command through the shell (say you are using <, >, |, etc), you actually want the shell module instead. The command module is much more secure as it's not affected by the user's environment.

fail¶

New in version 0.8.

This module fails the progress with a custom message. It can be useful for bailing out when a certain condition is met using only_if.

Example of how a playbook may fail when a condition is not met

[{'action': 'fail msg="The system may not be provisioned according to the CMDB status."', 'only_if': "'$cmdb_status' != 'to-be-staged'"}]

assemble¶

New in version 0.5.

Assembles a configuration file from fragments. Often a particular program will take a single configuration file and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources. Assemble will take a directory of files that have already been transferred to the system, and concatenate them together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea fragments.

Example from Ansible Playbooks

assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf

fetch¶

New in version 0.2.

This module works like copy, but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.

Example from Ansible Playbooks

fetch src=/var/log/messages dest=/home/logtree

apt¶

New in version 0.0.2.

Manages apt-packages (such as for Debian/Ubuntu).

Update repositories cache and install foo package

apt pkg=foo update-cache=yes

Remove foo package

apt pkg=foo state=removed

Install the the package foo

apt pkg=foo state=installed

Install the version '1.00' of package foo

apt pkg=foo=1.00 state=installed

Update the repository cache and update package ngnix to latest version using default release squeeze-backport

apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes

Install latest version of openjdk-6-jdk ignoring install-recomands

apt pkg=openjdk-6-jdk state=latest install-recommends=no

ohai¶

New in version 0.6.

Similar to the facter module, this runs the ohai discovery program (http://wiki.opscode.com/display/chef/Ohai) on the remote host and returns JSON inventory data. Ohai data is a bit more verbose and nested than facter.

Retrieve ohai data from all Web servers and store in one-file per host

ansible webservers -m ohai --tree=/tmp/ohaidata

ping¶

A trivial test module, this module always returns ‘pong’ on successful contact. It does not make sense in playbooks, but is useful from /usr/bin/ansible

Test 'webservers' status

ansible webservers -m ping

postgresql_user¶

New in version 0.6.

Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users access to an existing database or tables. The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. Privilege assignment, or removal, is an optional step, which works on one database at a time. This allows for the module to be called several times in the same module to modify the permissions on different databases, or to grant permissions to already existing users. A user cannot be removed untill all the privileges have been stripped from the user. In such situation, if the module tries to remove the user it will fail. To avoid this from happening the fail_on_user option signals the module to try to remove the user, but if not possible keep going; the module will report if changes happened and separately if the user was removed or not.

Create django user and grant access to database and products table

postgresql_user db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL

Remove test user privileges from acme

postgresql_user db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no

Remove test user from test database and the cluster

postgresql_user db=test user=test priv=ALL state=absent

Example privileges string format

INSERT,UPDATE/table:SELECT/anothertable:ALL

Notes

The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.

This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.

service¶

New in version 0.1.

Controls services on remote hosts.

Example action from Ansible Playbooks

service name=httpd state=started

Example action from Ansible Playbooks

service name=httpd state=stopped

Example action from Ansible Playbooks

service name=httpd state=restarted

Example action from Ansible Playbooks

service name=httpd state=reloaded

Example action from Ansible Playbooks

service name=foo pattern=/usr/bin/foo state=started

ini_file¶

New in version 0.9.

Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with, say, template or assemble. Adds missing sections if they don’t exist.

Ensure fav=lemonade is in section [drinks] in said file

ini_file dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=true

ini_file dest=/etc/anotherconf
     section=drinks
     option=temperature
     value=cold
     backup=true

Notes

While it is possible to add an option without specifying a value, this makes no sense.

template¶

Templates are processed by the Jinja2 templating language (http://jinja.pocoo.org/docs/) - documentation on the template formatting can be found in the Template Designer Documentation (http://jinja.pocoo.org/docs/templates/).

Example from Ansible Playbooks

template src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644

Notes

Since Ansible version 0.9, templates are loaded with trim_blocks=True.

mysql_user¶

New in version 0.6.

Adds or removes a user from a MySQL database.

Create database user with name 'bob' and password '12345' with all database privileges

mysql_user name=bob password=12345 priv=*.*:ALL state=present

Ensure no user named 'sally' exists, also passing in the auth credentials.

mysql_user login_user=root login_password=123456 name=sally state=absent

Example privileges string format

mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL

Notes

Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb.

Both login_password and login_username are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password.

apt_repository¶

New in version 0.7.

Manages apt repositores (such as for Debian/Ubuntu).

Add nginx stable repository from PPA

apt_repository repo=ppa://nginx/stable

Add specified repository into sources.

apt_repository repo='deb http://archive.canonical.com/ubuntu hardy partner'

Notes

This module works on Debian and Ubuntu only and requires apt-add-repository be available on destination server. To ensure this package is available use the apt module and install the python-software-properties package before using this module.

A bug in apt-add-repository always adds deb and deb-src types for repositories (see the issue on Launchpad https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories.

setup¶

This module is automatically called by playbooks to gather useful variables about remote hosts that can be used in playbooks. It can also be executed directly by /usr/bin/ansible to check what variables are available to a host. Ansible provides many facts about the system, automatically.

Obtain facts from all hosts and store them indexed by hostname at /tmp/facts.

ansible all -m setup -tree /tmp/facts

Notes

More ansible facts will be added with successive releases. If facter or ohai are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating. These variables are prefixed with facter_ and ohai_ so it's easy to tell their source. All variables are bubbled up to the caller. Using the ansible facts and choosing to not install facter and ohai means you can avoid Ruby-dependencies on your remote systems.

fireball¶

New in version 0.9.

This modules launches an ephemeral fireball ZeroMQ message bus daemon on the remote node which Ansible can to communicate with nodes at high speed. The daemon listens on a configurable port for a configurable amount of time. Starting a new fireball as a given user terminates any existing user fireballs. Fireball mode is AES encrypted

This example playbook has two plays: the first launches fireball mode on all hosts via SSH, and the second actually starts using fireball node for subsequent management over the fireball interface

- hosts: devservers
  gather_facts: false
  connection: ssh
  sudo: yes
  tasks:
      - action: fireball

- hosts: devservers
  connection: fireball
  tasks:
      - action: command /usr/bin/anything

Notes

See the advanced playbooks chapter for more about using fireball mode.

mysql_db¶

New in version 0.6.

Add or remove MySQL databases from a remote host.

Create a new database with name 'bobdata'

mysql_db db=bobdata state=present

Notes

Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb.

Both login_password and login_username are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password.

yum¶

Will install, upgrade, remove, and list packages with the yum package manager.

yum name=httpd state=latest

yum name=httpd state=removed

yum name=httpd state=installed

async_status¶

New in version 0.5.

This module gets the status of an asynchronous task. See: http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling

Notes

See http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling

virt¶

New in version 0.2.

Manages virtual machines supported by libvirt.

Example from Ansible Playbooks

virt guest=alpha state=running

Example guest management with /usr/bin/ansible

ansible host -m virt -a "guest=alpha command=status"

Notes

Other non-idempotent commands are: status, pause, unpause, get_xml, autostart, freemem, list_vms, info, nodeinfo, virttype

file¶

Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as the file module - including copy, template, and assmeble.

Example from Ansible Playbooks

file path=/etc/foo.conf owner=foo group=foo mode=0644

file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link

Notes

See also copy, template, assemble

copy¶

The copy module copies a file on the local box to remote locations.

Example from Ansible Playbooks

copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644

Copy a new ntp.conf file into place, backing up the original if it differs from the copied version

copy src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes

supervisorctl¶

New in version 0.7.

Manage the state of a program or group of programs running via Supervisord

Manage the state of program my_app to be in started state.

supervisorctl name=my_app state=started

slurp¶

This module works like fetch. It is used for fetching a base64- encoded blob containing the data in a remote file.

Example using /usr/bin/ansible

ansible host -m slurp -a 'src=/tmp/xx'
host | success >> {
   "content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=",
   "encoding": "base64"
}

Notes

See also: fetch

authorized_key¶

New in version 0.5.

Adds or removes an SSH authorized key for a user from a remote host.

Example from Ansible Playbooks

authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"

Shorthand available in Ansible 0.8 and later

authorized_key user=charlie key=$FILE(/home/charlie/.ssh/id_rsa.pub)

lineinfile¶

New in version 0.7.

This module will search a file for a line, and ensure that it is present or absent. This is primarily useful when you want to change a single line in a file only. For other cases, see the copy or template modules.

lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled

lineinfile name=/etc/sudoers state=absent regexp="^%wheel"

wait_for¶

New in version 0.7.

This is useful for when services are not immediately available after their init scripts return - which is true of certain Java application servers. It is also useful when starting guests with the virt module and needing to pause until they are ready.

Example from Ansible Playbooks

wait_for port=8000 delay=10

facter¶

New in version 0.2.

Runs the facter discovery program (https://github.com/puppetlabs/facter) on the remote system, returning JSON data that can be useful for inventory purposes.

Example command-line invocation

ansible  www.example.net -m facter

group¶

New in version 0.0.2.

Manage presence of groups on a host.

Example group command from Ansible Playbooks

group name=somegroup state=present

pip¶

New in version 0.7.

Manage Python library dependencies.

Install flask python package.

pip name=flask

Install flask python package on version 0.8.

pip name=flask version=0.8

Install Flask (http://flask.pocoo.org/) into the specified virtualenv

pip name=flask virtualenv=/srv/webapps/my_app/venv

Install specified python requirements.

pip requirements=/srv/webapps/my_app/src/requirements.txt

Install specified python requirements in indicated virtualenv.

pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv

Notes

Please note that http://www.virtualenv.org/, virtualenv must be installed on the remote host if the virtualenv parameter is specified.

mount¶

New in version 0.6.

This module controls active and configured mount points in /etc/fstab.

Mount DVD read-only

mount name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro

Additional Contrib Modules¶

In addition to the following built-in modules, community modules are available at Ansible Resources.

Writing your own modules¶

See Module Development.