Ansible Modules¶

cloudformation¶

New in version 1.1.

Launches an AWS CloudFormation stack and waits for it complete.

parameter	required	default	choices	comments
disable_rollback	no	no	yes no	If a stacks fails to form, rollback will remove the stack
region	yes			The AWS region the stack will be launched in
stack_name	yes			name of the cloudformation stack
state	yes			If state is "present", stack will be created. If state is "present" and if stack exists and template has changed, it will be updated. If state is absent, stack will be removed.
template	yes			the path of the cloudformation template
template_parameters	yes			a list of hashes of all the template variables for the stack
wait_for	no	yes	yes no	Wait while the stack is being created/updated/deleted.

Requirements: boto

  # Basic task example
  tasks:
  - name: launch ansible cloudformation example
    action: cloudformation >
      stack_name="ansible-cloudformation" state=present
      region=us-east-1 disable_rollback=yes
      template=files/cloudformation-example.json
    args:
      template_parameters:
        KeyName: jmartin
        DiskType: ephemeral
        InstanceType: m1.small
        ClusterSize: 3

ec2¶

New in version 0.9.

creates ec2 instances and optionally waits for it to be ‘running’. This module has a dependency on python-boto >= 2.5

parameter	required	default	choices	comments
count	no	1		number of instances to launch
ec2_access_key	no			ec2 access key
ec2_secret_key	no			ec2 secret key
ec2_url	no			url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints)
group	no			security group to use with the instance
group_id	no			security group id to use with the instance (added in Ansible 1.1)
id	no			identifier for this instance or set of instances, so that the module will be idempotent with respect to EC2 instances.
image	yes			emi (or ami) to use for the instance
instance_tags	no			a hash/dictionary of tags to add to the new instance; '{"key":"value"}' and '{"key":"value","key":"value"}' (added in Ansible 1.0)
instance_type	yes			instance type to use for the instance
kernel	no			kernel eki to use for the instance
key_name	yes			key pair to use on the instance
monitor	no			enable detailed monitoring (CloudWatch) for instance (added in Ansible 1.1)
private_ip	no			the private ip address to assign the instance (from the vpc subnet) (added in Ansible 1.2)
ramdisk	no			ramdisk eri to use for the instance
region	no			the EC2 region to use (added in Ansible 1.2)
user_data	no			opaque blob of data which is made available to the ec2 instance (added in Ansible 0.9)
vpc_subnet_id	no			the subnet ID in which to launch the instance (VPC) (added in Ansible 1.1)
wait	no	no	yes no	wait for the instance to be in state 'running' before returning
wait_timeout	no	300		how long before wait gives up, in seconds
zone	no			availability zone in which to launch the instance (added in Ansible 1.2)

Requirements: boto

# Basic provisioning example
local_action:
    module: ec2
    keypair: mykey
    instance_type: c1.medium
    image: emi-40603AD1
    wait: yes
    group: webserver
    count: 3

# Advanced example with tagging and CloudWatch
local_action:
    module: ec2
    keypair: mykey
    group: databases
    instance_type: m1.large
    image: ami-6e649707
    wait: yes
    wait_timeout: 500
    count: 5
    instance_tags: '{"db":"postgres"}' monitoring=true'

# VPC example
local_action:
    module: ec2
    keypair: mykey
    group_id: sg-1dc53f72
    instance_type: m1.small
    image: ami-6e649707
    wait: yes
    vpc_subnet_id: subnet-29e63245'

ec2_elb¶

New in version 1.2.

This module de-registers or registers an AWS EC2 instance from the EL**s** that it belongs to. Returns fact “ec2_elbs” which is a list of elbs attached to the instance if state=absent is passed as an argument. Will be marked changed when called only if there are ELBs found to operate on.

parameter	required	default	choices	comments
ec2_access_key	no	None		AWS Access API key
ec2_elbs	no	None		List of ELB names, required for registration. The ec2_elbs fact should be used if there was a previous de-register.
ec2_secret_key	no	None		AWS Secret API key
instance_id	yes			EC2 Instance ID
state	yes			register or deregister the instance

Requirements: boto

# basic pre_task and post_task example
pre_tasks:
  - name: Gathering ec2 facts
    ec2_facts:
  - name: Instance De-register
    local_action: ec2_elb
    args:
      instance_id: "{{ ansible_ec2_instance_id }}"
      state: 'absent'
roles:
  - myrole
post_tasks:
  - name: Instance Register
    local_action: ec2_elb
    args:
      instance_id: "{{ ansible_ec2_instance_id }}"
      ec2_elbs: "{{ ec2_elbs }}"
      state: 'present'

ec2_facts¶

New in version 1.0.

This module fetches data from the metadata servers in ec2 (aws). Eucalyptus cloud provides a similar service and this module should work this cloud provider as well.

Obtain facts from ec2 metatdata servers. You will need to run an instance within ec2.

ansible all -m ec2_facts

Notes

Parameters to filter on ec2_facts may be added later.

ec2_vol¶

New in version 1.1.

creates an EBS volume and optionally attaches it to an instance. If both an instance ID and a device name is given and the instance has a device at the device name, then no volume is created and no attachment is made. This module has a dependency on python-boto.

parameter	required	default	choices	comments
device_name	no			device id to override device mapping. Assumes /dev/sdf for Linux/UNIX and /dev/xvdf for Windows.
instance	no			instance ID if you wish to attach the volume.
region	no			region in which to create the volume
volume_size	yes			size of volume (in GB) to create.
zone	no			zone in which to create the volume, if unset uses the zone the instance is in (if set)

Requirements: boto

# Simple attachment action
local_action:
    module: ec2_vol
    instance: XXXXXX
    volume_size: 5
    device_name: sdd

# Playbook example combined with instance launch
local_action:
    module: ec2
    keypair: $keypair
    image: $image
    wait: yes
    count: 3
    register: ec2
local_action:
    module: ec2_vol
    instance: ${item.id}
    volume_size: 5
    with_items: ${ec2.instances}
    register: ec2_vol

rax¶

New in version 1.2.

creates / deletes Rackspace Public Cloud instances and optionally waits for it to be ‘running’.

parameter	required	default	choices	comments
creds_file	no			File to find the Rackspace Public Cloud credentials in
files	no			Files to insert into the instance. remotefilename:localcontent
flavor	no			flavor to use for the instance
image	no			image to use for the instance
key_name	no			key pair to use on the instance
meta	no			A hash of metadata to associate with the instance
name	no			Name to give the instance
region	no			Region to create an instance in
service	no	cloudservers	cloudservers	Cloud service to interact with
state	no	present	present active absent deleted	Indicate desired state of the resource
wait	no	no	yes no	wait for the instance to be in state 'running' before returning
wait_timeout	no	300		how long before wait gives up, in seconds

Requirements: pyrax

Example from Ansible Playbooks

- name: Create a server
  local_action:
    module: rax
    creds_file: ~/.raxpub
    service: cloudservers
    name: rax-test1
    flavor: 5
    image: b11d9567-e412-4255-96b9-bd63ab23bcfe
    wait: yes
    state: present

Notes

Two environment variables can be used, RAX_CREDS and RAX_REGION.

RAX_CREDS points to a credentials file appropriate for pyrax

RAX_REGION defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)

s3¶

New in version 1.1.

This module allows the user to dictate the presence of a given file in an S3 bucket. If or once the key (file) exists in the bucket, it returns a time-expired download url. This module has a dependency on python-boto.

parameter	required	default	choices	comments
bucket	yes			bucket you wish to present/absent for the key (file in path).
dest	no			the destination in s3, if different from path
expiry	no	600		expiry period (in seconds) for returned download URL.
overwrite	no			force overwrite if a file with the same name already exists, values true/false/yes/no. Does not support files uploaded to s3 with multipart upload. (added in Ansible 1.2)
path	no			path to the key (file) which you wish to be present/absent in the bucket.
state	no			desired state for both bucket and file.

Requirements: boto

# Simple PUT operation
   module: s3
   bucket: mybucket
   path: /path/to/file
   state: present
# Force and overwrite if checksums don't match
   module: s3
   bucket: mybucket
   path: /path/to/file
   state: present
   overwrite: yes

virt¶

New in version 0.2.

Manages virtual machines supported by libvirt.

parameter	required	default	choices	comments
command	no		create status start stop pause unpause shutdown undefine destroy get_xml autostart freemem list_vms info nodeinfo virttype define	in addition to state management, various non-idempotent commands are available. See examples
name	yes			name of the guest VM being managed. Note that VM must be previously defined with xml.
state	no	no	running shutdown	Note that there may be some lag for state requests like shutdown since these refer only to VM states. After starting a guest, it may not be immediately accessible.
uri	no			libvirt connection uri
xml	no			XML document used with the define command

Requirements: libvirt

# a playbook task line:
tasks:
  - virt: name=alpha state=running

# /usr/bin/ansible invocations
ansible host -m virt -a "name=alpha command=status"
ansible host -m virt -a "name=alpha command=get_xml"
ansible host -m virt -a "name=alpha command=create uri=lxc:///"

# a playbook example of defining and launching an LXC guest
tasks:
  - name: define vm
    virt: name=foo command=define xml="{{ lookup('template', 'container-template.xml.j2') }}" uri=lxc:///
  - name: start vm
    virt: name=foo state=running uri=lxc:///

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

parameter	required	default	choices	comments
chdir	no			cd into this directory before running the command (added in Ansible 0.6)
creates	no			a filename, when it already exists, this step will not be run.
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 0.9)
free_form	yes			the command module takes a free form command to run
removes	no			a filename, when it does not exist, this step will not be run. (added in Ansible 0.8)

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.

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. Standard output, error output and return code are returned when available. There is no change handler support for this module. This module does not require python on the remote system, much like the script module.

parameter	required	default	choices	comments
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 1.0)
free_form	yes			the raw module takes a free form command to run

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

action: raw yum -y install python-simplejson

Notes

If you want to execute a command securely and predictably, 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.

script¶

The script module takes the script name followed by a list of space-delimited arguments. The pathed local script will be transfered to the remote node and then executed. The given script will be processed through the shell environment on the remote node. This module does not require python on the remote system, much like the raw module.

parameter	required	default	choices	comments
free_form	yes			path to the local script file followed by optional arguments.

Example from Ansible Playbooks

action: script /some/local/script.sh --some-arguments 1234

Notes

It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!

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 a shell (/bin/sh) on the remote node.

parameter	required	default	choices	comments
(free form)	no			The command module takes a free form command to run
chdir	no			cd into this directory before running the command (added in Ansible 0.6)
creates	no			a filename, when it already exists, this step will NOT be run
executable	no			change the shell used to execute the command. Should be an absolute path to the executable. (added in Ansible 0.9)

Execute the command in remote shell

shell: somescript.sh >> somelog.txt

Notes

If you want to execute a command securely and predictably, 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.

mongodb_user¶

New in version 1.1.

Adds or removes a user from a MongoDB database.

parameter	required	default	choices	comments
database	yes			The name of the database to add/remove the user from
login_host	no	localhost		The host running the database
login_password	no			The password used to authenticate with
login_port	no	27017		The port to connect to
login_user	no			The username used to authenticate with
password	no			The password to use for the user
state	no	present	present absent	The database user state
user	yes			The name of the user to add or remove

Requirements: pymongo

Create 'burgers' database user with name 'bob' and password '12345'.

mongodb_user: database=burgers name=bob password=12345 state=present

Delete 'burgers' database user with name 'bob'.

mongodb_user: database=burgers name=bob state=absent

Notes

Requires the pymongo Python package on the remote host, version 2.4.2+. This can be installed using pip or the OS package manager. @see http://api.mongodb.org/python/current/installation.html

mysql_db¶

New in version 0.6.

Add or remove MySQL databases from a remote host.

parameter	required	default	choices	comments
collation	no			Collation mode
encoding	no			Encoding mode
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_unix_socket	no			The path to a Unix domain socket for local connections
login_user	no			The username used to authenticate with
name	yes			name of the database to add or remove
state	no	present	present absent dump import	The database state
target	no			Where to dump/get the .sql file

Requirements: ConfigParser

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. (See apt.)

Both login_password and login_user 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.

mysql_user¶

New in version 0.6.

Adds or removes a user from a MySQL database.

parameter	required	default	choices	comments
host	no	localhost		the 'host' part of the MySQL username
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_unix_socket	no			The path to a Unix domain socket for local connections
login_user	no			The username used to authenticate with
name	yes			name of the user (role) to add or remove
password	no			set the user's password
priv	no			MySQL privileges string in the format: db.table:priv1,priv2
state	no	present	present absent	The database state

Requirements: ConfigParser MySQLdb

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

Example using login_unix_socket to connect to server

mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock

# Example .my.cnf file for setting the root password
# Note: don't use quotes around the password, because the mysql_user module
# will include them in the password but the mysql client will not
[client]
user=root
password=n<_665{vS43y

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.

MySQL server installs with default login_user of 'root' and no password. To secure this user as part of an idempotent playbook, you must create at least two tasks: the first must change the root user's password, without providing any login_user/login_password details. The second must drop a ~/.my.cnf file containing the new root credentials. Subsequent runs of the playbook will then succeed by reading the new credentials from the file.

postgresql_db¶

New in version 0.6.

Add or remove PostgreSQL databases from a remote host.

parameter	required	default	choices	comments
encoding	no			Encoding of the database
lc_collate	no			Collation order (LC_COLLATE) to use in the database. Must match collation order of template database unless template0 is used as template.
lc_ctype	no			Character classification (LC_CTYPE) to use in the database (e.g. lower, upper, ...) Must match LC_CTYPE of template database unless template0 is used as template.
login_host	no	localhost		Host running the database
login_password	no			The password used to authenticate with
login_user	no			The username used to authenticate with
name	yes			name of the database to add or remove
owner	no			Name of the role to set as owner of the database
state	no	present	present absent	The database state
template	no			Template used to create the database

Requirements: psycopg2

Create a new database with name acme

postgresql_db: db=acme

Create a new database with name acme and specific encoding and locale settings. If a template different from template0 is specified, encoding and locale settings must match those of the template.

postgresql_db: db=acme encoding='UTF-8' lc_collate='de_DE.UTF-8' lc_ctype='de_DE.UTF-8' template='template0'

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.

postgresql_privs¶

Grant or revoke privileges on PostgreSQL database objects. This module is basically a wrapper around most of the functionality of PostgreSQL’s GRANT and REVOKE statements with detection of changes (GRANT/REVOKE privs ON type objs TO/FROM roles)

parameter	required	default	choices	comments
database	yes			Name of database to connect to.Alias: db
grant_option	no		True False	Whether role may grant/revoke the specified privileges/group memberships to others.Set to no to revoke GRANT OPTION, leave unspecified to make no changes.grant_option only has an effect if state is present.Alias: admin_option
host	no			Database host address. If unspecified, connect via Unix socket.Alias: login_host
login	no	postgres		The username to authenticate with.Alias: login_user
objs	no			Comma separated list of database objects to set privileges on.If type is table or sequence, the special value ALL_IN_SCHEMA can be provided instead to specify all database objects of type type in the schema specified via schema. (This also works with PostgreSQL < 9.0.)If type is database, this parameter can be omitted, in which case privileges are set for the database specified via database.If type is function, colons (":") in object names will be replaced with commas (needed to specify function signatures, see examples)Alias: obj
password	no			The password to authenticate with.Alias: login_password)
port	no	5432		Database port to connect to.
privs	no			Comma separated list of privileges to grant/revoke.Alias: priv
roles	yes			Comma separated list of role (user/group) names to set permissions for.The special value PUBLIC can be provided instead to set permissions for the implicitly defined PUBLIC group.Alias: role
schema	no			Schema that contains the database objects specified via objs.May only be provided if type is table, sequence or function. Defaults to public in these cases.
state	no	present	present absent	If present, the specified privileges are granted, if absent they are revoked.
type	no	table	table sequence function database schema language tablespace group	Type of database object to set privileges on.

Requirements: psycopg2

# On database "library":
# GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors
# TO librarian, reader WITH GRANT OPTION
postgresql_privs: >
    database=library
    state=present
    privs=SELECT,INSERT,UPDATE
    type=table
    objs=books,authors
    schema=public
    roles=librarian,reader
    grant_option=yes

# Same as above leveraging default values:
postgresql_privs: >
    db=library
    privs=SELECT,INSERT,UPDATE
    objs=books,authors
    roles=librarian,reader
    grant_option=yes

# REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader
# Note that role "reader" will be *granted* INSERT privilege itself if this
# isn't already the case (since state=present).
postgresql_privs: >
    db=library
    state=present
    priv=INSERT
    obj=books
    role=reader
    grant_option=no

# REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader
# "public" is the default schema. This also works for PostgreSQL 8.x.
postgresql_privs: >
    db=library
    state=absent
    privs=INSERT,UPDATE
    objs=ALL_IN_SCHEMA
    role=reader

# GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian
postgresql_privs: >
    db=library
    privs=ALL
    type=schema
    objs=public,math
    role=librarian

# GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader
# Note the separation of arguments with colons.
postgresql_privs: >
    db=library
    privs=ALL
    type=function
    obj=add(int:int)
    schema=math
    roles=librarian,reader

# GRANT librarian, reader TO alice, bob WITH ADMIN OPTION
# Note that group role memberships apply cluster-wide and therefore are not
# restricted to database "library" here.
postgresql_privs: >
    db=library
    type=group
    objs=librarian,reader
    roles=alice,bob
    admin_option=yes

# GRANT ALL PRIVILEGES ON DATABASE library TO librarian
# Note that here "db=postgres" specifies the database to connect to, not the
# database to grant privileges on (which is specified via the "objs" param)
postgresql_privs: >
    db=postgres
    privs=ALL
    type=database
    obj=library
    role=librarian

# GRANT ALL PRIVILEGES ON DATABASE library TO librarian
# If objs is omitted for type "database", it defaults to the database
# to which the connection is established
postgresql_privs: >
    db=library
    privs=ALL
    type=database
    role=librarian

Notes

Default authentication assumes that postgresql_privs is run by the postgres user on the remote host. (Ansible's user or sudo-user).

This module requires Python package psycopg2 to be installed on the remote host. In the default case of the remote host also being the PostgreSQL server, PostgreSQL has to be installed there as well, obviously. For Debian/Ubuntu-based systems, install packages postgresql and python-psycopg2.

Parameters that accept comma separated lists (privs, objs, roles) have singular alias names (priv, obj, role).

To revoke only GRANT OPTION for a specific object, set state to present and grant_option to no (see examples).

Note that when revoking privileges from a role R, this role may still have access via privileges granted to any role R is a member of including PUBLIC.

Note that when revoking privileges from a role R, you do so as the user specified via login. If R has been granted the same privileges by another user also, R can still access database objects via these privileges.

When revoking privileges, RESTRICT is assumed (see PostgreSQL docs).

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 until 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.

parameter	required	default	choices	comments
db	no			name of database where permissions will be granted
fail_on_user	no	True	yes no	if yes, fail when user can't be removed. Otherwise just log and continue
login_host	no	localhost		Host running PostgreSQL.
login_password	no			Password used to authenticate with PostgreSQL
login_user	no	postgres		User (role) used to authenticate with PostgreSQL
name	yes			name of the user (role) to add or remove
password	yes			set the user's password
priv	no			PostgreSQL privileges string in the format: table:priv1,priv2
role_attr_flags	no		[NO]SUPERUSER [NO]CREATEROLE [NO]CREATEUSER [NO]CREATEDB [NO]INHERIT [NO]LOGIN [NO]REPLICATION	PostgreSQL role attributes string in the format: CREATEDB,CREATEROLE,SUPERUSER
state	no	present	present absent	The user (role) state

Requirements: psycopg2

Create django user and grant access to database and products table

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

Create rails user, grant privilege to create other databases and demote rails from super user status

postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER

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.

If you specify PUBLIC as the user, then the privilege changes will apply to all users. You may not specify password or role_attr_flags when the PUBLIC user is specified.

riak¶

New in version 1.2.

This module can be used to join nodes to a cluster, check the status of the cluster.

parameter	required	default	choices	comments
command	no		ping kv_test join plan commit	The command you would like to perform against the cluster.
config_dir	no	/etc/riak		The path to the riak configuration directory
http_conn	no	127.0.0.1:8098		The ip address and port that is listening for Riak HTTP queries
target_node	no	[email protected]		The target node for certain operations (join, ping)
wait_for_handoffs	no			Waits for handoffs to complete before continuing. This can take awhile and should generally be used with async mode.
wait_for_ring	no			Waits for all nodes to agree on the status of the ring
wait_for_service	no	kv	kv	Waits for a riak service to come online before continuing.

Join's a Riak node to another node

riak: command=join target_node=[email protected]

Wait for handoffs to finish. Use with async and poll.

riak: wait_for_handoffs=true

Wait for riak_kv service to startup

riak: wait_for_service=kv

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.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file (if yes), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			A file to create using the concatenation of all of the source files.
others	no			all arguments accepted by the file module also work here
src	yes			An already existing directory full of source files.

Example from Ansible Playbooks

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

copy¶

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

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. (added in Ansible 0.7)
content	no			When used instead of 'src', sets the contents of a file directly to the specified value. (added in Ansible 1.1)
dest	yes			Remote absolute path where the file should be copied to.
force	no	yes	yes no	the default is yes, which will replace the remote file when contents are different than the source. If no, the file will only be transferred if the destination does not exist. (added in Ansible 1.1)
others	no			all arguments accepted by the file module also work here
src	no			Local path to a file to copy to the remote server; can be absolute or relative.
validate	no			validation to run before copying into place (added in Ansible 1.2)

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

Copy a new sudoers file into place, after passing validation with visudo

copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'

Notes

The "copy" module can't be used to recursively copy directory structures to the target machine. Please see the "Delegation" section of the Advanced Playbooks documentation for a better approach to recursive copies.

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 assemble.

parameter	required	default	choices	comments
context	no		default	accepts only default as value. This will restore a file's SELinux context in the policy. Does nothing if no default value is available.
group	no			name of the group that should own the file/directory, as would be fed to chown
mode	no			mode the file or directory should be, such as 0644 as would be fed to chmod
owner	no			name of the user that should own the file/directory, as would be fed to chown
path	yes			defines the file being managed, unless when used with state=link, and then sets the destination to create a symbolic link to using src
recurse	no	no	yes no	recursively set the specified file attributes (applies only to state=directory) (added in Ansible 1.1)
selevel	no	s0		level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the range. _default feature works as for seuser.
serole	no			role part of SELinux file context, _default feature works as for seuser.
setype	no			type part of SELinux file context, _default feature works as for seuser.
seuser	no			user part of SELinux file context. Will default to system policy, if applicable. If set to _default, it will use the user portion of the policy if available
src	no			path of the file to link to (applies only to state=link).
state	no	file	file link directory absent	If directory, all immediate subdirectories will be created if they do not exist. If file, the file will NOT be created if it does not exist, see the copy or template module if you want that behavior. If link, the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.

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

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.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			Path to the INI-style file; this file is created if required
option	no			if set (required for changing a value), this is the name of the option.May be omitted if adding/removing a whole section.
others	no			all arguments accepted by the file module also work here
section	yes			Section name in INI file. This is added if state=present automatically when a single value is being set.
value	no			the string value to be associated with an option. May be omitted when removing an option.

Requirements: ConfigParser

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

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

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

Notes

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

A section named default cannot be added by the module, but if it exists, individual options within the section can be updated. (This is a limitation of Python's ConfigParser.) Either use template to create a base INI file with a [default] section, or use lineinfile to add the missing line.

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.

parameter	required	default	choices	comments
backrefs	no	no	yes no	Used with state=present. If set, line can contain backreferences (both positional and named) that will get populated if the regexp matches. This flag changes the operation of the module slightly; insertbefore and insertafter will be ignored, and if the regexp doesn't match anywhere in the file, the file will be left unchanged. If the regexp does match, the last matching line will be replaced by the expanded line parameter. (added in Ansible 1.1)
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
create	no	no	yes no	Used with state=present. If specified, the file will be created if it does not already exist. By default it will fail if the file is missing.
dest	yes			The file to modify.
insertafter	no	EOF	EOF *regex*	Used with state=present. If specified, the line will be inserted after the specified regular expression. A special value is available; EOF for inserting the line at the end of the file. May not be used with backrefs.
insertbefore	no		BOF *regex*	Used with state=present. If specified, the line will be inserted before the specified regular expression. A value is available; BOF for inserting the line at the beginning of the file. May not be used with backrefs. (added in Ansible 1.1)
line	no			Required for state=present. The line to insert/replace into the file. If backrefs is set, may contain backreferences that will get expanded with the regexp capture groups if the regexp matches. The backreferences should be double escaped (see examples).
others	no			All arguments accepted by the file module also work here.
regexp	yes			The regular expression to look for in every line of the file. For state=present, the pattern to replace if found; only the last line found will be replaced. For state=absent, the pattern of the line to remove. Uses Python regular expressions; see http://docs.python.org/2/library/re.html.
state	no	present	present absent	Whether the line should be there or not.

   lineinfile: dest=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled

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

   lineinfile: dest=/etc/host regexp='^127\.0\.0\.1' line='127.0.0.1 localhost' owner=root group=root mode=0644

   lineinfile: dest=/etc/httpd/conf/httpd.conf regexp="^Listen " insertafter="^#Listen " line="Listen 8080"

   lineinfile: dest=/etc/services regexp="^# port for http" insertbefore="^www.*80/tcp" line="# port for http by default"

   lineinfile: dest=/etc/sudoers state=present regexp='^%wheel' line='%wheel ALL=(ALL) NOPASSWD: ALL'

   lineinfile: dest=/opt/jboss-as/bin/standalone.conf regexp='^(.*)Xms(\d+)m(.*)$' line='\\1Xms${xms}m\\3' backrefs=yes

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/). Six additional variables can be used in templates: ansible_managed (configurable via the defaults section of ansible.cfg) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid, template_host contains the node name of the template’s machine, template_uid the owner, template_path the relative path of the template, template_fullpath is the absolute path of the template, and template_run_date is the date that the template was rendered.

parameter	required	default	choices	comments
backup	no	no	yes no	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
dest	yes			Location to render the template to on the remote machine.
others	no			all arguments accepted by the file module also work here
src	yes			Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path.
validate	no			validation to run before copying into place (added in Ansible 1.2)

Example from Ansible Playbooks

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

Copy a new sudoers file into place, after passing validation with visudo

action: template src=/mine/sudoers dest=/etc/sudoers validate='visudo -c %s'

Notes

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

You can override jinja2 settings by adding a special header to template file. i.e. c(#jinja2: trim_blocks: False)

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

parameter	required	default	choices	comments
jid	yes			Job or task identifier
mode	no	status	status cleanup	if status, obtain the status; if cleanup, clean up the async job cache located in ~/.ansible_async/ for the specified job jid.

Notes

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

add_host¶

New in version 0.9.

Use variables to create new hosts and groups in inventory for use in later plays of the same playbook. Takes variables so you can define the new hosts more fully.

parameter	required	default	choices	comments
groups	no			The groups to add the hostname to, comma separated.
name	yes			The hostname/ip of the host to add to the inventory, can include a colon and a port number.

add host to group 'just_created' with variable foo=42

add_host hostname=${ip_from_ec2} groups=just_created foo=42

add a host with a non-standard port local to your machines

add_host hostname='${new_ip}:${new_port}'

add a host alias that we reach through a tunnel

add_host hostname=${new_ip} ansible_ssh_host=${inventory_hostname} ansible_ssh_port=${new_port}'

group_by¶

New in version 0.9.

Use facts to create ad-hoc groups that can be used later in a playbook.

parameter	required	default	choices	comments
key	yes			The variables whose values will be used as groups

Create groups based on the machine architecture

group_by key=${ansible_machine}

Create groups like 'kvm-host'

group_by key=${ansible_virtualization_type}-${ansible_virtualization_role}

Notes

Spaces in group names are converted to dashes '-'.

rabbitmq_parameter¶

New in version 1.1.

Manage dynamic, cluster-wide parameters for RabbitMQ

parameter	required	default	choices	comments
component	yes			Name of the component of which the parameter is being set
name	yes			Name of the parameter being set
state	no	present	present absent	Specify if user is to be added or removed
value	no			Value of the parameter, as a JSON term
vhost	no	/		vhost to apply access privileges.

# Set the federation parameter 'local_username' to a value of 'guest' (in quotes)
rabbitmq_parameter: component=federation name=local-username value='"guest"' state=present

rabbitmq_plugin¶

New in version 1.1.

Enables or disables RabbitMQ plugins

parameter	required	default	choices	comments
names	yes			Comma-separated list of plugin names
new_only	no	no	yes no	Only enable missing pluginsDoes not disable plugins that are not in the names list
state	no	enabled	enabled disabled	Specify if pluginss are to be enabled or disabled

Enables the rabbitmq_management plugin

rabbitmq_plugin names=rabbitmq_management state=enabled

rabbitmq_user¶

New in version 1.1.

Add or remove users to RabbitMQ and assign permissions

parameter	required	default	choices	comments
configure_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.
force	no	no	yes no	Deletes and recreates the user.
password	no			Password of user to add
read_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.
state	no	present	present absent	Specify if user is to be added or removed
tags	no			User tags specified as comma delimited
user	yes			Name of user to add
vhost	no	/		vhost to apply access privileges.
write_priv	no	^$		Regular expression to restrict configure actions on a resource for the specified vhost.By default all actions are restricted.

Add user to server and assign full access control

rabbitmq_user user=joe password=changeme vhost=/ configure_priv=.* read_priv=.* write_priv=.* state=present

rabbitmq_vhost¶

New in version 1.1.

Manage the state of a virtual host in RabbitMQ

parameter	required	default	choices	comments
name	yes			The name of the vhost to manage
state	no	present	present absent	The state of vhost
tracing	no	no	yes no	Enable/disable tracing for a vhost

Ensure that the vhost /test exists.

rabbitmq_vhost: name=/test state=present

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. To schedule downtime for all services on particular host use keyword “all”, e.g., service=all. When using the nagios module you will need to specify your Nagios server using the delegate_to parameter.

parameter	required	default	choices	comments
action	yes		downtime enable_alerts disable_alerts silence unsilence silence_nagios unsilence_nagios command	Action to take.
author	no	Ansible		Author to leave downtime comments as. Only usable with the downtime action.
cmdfile	no	auto-detected		Path to the nagios command file (FIFO pipe). Only required if auto-detection fails.
command	yes			The raw command to send to nagios, which should not include the submitted time header or the line-feed Required option when using the command action.
host	no			Host to operate on in Nagios.
minutes	no	30		Minutes to schedule downtime for.Only usable with the downtime action.
services	yes			What to manage downtime/alerts for. Separate multiple services with commas. service is an alias for services. Required option when using the downtime, enable_alerts, and disable_alerts actions.

Requirements: Nagios

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 ALL services on HOST

nagios: action=downtime minutes=45 service=all 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

SHUT UP NAGIOS

nagios: action=silence_nagios

ANNOY ME NAGIOS

nagios: action=unsilence_nagios

command something

nagios: action=command command='DISABLE_FAILURE_PREDICTION'

newrelic_deployment¶

New in version 1.2.

Notify newrelic about app deployments (see http://newrelic.github.io/newrelic_api/NewRelicApi/Deployment.html)

parameter	required	default	choices	comments
app_name	no			(one of app_name or application_id are required) The value of app_name in the newrelic.yml file used by the application
application_id	no			(one of app_name or application_id are required) The application id, found in the URL when viewing the application in RPM
appname	no			Name of the application
changelog	no			A list of changes for this deployment
description	no			Text annotation for the deployment - notes for you
environment	no			The environment for this deployment
revision	no			A revision number (e.g., git commit SHA)
token	yes			API token.
user	no			The name of the user/process that triggered this deployment

Requirements: urllib urllib2

action: newrelic_deployment token=AAAAAA app_name=myapp user='ansible deployment' revision=1.0

bigip_pool¶

New in version 1.2.

Manages F5 BIG-IP LTM pool members via iControl SOAP API

parameter	required	default	choices	comments
host	yes			BIG-IP pool member
name	yes			BIG-IP pool name
partition	no	Common		BIG-IP partition
password	yes			BIG-IP password
port	yes			BIG-IP pool member port
server	yes			BIG-IP host
state	no	present	present absent	Pool member state
user	yes			BIG-IP username

Requirements: bigsuds

### Examples assume [localhost] is defined in inventory file

## ad-hoc ansible CLI example

# ensures 1.1.1.1:80 is present in pool /matthite/matthite-pool on load balancer lb.mydomain.com
ansible -c local localhost -m bigip_pool -a "server=lb.mydomain.com user=admin password=mysecret state=present name=matthite-pool partition=matthite host=1.1.1.1 port=80"

# ensures 1.1.1.1:80 is absent from pool /matthite/matthite-pool on load balancer lb.mydomain.com
ansible -c local localhost -m bigip_pool -a "server=lb.mydomain.com user=admin password=mysecret state=absent name=matthite-pool partition=matthite host=1.1.1.1 port=80"

## playbook task example:

---
# file bigip-test.yml
# ...
  tasks:
  - name: Register current node to load balancer pool
    local_action: bigip_pool server=lb.mydomain.com user=admin password=mysecret state=present name=matthite-pool partition=matthite host={{ ansible_default_ipv4.address }} port=80

Notes

Requires BIG-IP software version >= 11

F5 developed module 'bigsuds' required (see http://devcentral.f5.com)

Best run as a local_action in your playbook

If pool member IP address is no longer referenced by another pool when running with state=absent, the node IP will also be deleted from the F5 configuration.

netscaler¶

New in version 1.1.

Manages Citrix NetScaler server and service entities.

parameter	required	default	choices	comments
action	no	disable	enable disable	the action you want to perform on the entity
name	yes	hostname		name of the entity
nsc_host	yes			hostname or ip of your netscaler
nsc_protocol	no	https		protocol used to access netscaler
password	yes			password
type	no	server	server service	type of the entity
user	yes			username

Requirements: urllib urllib2

Disable the server

ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass"

Enable the server

ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass action=enable"

Disable the service local:8080

ansible host -m netscaler -a "nsc_host=nsc.example.com user=apiuser password=apipass name=local:8080 type=service action=disable"

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. Note that this module is written to transfer log files that might not be present, so a missing remote file won’t be an error unless fail_on_missing is set to ‘yes’.

parameter	required	default	choices	comments
dest	yes			A directory to save the file into. For example, if the dest directory is /backup a src file named /etc/profile on host host.example.com, would be saved into /backup/host.example.com/etc/profile
fail_on_missing	no	no	yes no	Makes it fails when the source file is missing. (added in Ansible 1.1)
src	yes			The file on the remote system to fetch. This must be a file, not a directory. Recursive fetching may be supported in a later release.

Example from Ansible Playbooks

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

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. By default, if an environment variable <protocol>_proxy is set on the target host, requests will be sent through that proxy. This behaviour can be overriden by setting a variable for this task (see setting the environment), or by using the use_proxy option.

parameter	required	default	choices	comments
dest	yes			absolute path of where to download the file to.If dest is a directory, the basename of the file on the remote server will be used. If a directory, force=yes must also be set.
force	no	no	yes no	if yes, will download the file every time and replace the file if the contents change. If no, the file will only be downloaded if the destination does not exist. Generally should be yes only for small local files. prior to 0.6, acts if yes by default. (added in Ansible 0.7)
others	no			all arguments accepted by the file module also work here
url	yes			HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
use_proxy	no	True	True False	if no, it will not use a proxy, even if one is defined by in an environment variable on the target hosts.

Requirements: urllib2 urlparse

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.

slurp¶

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

parameter	required	default	choices	comments
src	yes			The file on the remote system to fetch. This must be a file, not a directory.

Example using /usr/bin/ansible

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

Notes

See also: fetch

uri¶

New in version 1.1.

Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.

parameter	required	default	choices	comments
HEADER_	no			Any parameter starting with "HEADER_" is a sent with your request as a header. For example, HEADER_Content-Type="application/json" would send the header "Content-Type" along with your request with a value of "application/json".
body	no			The body of the http request/response to the web service.
creates	no			a filename, when it already exists, this step will not be run.
dest	no			path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used.
follow_redirects	no	no	yes no	Whether or not the URI module should follow all redirects.
force_basic_auth	no	no	yes no	httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the sending of the Basic authentication header upon initial request.
method	no	GET	GET POST PUT HEAD DELETE OPTIONS	The HTTP method of the request or response.
others	no			all arguments accepted by the file module also work here
password	no			password for the module to use for Digest, Basic or WSSE authentication.
removes	no			a filename, when it does not exist, this step will not be run.
return_content	no	no	yes no	Whether or not to return the body of the request as a "content" key in the dictionary result. If the reported Content-type is "application/json", then the JSON is additionally loaded into a key called json in the dictionary results.
status_code	no	200		A valid, numeric, HTTP status code that signifies success of the request.
timeout	no	30		The socket level timeout in seconds
url	yes			HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path
user	no			username for the module to use for Digest, Basic or WSSE authentication.

Requirements: urlparse httplib2

Check that you can connect (GET) to a page and it returns a status 200

uri: url=http://www.awesome.com

Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents.

action: uri url=http://www.awesome.com return_content=yes
register: webpage

action: fail
when_string: '"AWESOME" not in "${webpage.content}"'

Create a JIRA issue.

action: >
        uri url=https://your.jira.server.com/rest/api/2/issue/
        method=POST user=your_username password=your_pass
        body='$FILE(issue.json)' force_basic_auth=yes
        status_code=201 HEADER_Content-Type="application/json"

Login to a form based webpage, then use the cookie that got returned to access the app in later tasks.

action: >
        uri url=https://your.form.based.auth.app.com/index.php
        method=POST body="name=your_username&password=your_password&enter=Sign%20in"
        status_code=302 HEADER_Content-Type="application/x-www-form-urlencoded"
register: login

action: uri url=https://your.form.based.auth.app.com/dashboard.php method=GET return_content=yes HEADER_Cookie="${login.set_cookie}"

campfire¶

New in version 1.2.

Send a message to Campfire. Messages with newlines will result in a “Paste” message being sent.

parameter	required	default	choices	comments
msg	yes			The message body.
notify	no		56k bueller crickets dangerzone deeper drama greatjob horn horror inconceivable live loggins noooo nyan ohmy ohyeah pushit rimshot sax secret tada tmyk trombone vuvuzela yeah yodel	Send a notification sound before the message.
room	yes			Room number to which the message should be sent.
subscription	yes			The subscription name to use.
token	yes			API token.

Requirements: urllib2 cgi

action: campfire subscription=foo token=12345 room=123 msg="Task completed."

action: campfire subscription=foo token=12345 room=123 notify=loggins
        msg="Task completed ... with feeling."

flowdock¶

New in version 1.2.

Send a message to a flowdock team inbox or chat using the push API (see https://www.flowdock.com/api/team-inbox and https://www.flowdock.com/api/chat)

parameter	required	default	choices	comments
external_user_name	no			(chat only - required) Name of the "user" sending the message
from_address	no			(inbox only - required) Email address of the message sender
from_name	no			(inbox only) Name of the message sender
link	no			(inbox only) Link associated with the message. This will be used to link the message subject in Team Inbox.
msg	yes			Content of the message
project	no			(inbox only) Human readable identifier for more detailed message categorization
reply_to	no			(inbox only) Email address for replies
source	no			(inbox only - required) Human readable identifier of the application that uses the Flowdock API
subject	no			(inbox only - required) Subject line of the message
tags	no			tags of the message, separated by commas
token	yes			API token.
type	yes		inbox chat	Whether to post to 'inbox' or 'chat'

Requirements: urllib urllib2

action: flowdock type=inbox token=AAAAAA from_address=[email protected] source='my cool app' msg='test from ansible' subject='test subject'

action: flowdock type=chat token=AAAAAA external_user_name=testuser msg='test from ansible' tags=tag1,tag2,tag3

hipchat¶

New in version 1.2.

Send a message to hipchat

parameter	required	default	choices	comments
color	no	yellow	yellow red green purple gray random	Background color for the message. Default is yellow.
from	no	Ansible		Name the message will appear be sent from. max 15 characters. Over 15, will be shorten.
msg	yes			The message body.
msg_format	no	text	text html	message format. html or text. Default is text.
notify	no	True	true false	notify or not (change the tab color, play a sound, etc)
room	yes			ID or name of the room.
token	yes			API token.

Requirements: urllib urllib2

action: hipchat token=AAAAAA room=notify msg="Ansible task finished"

irc¶

Send a message to an IRC channel. This is a very simplistic implementation.

parameter	required	default	choices	comments
channel	yes			Channel name
color	no	black	yellow red green blue black	Text color for the message. Default is black.
msg	yes			The message body.
nick	no	ansible		Nickname
port	no	6667		IRC server port number
server	no	localhost		IRC server name/address

Requirements: socket

action: irc server=irc.example.net channel="#t1" msg="Hello world"

local_action: irc port=6669
              channel="#t1"
              msg="All finished at {{ ansible_date_time.iso8601 }}"
              color=red
              nick=ansibleIRC

jabber¶

New in version 1.2.

Send a message to jabber

parameter	required	default	choices	comments
encoding	no			message encoding
host	no			host to connect, overrides user info
msg	yes			The message body.
password	yes			password for user to connect
port	no	5222		port to connect to, overrides default
to	yes			user ID or name of the room, when using room use a slash to indicate your nick.
user	yes			User as which to connect

Requirements: xmpp

# send a message to a user
jabber: user=[email protected] password=secret to=[email protected]  msg="Ansible task finished"

# send a message to a room
jabber: user=[email protected] password=secret to=[email protected]/ansiblebot  msg="Ansible task finished"

# send a message, specifying the host and port
jabber user=[email protected] host=talk.chatserver.tld port=5223 password=secret to=[email protected]  msg="Ansible task finished"

mail¶

New in version 0.8.

This module is useful for sending emails from playbooks. One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot be automated, either because you lack the authority to make it so, or because not everyone agrees to a common approach. If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to make him perform his part of the bargain is an elegant way to put the responsibility in someone else’s lap. Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action has been (successfully) taken.

parameter	required	default	choices	comments
attach	no			A space-separated list of pathnames of files to attach to the message. Attached files will have their content-type set to application/octet-stream. (added in Ansible 1.0)
bcc	no			The email-address(es) the mail is being 'blind' copied to. This is a comma-separated list, which may contain address and phrase portions.
body	no	$subject		The body of the email being sent.
cc	no			The email-address(es) the mail is being copied to. This is a comma-separated list, which may contain address and phrase portions.
charset	no	us-ascii		The character set of email being sent
from	no	root		The email-address the mail is sent from. May contain address and phrase.
headers	no			A vertical-bar-separated list of headers which should be added to the message. Each individual header is specified as header=value (see example below). (added in Ansible 1.0)
host	no	localhost		The mail server
port	no	25		The mail server port (added in Ansible 1.0)
subject	yes			The subject of the email being sent.
to	no	root		The email-address(es) the mail is being sent to. This is a comma-separated list, which may contain address and phrase portions.

Example playbook sending mail to root

local_action: mail msg='System ${ansible_hostname} has been sucessfully provisioned.'

Send e-mail to a bunch of users, attaching files

- local_action: mail
      host='127.0.0.1'
      port=2025
      subject="Ansible-report"
      body="Hello, this is an e-mail. I hope you like it ;-)"
      from="[email protected] (Jane Jolie)"
      to="John Doe <[email protected]>, Suzie Something <[email protected]>"
      cc="Charlie Root <root@localhost>"
      attach="/etc/group /tmp/pavatar2.png"
      headers=Reply-To=[email protected]|X-Special="Something or other"
      charset=utf8

mqtt¶

New in version 1.2.

Publish a message on an MQTT topic.

parameter	required	default	choices	comments
client_id	no	hostname + pid		MQTT client identifier
password	no			Password for username to authenticate against the broker.
payload	yes			Payload. The special string "None" may be used to send a NULL (i.e. empty) payload which is useful to simply notify with the topic or to clear previously retained messages.
port	no	1883		MQTT broker port number
qos	no		0 1 2	QoS (Quality of Service)
retain	no			Setting this flag causes the broker to retain (i.e. keep) the message so that applications that subsequently subscribe to the topic can received the last retained message immediately.
server	no	localhost		MQTT broker address/name
topic	yes			MQTT topic name
username	no			Username to authenticate against the broker.

Requirements: mosquitto

local_action: mqtt
              topic=service/ansible/{{ ansible_hostname }}
              payload="Hello at {{ ansible_date_time.iso8601 }}"
              qos=0
              retain=false
              client_id=ans001

Notes

This module requires a connection to an MQTT broker such as Mosquitto http://mosquitto.org and the mosquitto Python module (http://mosquitto.org/python).

osx_say¶

New in version 1.2.

makes an OS computer speak! Amuse your friends, annoy your coworkers!

parameter	required	default	choices	comments
msg	yes			What to say
voice	no			What voice to use

Requirements: say

local_action: osx_say msg="{{inventory_hostname}} is all done" voice=Zarvox

Notes

If you like this module, you may also be interested in the osx_say callback in the plugins/ directory of the source checkout.

apt¶

New in version 0.0.2.

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

parameter	required	default	choices	comments
cache_valid_time	no	no		If update_cache is specified and the last run is less or equal than cache_valid_time seconds ago, the update_cache gets skipped.
default_release	no			Corresponds to the -t option for apt and sets pin priorities
force	no	no	yes no	If yes, force installs/removes.
install_recommends	no	yes	yes no	Corresponds to the --no-install-recommends option for apt, default behavior works as apt's default behavior, no does not install recommended packages. Suggested packages are never installed.
pkg	yes			A package name or package specifier with version, like foo or foo=1.0
purge	no	no	yes no	Will force purging of configuration files if the module state is set to absent.
state	no	present	latest absent present	Indicates the desired package state
update_cache	no	no	yes no	Run the equivalent of apt-get update before the operation. Can be run as part of the package installation or as a separate step
upgrade	no	yes	yes safe full dist	If yes or safe, performs an aptitude safe-upgrade.If full, performs an aptitude full-upgrade.If dist, performs an apt-get dist-upgrade.Note: This does not upgrade a specific package, use state=latest for that. (added in Ansible 1.1)

Requirements: python-apt aptitude

Update repositories cache and install foo package

apt: pkg=foo update_cache=yes

Remove foo package

apt: pkg=foo state=removed

Install 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-reccomends

apt: pkg=openjdk-6-jdk state=latest install_recommends=no

Update all packages to the latest version

apt: upgrade=dist

Run the equivalent of apt-get update as a separate step

apt: update_cache=yes

Only run update_cache=yes if the last one is more than more than 3600 seconds ago

apt: update_cache=yes cache_valid_time=3600

Notes

Two of the upgrade modes (full and dist) require aptitude, otherwise apt-get suffices.

apt_key¶

New in version 1.0.

Add or remove an apt key, optionally downloading it

parameter	required	default	choices	comments
id	no	none		identifier of key
state	no	present	absent present	used to specify if key is being added or revoked
url	no	none		url to retrieve key from.

Add an Apt signing key, uses whichever key is at the URL

apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present

Add an Apt signing key, will not download if present

apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present

Remove an Apt signing key, uses whichever key is at the URL

apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent

Remove a Apt specific signing key

apt_key: id=473041FA state=absent

Notes

doesn't download the key unless it really needs it

as a sanity check, downloaded key id must match the one specified

best practice is to specify the key id and the url

apt_repository¶

New in version 0.7.

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

parameter	required	default	choices	comments
repo	yes			The repository name/value
state	no	present	present absent	The repository state

Requirements: python-apt

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 the destination server. To ensure this package is available use the apt module and install the python-software-properties package before using this module.

This module cannot be used on Debian Squeeze (Version 6) as there is no add-apt-repository in python-software-properties

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.

easy_install¶

New in version 0.7.

Installs Python libraries, optionally in a virtualenv

parameter	required	default	choices	comments
name	yes			A Python library name
virtualenv	no			an optional virtualenv directory path to install into. If the virtualenv does not exist, it is created automatically
virtualenv_command	no	virtualenv		The command to create the virtual environment with. For example pyvenv, virtualenv, virtualenv2. (added in Ansible 1.1)
virtualenv_site_packages	no	no	yes no	Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting is changed on an already existing virtual environment it will not have any effect, the environment must be deleted and newly created. (added in Ansible 1.1)

Requirements: 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.

gem¶

New in version 1.1.

Manage installation and uninstallation of Ruby gems.

parameter	required	default	choices	comments
gem_source	no			The path to a local gem used as installation source.
include_dependencies	no	yes	yes no	Wheter to include dependencies or not.
name	yes			The name of the gem to be managed.
repository	no			The repository from which the gem will be installed
state	yes		present absent latest	The desired state of the gem. latest ensures that the latest version is installed.
version	no			Version of the gem to be installed/removed.

# Installs version 1.0 of vagrant.
gem: name=vagrant version=1.0 state=present

# Installs latest available version of rake.
gem: name=rake state=latest

# Installs rake version 1.0 from a local gem on disk.
gem: name=rake gem_source=/path/to/gems/rake-1.0.gem state=present

homebrew¶

New in version 1.1.

Manages Homebrew packages

parameter	required	default	choices	comments
name	yes			name of package to install/remove
state	no	present	present absent	state of the package
update_homebrew	no	no	yes no	update homebrew itself first

homebrew: name=foo state=present
homebrew: name=foo state=present update_homebrew=yes
homebrew: name=foo state=absent
homebrew: name=foo,bar state=absent

macports¶

New in version 1.1.

Manages MacPorts packages

parameter	required	default	choices	comments
name	yes			name of package to install/remove
state	no	present	present absent active inactive	state of the package
update_cache	no	no	yes no	update the package db first

macports: name=foo state=present
macports: name=foo state=present update_cache=yes
macports: name=foo state=absent
macports: name=foo state=active
macports: name=foo state=inactive

npm¶

New in version 1.2.

Manage node.js packages with Node Package Manager (npm)

parameter	required	default	choices	comments
executable	no	nvm		The executable location for npm.This is useful if you are using a version manager, such as nvm
global	no		yes no
name	no			The name of a node.js library to install
path	no			The base path where to install the node.js libraries
production	no			Install dependencies in production mode, excluding devDependencies
state	no	present	present absent latest	The state of the node.js library
version	no			The version to be installed

Install coffee-script node.js package.

npm: name=coffee-script path=/app/location

Install coffee-script node.js package on version 1.6.1.

npm: name=coffee-script version=1.6.1 path=/app/location

Install coffee-script node.js package globally.

npm: name=coffee-script global=yes

Remove the globally package coffee-script.

npm: name=coffee-script global=yes state=absent

Install packages based on package.json.

npm: path=/app/location

Update packages based on package.json to their latest version.

npm: path=/app/location state=latest

Install packages based on package.json using the npm installed with nvm v0.10.1.

npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present

openbsd_pkg¶

New in version 1.1.

Manage packages on OpenBSD using the pkg tools.

parameter	required	default	choices	comments
name	yes			Name of the package.
state	yes		present latest absent	present will make sure the package is installed. latest will make sure the latest version of the package is installed. absent will make sure the specified package is not installed.

Make sure nmap is installed

openbsd_pkg: name=nmap state=present

Make sure nmap is the latest version

openbsd_pkg: name=nmap state=latest

Make sure nmap is not installed

openbsd_pkg: name=nmap state=absent

opkg¶

New in version 1.1.

Manages OpenWrt packages

parameter	required	default	choices	comments
name	yes			name of package to install/remove
state	no	present	present absent	state of the package
update_cache	no	no	yes no	update the package db first

opkg: name=foo state=present
opkg: name=foo state=present update_cache=yes
opkg: name=foo state=absent
opkg: name=foo,bar state=absent

pacman¶

New in version 1.0.

Manages Archlinux packages

parameter	required	default	choices	comments
name	yes			name of package to install, upgrade or remove.
state	no			state of the package (installed or absent).
update_cache	no	no	yes no	update the package database first (pacman -Syy).

install package foo

pacman: name=foo state=installed

remove package foo

pacman: name=foo state=absent

remove packages foo and bar

pacman: name=foo,bar state=absent

update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists)

pacman: name=bar, state=installed, update_cache=yes

pip¶

New in version 0.7.

Manage Python library dependencies.

parameter	required	default	choices	comments
extra_args	no			Extra arguments passed to pip. (added in Ansible 1.0)
name	no			The name of a Python library to install
requirements	no			The path to a pip requirements file
state	no	present	present absent latest	The state of module
use_mirrors	no	yes	yes no	Whether to use mirrors when installing python libraries. If using an older version of pip (< 1.0), you should set this to no because older versions of pip do not support --use-mirrors. (added in Ansible 1.0)
version	no			The version number to install of the Python library specified in the name parameter
virtualenv	no			An optional path to a virtualenv directory to install into
virtualenv_command	no	virtualenv		The command to create the virtual environment with. For example pyvenv, virtualenv, virtualenv2.
virtualenv_site_packages	no	no	yes no	Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting is changed on an already existing virtual environment it will not have any effect, the environment must be deleted and newly created. (added in Ansible 1.0)

Requirements: virtualenv pip

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, inheriting none of the globally installed modules

pip: name=flask virtualenv=/my_app/venv

Install Flask (http://flask.pocoo.org/) into the specified virtualenv, inheriting globally installed modules

pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes

Install Flask (http://flask.pocoo.org/) into the specified virtualenv, using Python 2.7

pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7

Install specified python requirements.

pip: requirements=/my_app/requirements.txt

Install specified python requirements in indicated virtualenv.

pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv

Install specified python requirements and custom Index URL.

pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'

Notes

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

pkgin¶

New in version 1.0.

Manages SmartOS packages

parameter	required	default	choices	comments
name	yes			name of package to install/remove
state	no	present	present absent	state of the package

install package foo"

pkgin: name=foo state=present

remove package foo

pkgin: name=foo state=absent

remove packages foo and bar

pkgin: name=foo,bar state=absent

pkgng¶

New in version 1.2.

Manage binary packages for FreeBSD using ‘pkgng’ which is available in versions after 9.0.

parameter	required	default	choices	comments
cached	no		yes no	use local package base or try to fetch an updated one
name	yes			name of package to install/remove
pkgsite	no			specify packagesite to use for downloading packages, if not specified, use settings from /usr/local/etc/pkg.conf
state	no	present	present absent	state of the package

install package foo"

pkgng: name=foo state=present

remove package foo

pkgng: name=foo state=absent

remove packages foo and bar

pkgng: name=foo,bar state=absent

Notes

When using pkgsite, be careful that already in cache packages won't be downloaded again.

rhn_channel¶

New in version 1.1.

Adds or removes Red Hat software channels

parameter	required	default	choices	comments
name	yes			name of the software channel
password	yes			the user's password
state	no	present		whether the channel should be present or not
sysname	yes			name of the system as it is known in RHN/Satellite
url	yes			The full url to the RHN/Satellite api
user	yes			RHN/Satellite user

Requirements: none

rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme

Notes

this module fetches the system id from RHN.

svr4pkg¶

New in version 0.9.

Manages SVR4 packages on Solaris 10 and 11. These were the native packages on Solaris <= 10 and are available as a legacy feature in Solaris 11. Note that this is a very basic packaging system. It will not enforce dependencies on install or remove.

parameter	required	default	choices	comments
name	yes			Package name, e.g. SUNWcsr
proxy	no			HTTP[s] proxy to be used if src is a URL.
src	no			Specifies the location to install the package from. Required when state=present.Can be any path acceptable to the pkgadd command's -d option. e.g.: somefile.pkg, /dir/with/pkgs, http:/server/mypkgs.pkg.If using a file or directory, they must already be accessible by the host. See the copy module for a way to get them there.
state	yes		present absent	Whether to install (present), or remove (absent) a package.If the package is to be installed, then src is required.The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package.

Install a package from an already copied file

svr4pkg name=CSWcommon src=/tmp/cswpkgs.pkg state=present

Install a package directly from an http site

svr4pkg name=CSWpkgutil src=http://get.opencsw.org/now state=present

Ensure that a package is not installed.

svr4pkg name=SUNWgnome-sound-recorder state=absent

yum¶

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

parameter	required	default	choices	comments
conf_file	no			The remote yum configuration file to use for the transaction. (added in Ansible 0.6)
disable_gpg_check	no	no	yes no	Whether to disable the GPG checking of signatures of packages being installed. Has an effect only if state is present or latest. (added in Ansible 1.2)
disablerepo	no			repoid of repositories to disable for the install/update operation These repos will not persist beyond the transaction Multiple repos separated with a ',' (added in Ansible 0.9)
enablerepo	no			Repoid of repositories to enable for the install/update operation. These repos will not persist beyond the transaction multiple repos separated with a ',' (added in Ansible 0.9)
list	no			various non-idempotent commands for usage with /usr/bin/ansible and not playbooks. See examples.
name	yes			package name, or package specifier with version, like name-1.0.
state	no	present	present latest absent	whether to install (present, latest), or remove (absent) a package.

Requirements: yum rpm

yum name=httpd state=latest

yum name=httpd state=removed

yum name=httpd enablerepo=testing state=installed

bzr¶

New in version 1.1.

Manage bzr branches to deploy files or software.

parameter	required	default	choices	comments
dest	yes			Absolute path of where the branch should be cloned to.
force	no	yes	True False	If yes, any modified files in the working tree will be discarded.
name	yes			SSH or HTTP protocol address of the parent branch.
version	no	head		What version of the branch to clone. This can be the bzr revno or revid.

Example bzr checkout from Ansible Playbooks

bzr name=bzr+ssh://foosball.example.org/path/to/branch dest=/srv/checkout version=22

git¶

New in version 0.0.1.

Manage git checkouts of repositories to deploy files or software.

parameter	required	default	choices	comments
depth	no			Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is 1, otherwise ignored. (added in Ansible 1.2)
dest	yes			Absolute path of where the repository should be checked out to.
force	no	yes	yes no	If yes, any modified files in the working repository will be discarded. Prior to 0.7, this was always 'yes' and could not be disabled. (added in Ansible 0.7)
remote	no	origin		Name of the remote.
repo	yes			git, SSH, or HTTP protocol address of the git repository.
version	no	HEAD		What version of the repository to check out. This can be the git SHA, the literal string HEAD, a branch name, or a tag name.

Example git checkout from Ansible Playbooks

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

Example read-write git checkout from github

git: repo=ssh://[email protected]/mylogin/hello.git dest=/home/mylogin/hello

hg¶

New in version 1.0.

Manages Mercurial (hg) repositories. Supports SSH, HTTP/S and local address.

parameter	required	default	choices	comments
dest	yes			Absolute path of where the repository should be cloned to.
force	no	yes	yes no	Discards uncommited changes. Runs hg update -C.
purge	no	no	yes no	Delets untracked files. Runs hg purge. Note this requires purge extension to be enabled if purge=yes. This module will modify hgrc file on behalf of the user and undo the changes before exiting the task.
repo	yes			The repository address.
revision	no	default		Equivalent -r option in hg command which could be the changeset, revision number, branch name or even tag.

Ensure the current working copy is inside the stable branch and deletes untracked files if any.

hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes

Notes

If the task seems to be hanging, first verify remote host is in known_hosts. SSH will prompt user to authorize the first contact with a remote host. One solution is to add StrictHostKeyChecking no in .ssh/config which will accept and authorize the connection on behalf of the user. However, if you run as a different user such as setting sudo to True), for example, root will not look at the user .ssh/config setting.

subversion¶

New in version 0.7.

Deploy given repository URL / revision to dest.

parameter	required	default	choices	comments
dest	yes			Absolute path where the repository should be deployed.
force	no	yes	yes no	If yes, modified files will be discarded. If no, module will fail if it encounters modified files.
password	no			--password parameter passed to svn.
repo	yes			The subversion URL to the repository.
revision	no	HEAD		Specific revision to checkout.
username	no			--username parameter passed to svn.

Checkout subversion repository to specified folder.

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

Notes

Requres svn to be installed on the client.

authorized_key¶

New in version 0.5.

adds or removes authorized keys for particular user accounts

parameter	required	default	choices	comments
key	yes			the SSH public key, as a string
manage_dir	no	yes	yes no	Whether this module should manage the directory of the authorized_keys file (added in Ansible 1.2)
path	no	(homedir)+/.ssh/authorized_keys		Alternate path to the authorized_keys file (added in Ansible 1.2)
state	no	present	present absent	whether the given key should or should not be in the file
user	yes			Name of the user who should have access to the remote host

# Example using key data from a local file on the management machine
authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"

# Using alternate directory locations:
authorized_key: user=charlie key="{{ lookup('file', '/home/charlie/.ssh/id_rsa.pub') }}"  sshdir='/etc/ssh/authorized_keys/charlie' manage_dir=no

cron¶

New in version 0.9.

Use this module to manage crontab entries. This module allows you to create named crontab entries, update, or delete them. The module includes one line with the description of the crontab entry "#Ansible: <name>" corresponding to the “name” passed to the module, which is used by future ansible/module calls to find/check the state.

parameter	required	default	choices	comments
backup	no			If set, then create a backup of the crontab before it is modified.The location of the backup is returned in the backup variable by this module.
cron_file	no			If specified, uses this file in cron.d versus in the main crontab
day	no	*		Day of the month the job should run ( 1-31, *, */2, etc )
hour	no	*		Hour when the job should run ( 0-23, *, */2, etc )
job	no			The command to execute.Required if state=present.
minute	no	*		Minute when the job should run ( 0-59, *, */2, etc )
month	no	*		Month of the year the job should run ( 1-12, *, */2, etc )
name	yes			Description of a crontab entry.
reboot	no	no	yes no	If the job should be run at reboot, will ignore minute, hour, day, and month settings in favour of @reboot (added in Ansible 1.0)
state	no	present		Whether to ensure the job is present or absent.
user	no	root		The specific user who's crontab should be modified.
weekday	no	*		Day of the week that the job should run ( 0-7 for Sunday - Saturday, or mon, tue, * etc )

Requirements: cron

Ensure a job that runs at 2 and 5 exists. Creates an entry like "* 5,2 * * ls -alh > /dev/null"

cron: name="check dirs" hour="5,2" job="ls -alh > /dev/null"

Ensure an old job is no longer present. Removes any job that is preceded by "#Ansible: an old job" in the crontab

cron: name="an old job" cron job="/some/dir/job.sh" state=absent

Creates an entry like "@reboot /some/job.sh"

cron: name="a job for reboot" reboot=yes job="/some/job.sh"

cron: name="yum autoupdate" weekday="2" minute=0 hour=12 user="root" job="YUMINTERACTIVE=0 /usr/sbin/yum-autoupdate" cron_file=ansible_yum-autoupdate

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.

Requirements: facter ruby-json

Example command-line invocation

ansible www.example.net -m facter

filesystem¶

New in version 1.2.

This module creates file system.

parameter	required	default	choices	comments
dev	yes			Target block device.
force	no	no	yes no	If yes, allows to create new filesystem on devices that already has filesystem.
fstype	yes			File System type to be created.
opts	no			List of options to be passed to mkfs command.

Create a ext2 filesystem on /dev/sdb1.

filesystem fstype=ext2 dev=/dev/sdb1

Create a ext4 filesystem on /dev/sdb1 and check disk blocks.

filesystem fstype=ext4 dev=/dev/sdb1 opts="-cc"

Notes

uses mkfs command

group¶

New in version 0.0.2.

Manage presence of groups on a host.

parameter	required	default	choices	comments
gid	no			Optional GID to set for the group.
name	yes			Name of the group to manage.
state	no	present	present absent	Whether the group should be present or not on the remote host.
system	no	no	yes no	If yes, indicates that the group created is a system group.

Requirements: groupadd groupdel groupmod

Example group command from Ansible Playbooks

group: name=somegroup state=present

lvg¶

New in version 1.1.

This module creates, removes or resizes volume groups.

parameter	required	default	choices	comments
force	no	no	yes no	If yes, allows to remove volume group with logical volumes.
pesize	no	4		The size of the physical extent in megabytes. Must be a power of 2.
pvs	no			List of comma-separated devices to use as physical devices in this volume group. Required when creating or resizing volume group.
state	no	present	present absent	Control if the volume group exists.
vg	yes			The name of the volume group.

Create a volume group on top of /dev/sda1 with physical extent size = 32MB.

lvg vg=vg.services pvs=/dev/sda1 pesize=32

Create or resize a volume group on top of /dev/sdb1 and /dev/sdc5. If, for example, we already have VG vg.services on top of /dev/sdb1, this VG will be extended by /dev/sdc5. Or if vg.services was created on top of /dev/sda5, we first extend it with /dev/sdb1 and /dev/sdc5, and then reduce by /dev/sda5.

lvg vg=vg.services pvs=/dev/sdb1,/dev/sdc5

Remove a volume group with name vg.services.

lvg vg=vg.services state=absent

Notes

module does not modify PE size for already present volume group

lvol¶

New in version 1.1.

This module creates, removes or resizes logical volumes.

parameter	required	default	choices	comments
lv	yes			The name of the logical volume.
size	no			The size of the logical volume in megabytes.
state	no	present	present absent	Control if the logical volume exists.
vg	yes			The volume group this logical volume is part of.

Create a logical volume of 512m.

lvol vg=firefly lv=test size=512

Extend the logical volume to 1024m.

lvol vg=firefly lv=test size=1024

Reduce the logical volume to 512m

lvol vg=firefly lv=test size=512

Remove the logical volume.

lvol vg=firefly lv=test state=absent

Notes

Filesystems on top of the volume are not resized.

mount¶

New in version 0.6.

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

parameter	required	default	choices	comments
dump	no			dump (see fstab(8))
fstype	yes			file-system type
name	yes			path to the mount point, eg: /mnt/files
opts	no			mount options (see fstab(8))
passno	no			passno (see fstab(8))
src	yes			device to be mounted on name.
state	yes		present absent mounted unmounted	If mounted or unmounted, the device will be actively mounted or unmounted as well as just configured in fstab. absent and present only deal with fstab.

Mount DVD read-only

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

Mount up device by label

mount: name=/srv/disk src='LABEL=SOME_LABEL' state=present

Mount up device by UUID

mount: name=/home src='UUID=b3e48f45-f933-4c8e-a700-22a159ec9077' opts=noatime state=present

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.

Requirements: ohai

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 it is useful from /usr/bin/ansible

Test 'webservers' status

ansible webservers -m ping

seboolean¶

New in version 0.7.

Toggles SELinux booleans.

parameter	required	default	choices	comments
name	yes			Name of the boolean to configure
persistent	no		yes no	Set to yes if the boolean setting should survive a reboot
state	yes		True False	Desired boolean value

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.

parameter	required	default	choices	comments
conf	no	/etc/selinux/config		path to the SELinux configuration file, if non-standard
policy	no			name of the SELinux policy to use (example: targeted) will be required if state is not disabled
state	yes		enforcing permissive disabled	The SELinux mode

Requirements: libselinux-python

selinux: policy=targeted state=enforcing

selinux: policy=targeted state=permissive

selinux: state=disabled

Notes

Not tested on any debian based system

service¶

New in version 0.1.

Controls services on remote hosts.

parameter	required	default	choices	comments
arguments	no			Additional arguments provided on the command line
enabled	no		yes no	Whether the service should start on boot. At least one of state and enabled are required.
name	yes			Name of the service.
pattern	no			If the service does not respond to the status command, name a substring to look for as would be found in the output of the ps command as a stand-in for a status result. If the string is found, the service will be assumed to be running. (added in Ansible 0.7)
state	no		started stopped restarted reloaded	started/stopped are idempotent actions that will not run commands unless necessary. restarted will always bounce the service. reloaded will always reload. At least one of state and enabled are required.

Example action to start service httpd, if not running

service: name=httpd state=started

Example action to stop service httpd, if running

service: name=httpd state=stopped

Example action to restart service httpd, in all cases

service: name=httpd state=restarted

Example action to reload service httpd, in all cases

service: name=httpd state=reloaded

Example action to enable service httpd, and not touch the running state

service: name=httpd enabled=yes

Example action to start service foo, based on running process /usr/bin/foo

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

Example action to restart network service for interface eth0

service: name=network state=restarted args=eth0

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.

parameter	required	default	choices	comments
filter	no	*		if supplied, only return facts that match this shell-style (fnmatch) wildcard. (added in Ansible 1.1)

# Display facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts).
ansible all -m setup --tree /tmp/facts

# Display only facts regarding memory found by ansible on all hosts and output them.
ansible all -m setup -a 'filter=ansible_*_mb'

# Display only facts returned by facter.
ansible all -m setup -a 'filter=facter_*'

# Display only facts returned by facter.
ansible all -m setup -a 'filter=ansible_eth[0-2]'

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. (See also facter and ohai.)

The filter option filters only the first level subkey below ansible_facts.

sysctl¶

New in version 1.0.

This module manipulates sysctl entries and performs a /sbin/sysctl -p after changing them.

parameter	required	default	choices	comments
checks	no	both	none before after both	if checks=none no smart/facultative checks will be madeif checks=before some checks performed before any update (ie. does the sysctl key is writable ?)if checks=after some checks performed after an update (ie. does kernel give back the setted value ?)if checks=both all the smart checks before and after are performed
name	yes			this is the short path, decimal separated, to the sysctl entry
reload	no	yes	yes no	if reload=yes, performs a /sbin/sysctl -p if the sysctl_file is updatedif reload=no, does not reload sysctl even if the sysctl_file is updated
state	no	present	present absent	whether the entry should be present or absent
sysctl_file	no	/etc/sysctl.conf		specifies the absolute path to sysctl.conf, if not /etc/sysctl.conf
value	no			set the sysctl value to this entry

Set vm.swappiness to 5 in /etc/sysctl.conf

sysctl: name=vm.swappiness value=5 state=present

Remove kernel.panic entry from /etc/sysctl.conf

sysctl: name=kernel.panic state=absent sysctl_file=/etc/sysctl.conf

Set kernel.panic to 3 in /tmp/test_sysctl.conf, check if the sysctl key seems writable, but do not reload sysctl, and do not check kernel value after (not needed, because not the real /etc/sysctl.conf updated)

sysctl: name=kernel.panic value=3 sysctl_file=/tmp/test_sysctl.conf check=before reload=no

user¶

New in version 0.2.

Manage user accounts and user attributes.

parameter	required	default	choices	comments
append	no			If yes, will only add groups, not set them to just the list in groups.
comment	no			Optionally sets the description (aka GECOS) of user account.
createhome	no	yes	yes no	Unless set to no, a home directory will be made for the user when the account is created.
force	no	no	yes no	When used with state=absent, behavior is as with userdel --force.
generate_ssh_key	no	no	yes no	Whether to generate a SSH key for the user in question. This will not overwrite an existing SSH key. (added in Ansible 0.9)
group	no			Optionally sets the user's primary group (takes a group name).
groups	no			Puts the user in this comma-delimited list of groups. When set to the empty string ('groups='), the user is removed from all groups except the primary group.
home	no			Optionally set the user's home directory.
name	yes			Name of the user to create, remove or modify.
non_unique	no	no	yes no	Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. (added in Ansible 1.1)
password	no			Optionally set the user's password to this crypted value. See the user example in the github examples directory for what this looks like in a playbook.
remove	no	no	yes no	When used with state=absent, behavior is as with userdel --remove.
shell	no			Optionally set the user's shell.
ssh_key_bits	no	2048		Optionally specify number of bits in SSH key to create. (added in Ansible 0.9)
ssh_key_comment	no	ansible-generated		Optionally define the comment for the SSH key. (added in Ansible 0.9)
ssh_key_file	no	$HOME/.ssh/id_rsa		Optionally specify the SSH key filename. (added in Ansible 0.9)
ssh_key_passphrase	no			Set a passphrase for the SSH key. If no passphrase is provided, the SSH key will default to having no passphrase. (added in Ansible 0.9)
ssh_key_type	no	rsa		Optionally specify the type of SSH key to generate. Available SSH key types will depend on implementation present on target host. (added in Ansible 0.9)
state	no	present	present absent	Whether the account should exist. When absent, removes the user account.
system	no	no	yes no	When creating an account, setting this to yes makes the user a system account. This setting cannot be changed on existing users.
uid	no			Optionally sets the UID of the user.

Requirements: useradd userdel usermod

Add the user 'johnd' with a specific uid and a primary group of 'admin'

user: name=johnd comment="John Doe" uid=1040

Remove the user 'johnd'

user: name=johnd state=absent remove=yes

Create a 2048-bit SSH key for user jsmith

user: name=jsmith generate_ssh_key=yes ssh_key_bits=2048

zfs¶

New in version 1.1.

Manages ZFS file systems on Solaris and FreeBSD. Can manage file systems, volumes and snapshots. See zfs(1M) for more information about the properties.

parameter	required	default	choices	comments
aclinherit	no		discard noallow restricted passthrough passthrough-x	The aclinherit property.
aclmode	no		discard groupmask passthrough	The aclmode property.
atime	no		True False	The atime property.
canmount	no		True False noauto	The canmount property.
casesensitivity	no		sensitive insensitive mixed	The casesensitivity property.
checksum	no		True False fletcher2 fletcher4 sha256	The checksum property.
compression	no		True False lzjb gzip gzip-1 gzip-2 gzip-3 gzip-4 gzip-5 gzip-6 gzip-7 gzip-8 gzip-9	The compression property.
copies	no		1 2 3	The copies property.
dedup	no		True False	The dedup property.
devices	no		True False	The devices property.
exec	no		True False	The exec property.
jailed	no		True False	The jailed property.
logbias	no		latency throughput	The logbias property.
mountpoint	no			The mountpoint property.
name	yes			File system, snapshot or volume name e.g. rpool/myfs
nbmand	no		True False	The nbmand property.
normalization	no		none formC formD formKC formKD	The normalization property.
primarycache	no		all none metadata	The primarycache property.
quota	no			The quota property.
readonly	no		True False	The readonly property.
recordsize	no			The recordsize property.
refquota	no			The refquota property.
refreservation	no			The refreservation property.
reservation	no			The reservation property.
secondarycache	no		all none metadata	The secondarycache property.
setuid	no		True False	The setuid property.
shareiscsi	no		True False	The shareiscsi property.
sharenfs	no			The sharenfs property.
sharesmb	no			The sharesmb property.
snapdir	no		hidden visible	The snapdir property.
state	yes		present absent	Whether to create (present), or remove (absent) a file system, snapshot or volume.
sync	no		True False	The sync property.
utf8only	no		True False	The utf8only property.
volblocksize	no			The volblocksize property.
volsize	no			The volsize property.
vscan	no		True False	The vscan property.
xattr	no		True False	The xattr property.
zoned	no		True False	The zoned property.

Create a new file system called myfs in pool rpool

zfs name=rpool/myfs state=present

Create a new volume called myvol in pool rpool.

zfs name=rpool/myvol state=present volsize=10M

Create a snapshot of rpool/myfs file system.

zfs name=rpool/myfs@mysnapshot state=present

Create a new file system called myfs2 with snapdir enabled

zfs name=rpool/myfs2 state=present snapdir=enabled

debug¶

New in version 0.8.

This module prints statements during execution and can be useful for debugging variables or expressions without necessarily halting the playbook. Useful for debugging together with the only_if directive. In order to see the debug message, you need to run ansible in verbose mode (using the -v option).

parameter	required	default	choices	comments
fail	no	no	yes no	A boolean that indicates whether the debug module should fail or not.
msg	no	Hello world!		The customized message that is printed. If omitted, prints a generic message.

Example that prints the loopback address and gateway for each host

- action: debug msg="System $inventory_hostname has uuid $ansible_product_uuid"
- action: debug msg="System $inventory_hostname lacks a gateway" fail=yes
  only_if: "is_unset('${ansible_default_ipv4.gateway}')"
- action: debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"
  only_if: "is_set('${ansible_default_ipv4.gateway}')"

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.

parameter	required	default	choices	comments
msg	no	'Failed as requested from task'		The customized message used for failing execution. If omitted, fail will simple bail out with a generic message.

Example playbook using fail and only_if together

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

fireball¶

New in version 0.9.

This modules launches an ephemeral fireball ZeroMQ message bus daemon on the remote node which Ansible can use 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

parameter	required	default	choices	comments
minutes	no	30		The fireball listener daemon is started on nodes and will stay around for this number of minutes before turning itself off.
port	no	5099		TCP port for ZeroMQ

Requirements: zmq keyczar

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:
          - command: /usr/bin/anything

Notes

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

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.

parameter	required	default	choices	comments
minutes	no			Number of minutes to pause for.
prompt	no			Optional text to use for the prompt message.
seconds	no			Number of seconds to pause for.

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"

set_fact¶

New in version 1.2.

This module allows setting new variables. Variables are set on a host-by-host basis just like facts discovered by the setup module. These variables will survive between plays.

parameter	required	default	choices	comments
key_value	yes			The set_fact module takes key=value pairs as variables to set in the playbook scope. Or alternatively, accepts complex arguments using the args: statement.

Example setting host facts using key=value pairs

action: set_fact one_fact="something" other_fact="{{ local_var * 2 }}"'

Example setting host facts using complex arguments

action: set_fact
args:
  one_fact: something
  other_fact: "{{ local_var * 2 }}"

Notes

You can set play variables using the set_var module.

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.

parameter	required	default	choices	comments
delay	no			number of seconds to wait before starting to poll
host	no	127.0.0.1		hostname or IP address to wait for
port	yes			port number to poll
state	no	started	started stopped	either started, or stopped depending on whether the module should poll for the port being open or closed.
timeout	no	300		maximum number of seconds to wait for

Example from Ansible Playbooks

wait_for: port=8000 delay=10

django_manage¶

New in version 1.1.

Manages a Django application using the manage.py application frontend to django-admin. With the virtualenv parameter, all management commands will be executed by the given virtualenv installation.

parameter	required	default	choices	comments
app_path	yes			The path to the root of the Django application where manage.py lives.
apps	no			A list of space-delimited apps to target. Used by the 'test' command.
cache_table	no			The name of the table used for database-backed caching. Used by the 'createcachetable' command.
command	yes		cleanup flush loaddata runfcgi syncdb test validate	The name of the Django management command to run. Allowed commands are cleanup, createcachetable, flush, loaddata, syncdb, test, validate.
database	no			The database to target. Used by the 'createcachetable', 'flush', 'loaddata', and 'syncdb' commands.
failfast	no	no	yes no	Fail the command immediately if a test fails. Used by the 'test' command.
fixtures	no			A space-delimited list of fixture file names to load in the database. Required by the 'loaddata' command.
pythonpath	no			A directory to add to the Python path. Typically used to include the settings module if it is located external to the application directory.
settings	no			The Python path to the application's settings module, such as 'myapp.settings'.
virtualenv	no			An optional path to a virtualenv installation to use while running the manage application.

Requirements: virtualenv django

# Run cleanup on the application installed in '$django_dir'.
django_manage: command=cleanup app_path=$django_dir

# Load the $initial_data fixture into the application
django_manage: command=loaddata app_path=$django_dir fixtures=$initial_data

#Run syncdb on the application
django_manage: >
    command=syncdb
    app_path=$django_dir
    settings=$settings_app_name
    pythonpath=$settings_dir
    virtualenv=$virtualenv_dir
    database=$mydb

#Run the SmokeTest test case from the main app. Useful for testing deploys.
django_manage command=test app_path=django_dir apps=main.SmokeTest

Notes

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

This module will create a virtualenv if the virtualenv parameter is specified and a virtualenv does not already exist at the given location.

This module assumes English error messages for the 'createcachetable' command to detect table existence, unfortunately.

supervisorctl¶

New in version 0.7.

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

parameter	required	default	choices	comments
name	yes			The name of the supervisord program/process to manage
state	yes		present started stopped restarted	The state of service

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

supervisorctl: name=my_app state=started