Contents
Ansible ships with a number of modules (called the ‘module library’) that can be executed directly on remote hosts or through Playbooks. Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or handle executing system commands.
Let’s review how we execute three different modules from the command line:
ansible webservers -m service -a "name=httpd state=running"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"
Each module supports taking arguments. Nearly all modules take key=value arguments, space delimited. Some modules take no arguments, and the command/shell modules simply take the string of the command you want to run.
From playbooks, Ansible modules are executed in a very similar way:
- name: reboot the servers
action: command /sbin/reboot -t now
Version 0.8 and higher support the following shorter syntax:
- name: reboot the servers
command: /sbin/reboot -t now
All modules technically return JSON format data, though if you are using the command line or playbooks, you don’t really need to know much about that. If you’re writing your own module, you care, and this means you do not have to write modules in any particular language – you get to choose.
Modules are idempotent, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible playbooks, these modules can trigger ‘change events’ in the form of notifying ‘handlers’ to run additional tasks.
Documention for each module can be accessed from the command line with the ansible-doc as well as the man command:
ansible-doc command
man ansible.template
Let’s see what’s available in the Ansible module library, out of the box:
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 seperated. | ||
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_ec2create} 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}'
New in version 0.0.2.
Manages apt packages (such as for Debian/Ubuntu).
parameter | required | default | choices | comments |
---|---|---|---|---|
default_release | no | Corresponds to the -t option for apt and sets pin priorities |
||
force | no | no |
|
If yes , force installs/removes. |
install_recommends | no | yes |
|
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 |
|
Will force purging of configuration files if the module state is set to absent. |
state | no | present |
|
Indicates the desired package state |
update_cache | no | 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 |
|
If yes, performs an aptitude safe-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) |
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
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 |
|
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
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
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 |
|
The repository state |
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'
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.
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 |
|
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
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 |
|
if status , obtain the status; if cleanup , clean up the async job cache located in ~/.ansible_async/ for the specified job jid. |
See http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling
New in version 0.5.
Adds or removes an SSH authorized key for a user from a remote host.
parameter | required | default | choices | comments |
---|---|---|---|---|
key | yes | the SSH public key, as a string | ||
state | no | present |
|
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 from Ansible Playbooks
authorized_key: user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
Shorthand available in Ansible 0.8 and later
authorized_key: user=charlie key='$FILE(/home/charlie/.ssh/id_rsa.pub)'
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 |
|
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
New in version 1.1.
Launches an AWS CloudFormation stack and waits for it complete.
parameter | required | default | choices | comments |
---|---|---|---|---|
disable_rollback | no | 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 |
|
Wait while the stack is being created/updated/deleted. |
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
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.
The copy module copies a file on the local box to remote locations.
parameter | required | default | choices | comments |
---|---|---|---|---|
backup | no | 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 |
|
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. |
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
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.
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 |
|
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 ) |
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
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 |
|
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}')"
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 |
|
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 |
|
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. |
# 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
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.
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 |
|
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) |
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
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.
New in version 0.9.
creates ec2 instances and optionally waits for it to be ‘running’. This module has a dependency on python-boto.
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) | ||
ramdisk | no | ramdisk eri to use for the instance | ||
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 |
|
wait for the instance to be in state 'running' before returning |
wait_timeout | no | 300 | how long before wait gives up, in seconds |
Examples from Ansible Playbooks
local_action: ec2 keypair=admin instance_type=m1.large image=emi-40603AD1 wait=yes group=webserver count=3 group=webservers
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
Parameters to filter on ec2_facts may be added later.
New in version 1.1.
creates an EBS volume and optionally attaches it to an instance. 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 instance-store, /dev/sdb for EBS. | ||
instance | no | instance ID if you wish to attach 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) |
Simple playbook example
local_action: ec2_vol instance=XXXXXX volume_size=5 device_name=sdd
Advanced - attaching multiple volumes to multiple instances
- name: Launch instances local_action: ec2 keypair=$keypair image=$image wait=yes count=3 register: ec2 - name: Create volumes and attach local_action: ec2_vol instance=${item.id} volume_size=5 with_items: ${ec2.instances} register: ec2_vol
New in version 0.2.
Runs the facter discovery program (https://github.com/puppetlabs/facter) on the remote system, returning JSON data that can be useful for inventory purposes.
Example command-line invocation
ansible www.example.net -m facter
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'"
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 |
|
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
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 |
|
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 |
|
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 |
|
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
See also copy, template, assemble
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 |
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
See the advanced playbooks chapter for more about using fireball mode.
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 |
|
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 |
|
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
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 |
|
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 |
|
if no , it will not use a proxy, even if one is defined by in an environment variable on the target hosts. |
get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
This module doesn't yet support configuration for proxies.
New in version 0.0.1.
Manage git checkouts of repositories to deploy files or software.
parameter | required | default | choices | comments |
---|---|---|---|---|
dest | yes | Absolute path of where the repository should be checked out to. | ||
force | no | yes |
|
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://git@github.com/mylogin/hello.git dest=/home/mylogin/hello
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 |
|
Whether the group should be present or not on the remote host. |
system | no | no |
|
If yes, indicates that the group created is a system group. |
Example group command from Ansible Playbooks
group: name=somegroup state=present
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}
Spaces in group names are converted to dashes '-'.
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 |
|
Discards uncommited changes. Runs hg update -C . |
purge | no | 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
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.
New in version 1.1.
Manages Homebrew packages
parameter | required | default | choices | comments |
---|---|---|---|---|
name | yes | name of package to install/remove | ||
state | no | present |
|
state of the package |
update_homebrew | no | 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
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 |
|
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. |
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
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.
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 state=present regexp='^(.*)Xms(\d+)m(.*)$' line='\\1Xms${xms}m\\3'
New in version 1.1.
This module creates, removes or resizes volume groups.
parameter | required | default | choices | comments |
---|---|---|---|---|
force | no | 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 |
|
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
module does not modify PE size for already present volume group
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 |
|
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
Filesystems on top of the volume are not resized.
New in version 1.1.
Manages MacPorts packages
parameter | required | default | choices | comments |
---|---|---|---|---|
name | yes | name of package to install/remove | ||
state | no | present |
|
state of the package |
update_cache | no | 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
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="jane@example.net (Jane Jolie)" to="John Doe <j.d@example.org>, Suzie Something <sue@example.com>" cc="Charlie Root <root@localhost>" attach="/etc/group /tmp/pavatar2.png" headers=Reply-To=john@example.com|X-Special="Something or other" charset=utf8
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 |
|
The database user state |
user | yes | The name of the user to add or remove |
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
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
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 |
|
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
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 |
|
The database state |
target | no | Where to dump/get the .sql file |
Create a new database with name 'bobdata'
mysql_db: db=bobdata state=present
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.
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 |
|
The database state |
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
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.
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 |
|
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 | raw command to send to nagiosshould not include the submitted time header or the line-feedRequired 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. |
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'
Manages Citrix NetScaler server and service entities.
parameter | required | default | choices | comments |
---|---|---|---|---|
action | no | 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 |
|
type of the entity |
user | yes | username |
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"
New in version 0.6.
Similar to the facter module, this runs the Ohai discovery program (http://wiki.opscode.com/display/chef/Ohai) on the remote host and returns JSON inventory data. Ohai data is a bit more verbose and nested than facter.
Retrieve ohai data from all Web servers and store in one-file per host
ansible webservers -m ohai --tree=/tmp/ohaidata
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 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
New in version 1.1.
Manages OpenWrt packages
parameter | required | default | choices | comments |
---|---|---|---|---|
name | yes | name of package to install/remove | ||
state | no | present |
|
state of the package |
update_cache | no | 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
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 |
|
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
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"
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
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 |
|
The state of module |
use_mirrors | no | yes |
|
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 |
|
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) |
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'
Please note that virtualenv (http://www.virtualenv.org/) must be installed on the remote host if the virtualenv parameter is specified.
New in version 1.0.
Manages SmartOS packages
parameter | required | default | choices | comments |
---|---|---|---|---|
name | yes | name of package to install/remove | ||
state | no | present |
|
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
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 | ||
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 |
|
The database state |
template | no | Template used to create the database |
Create a new database with name acme
postgresql_db: db=acme
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.
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 |
|
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 |
|
PostgreSQL role attributes string in the format: CREATEDB,CREATEROLE,SUPERUSER | |
state | no | present |
|
The user (role) state |
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
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.
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 |
|
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
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 |
|
Only enable missing pluginsDoes not disable plugins that are not in the names list |
state | no | enabled |
|
Specify if pluginss are to be enabled or disabled |
Enables the rabbitmq_management plugin
rabbitmq_plugin names=rabbitmq_management state=enabled
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 |
|
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 |
|
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
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 |
|
The state of vhost |
tracing | no | no |
|
Enable/disable tracing for a vhost |
Ensure that the vhost /test exists.
rabbitmq_vhost: name=/test state=present
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
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.
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 |
rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
this module fetches the system id from RHN.
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). | ||
expiry | no | 600 | expiry period (in seconds) for returned download URL. | |
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. |
Simple playbook example
s3 bucket=mybucket path=/path/to/file state=present
The script module takes the script name followed by a list of space-delimited arguments. The given script will be processed through the shell environment. 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
It is preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
New in version 0.7.
Toggles SELinux booleans.
parameter | required | default | choices | comments |
---|---|---|---|---|
name | yes | Name of the boolean to configure | ||
persistent | no |
|
Set to yes if the boolean setting should survive a reboot |
|
state | yes |
|
Desired boolean value |
Set httpd_can_network_connect SELinux flag to true and persistent
seboolean: name=httpd_can_network_connect state=true persistent=yes
Not tested on any debian based system
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 |
|
The SELinux mode |
selinux: policy=targeted state=enforcing
selinux: policy=targeted state=permissive
selinux: state=disabled
Not tested on any debian based system
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 |
|
Whether the service should start on boot. | |
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 are idempotent actions that will not run commands unless necessary. restarted will always bounce the service. reloaded will always reload. |
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 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
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]'
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.
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
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.
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" }
See also: fetch
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 |
|
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
Requres svn to be installed on the client.
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 |
|
The state of service |
Manage the state of program my_app to be in started state.
supervisorctl: name=my_app state=started
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 |
|
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
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 |
|
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 |
|
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 |
|
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
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 |
|
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. |
Example from Ansible Playbooks
template: src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644
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)
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 |
|
Whether or not the URI module should follow all redirects. |
force_basic_auth | no | 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 |
|
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 |
|
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. |
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}"
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 |
|
Unless set to no , a home directory will be made for the user when the account is created. |
force | no | no |
|
When used with state=absent , behavior is as with userdel --force . |
generate_ssh_key | no | 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 |
|
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 |
|
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 |
|
Whether the account should exist. When absent , removes the user account. |
system | no | 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. |
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
New in version 1.1.
creates VM instances via vagrant and optionally waits for it to be ‘running’. This module has a dependency on python-vagrant.
parameter | required | default | choices | comments |
---|---|---|---|---|
box_name | no | vagrant boxed image to start | ||
box_path | no | path to vagrant boxed image to start | ||
cmd | no | vagrant subcommand to execute. Can be "up," "status," "config," "ssh," "halt," "destroy" or "clear." | ||
count | no | 1 | number of instances to launch | |
forward_ports | no | comma separated list of ports to forward to the host. If the port is under 1024, the host port will be the guest port +10000 | ||
memory | no | memory in MB | ||
state | no | Should the VMs be "present" or "absent." | ||
vm_name | no | name to give an associated VM |
local_action: vagrant cmd=up box_name=lucid32 vm_name=webserver
New in version 0.2.
Manages virtual machines supported by libvirt.
parameter | required | default | choices | comments |
---|---|---|---|---|
command | no |
|
in addition to state management, various non-idempotent commands are available. See examples | |
name | yes | name of the guest VM being managed | ||
state | no | no |
|
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. |
Example from Ansible Playbooks
virt: name=alpha state=running
Example guest management with /usr/bin/ansible
ansible host -m virt -a "name=alpha command=status"
Use /usr/bin/ansible
to get the xml of the guest machine alpha
ansible host -m virt -a "name=alpha command=get_xml"
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 |
|
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
Will install, upgrade, remove, and list packages with the yum package manager.
parameter | required | default | choices | comments |
---|---|---|---|---|
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 |
|
whether to install (present , latest ), or remove (absent ) a package. |
yum name=httpd state=latest
yum name=httpd state=removed
yum name=httpd enablerepo=testing state=installed
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 |
|
The aclinherit property. | |
aclmode | no |
|
The aclmode property. | |
atime | no |
|
The atime property. | |
canmount | no |
|
The canmount property. | |
casesensitivity | no |
|
The casesensitivity property. | |
checksum | no |
|
The checksum property. | |
compression | no |
|
The compression property. | |
copies | no |
|
The copies property. | |
dedup | no |
|
The dedup property. | |
devices | no |
|
The devices property. | |
exec | no |
|
The exec property. | |
jailed | no |
|
The jailed property. | |
logbias | no |
|
The logbias property. | |
mountpoint | no | The mountpoint property. | ||
name | yes | File system, snapshot or volume name e.g. rpool/myfs |
||
nbmand | no |
|
The nbmand property. | |
normalization | no |
|
The normalization property. | |
primarycache | no |
|
The primarycache property. | |
quota | no | The quota property. | ||
readonly | no |
|
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 |
|
The secondarycache property. | |
setuid | no |
|
The setuid property. | |
shareiscsi | no |
|
The shareiscsi property. | |
sharenfs | no | The sharenfs property. | ||
sharesmb | no | The sharesmb property. | ||
snapdir | no |
|
The snapdir property. | |
state | yes |
|
Whether to create (present ), or remove (absent ) a file system, snapshot or volume. |
|
sync | no |
|
The sync property. | |
utf8only | no |
|
The utf8only property. | |
volblocksize | no | The volblocksize property. | ||
volsize | no | The volsize property. | ||
vscan | no |
|
The vscan property. | |
xattr | no |
|
The xattr property. | |
zoned | no |
|
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
See Module Development.
See also