< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
< html xmlns = "http://www.w3.org/1999/xhtml" >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" / >
< title > Ansible Modules — Ansible - SSH-Based Configuration Management & Deployment< / title >
< link rel = "stylesheet" href = "_static/default.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/pygments.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/bootstrap.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/bootstrap-sphinx.css" type = "text/css" / >
< script type = "text/javascript" >
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.01',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: false
};
< / script >
< script type = "text/javascript" src = "_static/jquery.js" > < / script >
< script type = "text/javascript" src = "_static/underscore.js" > < / script >
< script type = "text/javascript" src = "_static/doctools.js" > < / script >
< script type = "text/javascript" src = "_static/bootstrap-dropdown.js" > < / script >
< script type = "text/javascript" src = "_static/bootstrap-scrollspy.js" > < / script >
< link rel = "top" title = "Ansible - SSH-Based Configuration Management & Deployment" href = "index.html" / >
< link rel = "next" title = "YAML Syntax" href = "YAMLSyntax.html" / >
< link rel = "prev" title = "Command Line Examples" href = "examples.html" / >
< script type = "text/javascript" >
(function () {
/**
* Patch TOC list.
*
* Will mutate the underlying span to have a correct ul for nav.
*
* @param $span: Span containing nested UL's to mutate.
* @param minLevel: Starting level for nested lists. (1: global, 2: local).
*/
var patchToc = function ($span, minLevel) {
var $tocList = $("< ul / > ").attr('class', "dropdown-menu"),
findA;
// Find all a "internal" tags, traversing recursively.
findA = function ($elem, level) {
var level = level || 0,
$items = $elem.find("> li > a.internal, > ul, > li > ul");
// Iterate everything in order.
$items.each(function (index, item) {
var $item = $(item),
tag = item.tagName.toLowerCase(),
pad = 10 + ((level - minLevel) * 10);
if (tag === 'a' & & level >= minLevel) {
// Add to existing padding.
$item.css('padding-left', pad + "px");
// Add list element.
$tocList.append($("< li / > ").append($item));
} else if (tag === 'ul') {
// Recurse.
findA($item, level + 1);
}
});
};
// Start construction and return.
findA($span);
// Wipe out old list and patch in new one.
return $span.empty("ul").append($tocList);
};
$(document).ready(function () {
// Patch the global and local TOC's to be bootstrap-compliant.
patchToc($("span.globaltoc"), 1);
patchToc($("span.localtoc"), 2);
// Activate.
$('#topbar').dropdown();
});
}());
< / script >
< script type = "text/javascript" >
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-29861888-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type =
'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
})();
< / script >
< / head >
< body >
< div class = "topbar" data-scrollspy = "scrollspy" >
< div class = "topbar-inner" >
< div class = "container" >
< a class = "brand" href = "index.html" > Ansible< / a >
< ul class = "nav" >
< li class = "dropdown" data-dropdown = "dropdown" >
< a href = "index.html"
class="dropdown-toggle">Chapter< / a >
< span class = "globaltoc" > < ul class = "current" >
< li class = "toctree-l1" > < a class = "reference internal" href = "gettingstarted.html" > Downloads & Getting Started< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "patterns.html" > The Inventory File, Patterns, and Groups< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "examples.html" > Command Line Examples< / a > < / li >
< li class = "toctree-l1 current" > < a class = "current reference internal" href = "" > Ansible Modules< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "YAMLSyntax.html" > YAML Syntax< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "playbooks.html" > Playbooks< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "api.html" > API & Integrations< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "moduledev.html" > Module Development Guide< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "faq.html" > Frequently Asked Questions< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "man.html" > Man Pages< / a > < / li >
< / ul >
< / span >
< / li >
< li class = "dropdown" data-dropdown = "dropdown" >
< a href = "#"
class="dropdown-toggle">Page< / a >
< span class = "localtoc" > < ul >
< li > < a class = "reference internal" href = "#" > Ansible Modules< / a > < ul >
< li > < a class = "reference internal" href = "#command" > command< / a > < / li >
< li > < a class = "reference internal" href = "#copy" > copy< / a > < / li >
< li > < a class = "reference internal" href = "#facter" > facter< / a > < / li >
< li > < a class = "reference internal" href = "#file" > file< / a > < / li >
< li > < a class = "reference internal" href = "#git" > git< / a > < / li >
< li > < a class = "reference internal" href = "#ohai" > ohai< / a > < / li >
< li > < a class = "reference internal" href = "#ping" > ping< / a > < / li >
< li > < a class = "reference internal" href = "#service" > service< / a > < / li >
< li > < a class = "reference internal" href = "#setup" > setup< / a > < / li >
< li > < a class = "reference internal" href = "#shell" > shell< / a > < / li >
< li > < a class = "reference internal" href = "#template" > template< / a > < / li >
< li > < a class = "reference internal" href = "#yum" > yum< / a > < / li >
< li > < a class = "reference internal" href = "#writing-your-own-modules" > Writing your own modules< / a > < / li >
< / ul >
< / li >
< / ul >
< / span >
< / li >
< / ul >
< ul class = "nav secondary-nav" >
< form class = "pull-left" action = "search.html" method = "get" >
< input type = "text" name = "q" placeholder = "Search" / >
< input type = "hidden" name = "check_keywords" value = "yes" / >
< input type = "hidden" name = "area" value = "default" / >
< / form >
< / ul >
< / div >
< / div >
< / div >
< div class = "container" >
< div class = "section" id = "ansible-modules" >
< h1 > Ansible Modules< a class = "headerlink" href = "#ansible-modules" title = "Permalink to this headline" > ¶< / a > < / h1 >
< p > Ansible ships with a number of modules (called the ‘ module library’ )
that can be executed directly on remote hosts or through < a class = "reference internal" href = "playbooks.html" > < em > Playbooks< / em > < / a > .
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.< / p >
< p > Let’ s review how we execute three different modules from the command line:< / p >
< div class = "highlight-python" > < pre > ansible webservers -m service -a "name=httpd state=running"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"< / pre >
< / div >
< p > Each module supports taking arguments. Nearly all modules take < tt class = "docutils literal" > < span class = "pre" > key=value< / span > < / tt >
arguments, space delimited. Some modules take
no arguments, and the command/shell modules simply take the string
of the command you want to run.< / p >
< p > From playbooks, Ansible modules are executed in a very similar way:< / p >
< div class = "highlight-python" > < pre > - name: reboot the servers
action: command /sbin/reboot -t now< / pre >
< / div >
< p > 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 tho choose.< / p >
< p > Most modules other than command are < cite > idempotent< / cite > , 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’ . Unless otherwise
noted, any given module does support change hooks.< / p >
< p > Let’ s see what’ s available in the Ansible module library, out of the box:< / p >
< div class = "section" id = "command" >
< span id = "id1" > < / span > < h2 > command< a class = "headerlink" href = "#command" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > The command module takes the command name followed by a list of
arguments, space delimited.< / p >
< p > 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.< / p >
< p > Example usage:< / p >
< div class = "highlight-python" > < pre > /sbin/shutdown -t now< / pre >
< / div >
< p > 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.< / p >
< p > This module does not support change hooks and returns the return code
from the program as well as timing information about how long the
command was running for.< / p >
< / div >
< div class = "section" id = "copy" >
< span id = "id2" > < / span > < h2 > copy< a class = "headerlink" href = "#copy" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > The copy module moves a file on the local box to remote locations. In addition to the options
listed below, the arguments available to the < cite > file< / cite > module can also be passed to the copy
module.< / p >
< p > < em > src< / em > :< / p >
< ul class = "simple" >
< li > Local path to a file to copy to the remote server. This can be an
absolute or relative path.< / li >
< / ul >
< p > < em > dest< / em > :< / p >
< ul class = "simple" >
< li > Remote absolute path where the file should end up.< / li >
< / ul >
< p > This module also returns md5sum information about the resultant file.< / p >
< / div >
< div class = "section" id = "facter" >
< span id = "id3" > < / span > < h2 > facter< a class = "headerlink" href = "#facter" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Runs the discovery program ‘ facter’ on the remote system, returning
JSON data that can be useful for inventory purposes.< / p >
< p > Requires that ‘ facter’ and ‘ ruby-json’ be installed on the remote end.< / p >
< p > This module is informative only - it takes no parameters & does not
support change hooks, nor does it make any changes on the system.
Playbooks do not actually use this module, they use the < a class = "reference internal" href = "#setup" > < em > setup< / em > < / a >
module behind the scenes.< / p >
< / div >
< div class = "section" id = "file" >
< h2 > file< a class = "headerlink" href = "#file" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Sets attributes of files and directories, or removes files/directories. All parameters available
to the file module are also available when running the < cite > copy< / cite > or < cite > template< / cite > modules.< / p >
< p > < em > dest< / em > :< / p >
< ul class = "simple" >
< li > absolute path to a file on the filesystem.< / li >
< / ul >
< p > < em > state< / em > :< / p >
< ul class = "simple" >
< li > either ‘ file’ , ‘ directory’ , or ‘ absent’ . The default is ‘ file’ . If ‘ directory’ , the directory and all immediate subdirectories will be created if they do not exist. If ‘ file’ , the file will NOT be created if it does not exist, specify < cite > copy< / cite > or < cite > template< / cite > for the module name instead if you need to put content at the specified location. If ‘ absent’ , directories will be recursively deleted, and files or symlinks will be unlinked.< / li >
< / ul >
< p > < em > mode< / em > :< / p >
< ul class = "simple" >
< li > the mode the file or directory should be, such as 644, as would be given to < cite > chmod< / cite > . English modes like “ g+x” are not yet supported.< / li >
< / ul >
< p > < em > owner< / em > :< / p >
< ul class = "simple" >
< li > name of user that should own the file or directory, as would be given to < cite > chown< / cite > .< / li >
< / ul >
< p > < em > group< / em > :< / p >
< ul class = "simple" >
< li > name of group that should own the file or directory, as would be given to < cite > chgrp< / cite > < / li >
< / ul >
< / div >
< div class = "section" id = "git" >
< h2 > git< a class = "headerlink" href = "#git" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Deploys software (or files) from git checkouts.< / p >
< p > < em > repo< / em > :< / p >
< ul class = "simple" >
< li > git or http protocol address of the repo to checkout.< / li >
< / ul >
< p > < em > dest< / em > :< / p >
< ul class = "simple" >
< li > Where to check it out, an absolute directory path.< / li >
< / ul >
< p > < em > version< / em > :< / p >
< ul class = "simple" >
< li > What version to check out – either the git SHA, the literal string
< tt class = "docutils literal" > < span class = "pre" > HEAD< / span > < / tt > , or a tag name.< / li >
< / ul >
< / div >
< div class = "section" id = "ohai" >
< h2 > ohai< a class = "headerlink" href = "#ohai" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Similar to the < a class = "reference internal" href = "#facter" > < em > facter< / em > < / a > module, this returns JSON inventory data.
Ohai data is a bit more verbose and nested than facter.< / p >
< p > Requires that ‘ ohai’ be installed on the remote end.< / p >
< p > This module is information only - it takes no parameters & does not
support change hooks, nor does it make any changes on the system.< / p >
< p > Playbooks should not call the ohai module, playbooks call the
< a class = "reference internal" href = "#setup" > < em > setup< / em > < / a > module behind the scenes instead.< / p >
< / div >
< div class = "section" id = "ping" >
< h2 > ping< a class = "headerlink" href = "#ping" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > A trivial test module, this module always returns the integer < tt class = "docutils literal" > < span class = "pre" > 1< / span > < / tt > on
successful contact.< / p >
< p > This module does not support change hooks and is informative only - it
takes no parameters & does not support change hooks, nor does it make
any changes on the system.< / p >
< / div >
< div class = "section" id = "service" >
< h2 > service< a class = "headerlink" href = "#service" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Controls services on remote machines.< / p >
< p > < em > state< / em > :< / p >
< ul class = "simple" >
< li > Values are < tt class = "docutils literal" > < span class = "pre" > started< / span > < / tt > , < tt class = "docutils literal" > < span class = "pre" > stopped< / span > < / tt > , or < tt class = "docutils literal" > < span class = "pre" > restarted< / span > < / tt > .
Started/stopped are idempotent actions that will not run commands
unless necessary. < tt class = "docutils literal" > < span class = "pre" > restarted< / span > < / tt > will always bounce the service.< / li >
< / ul >
< p > < em > name< / em > :< / p >
< ul class = "simple" >
< li > The name of the service.< / li >
< / ul >
< / div >
< div class = "section" id = "setup" >
< span id = "id4" > < / span > < h2 > setup< a class = "headerlink" href = "#setup" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Writes a JSON file containing key/value data, for use in templating.
Call this once before using the < a class = "reference internal" href = "#template" > < em > template< / em > < / a > module. Playbooks
will execute this module automatically as the first step in each play
using the variables section, so it is unnecessary to make explicit
calls to setup within a playbook.< / p >
< p > 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 < tt class = "docutils literal" > < span class = "pre" > facter_< / span > < / tt > and < tt class = "docutils literal" > < span class = "pre" > ohai_< / span > < / tt > so it’ s easy to
tell their source. All variables are then bubbled up to the caller.< / p >
< p > < em > anything< / em > :< / p >
< blockquote >
< div > < ul class = "simple" >
< li > Any other parameters can be named basically anything, and set a
< tt class = "docutils literal" > < span class = "pre" > key=value< / span > < / tt > pair in the JSON file for use in templating.< / li >
< / ul >
< / div > < / blockquote >
< / div >
< div class = "section" id = "shell" >
< span id = "id5" > < / span > < h2 > shell< a class = "headerlink" href = "#shell" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > The shell module takes the command name followed by a list of
arguments, space delimited. It is almost exactly like the command module
but runs the command through the shell rather than directly.< / p >
< p > Example usage:< / p >
< div class = "highlight-python" > < pre > find . | grep *.txt< / pre >
< / div >
< p > The given command will be executed on all selected nodes.< / p >
< p > If you want to execute a command securely and predicably, it may
be better to use the ‘ command’ module instead. Best practices
when writing playbooks will follow the trend of using ‘ command’
unless ‘ shell’ is explicitly required. When running ad-hoc commands,
use your best judgement.< / p >
< p > This module does not support change hooks and returns the return code
from the program as well as timing information about how long the
command was running for.< / p >
< / div >
< div class = "section" id = "template" >
< span id = "id6" > < / span > < h2 > template< a class = "headerlink" href = "#template" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Templates a file out to a remote server. Call the < a class = "reference internal" href = "#setup" > < em > setup< / em > < / a > module
prior to usage if you are not running from a playbook. In addition to the options
listed below, the arguments available to the < cite > file< / cite > module can also be passed to the copy
module.< / p >
< p > < em > src< / em > :< / p >
< ul class = "simple" >
< li > Path of a Jinja2 formatted template on the local server. This can
be a relative or absolute path.< / li >
< / ul >
< p > < em > dest< / em > :< / p >
< ul class = "simple" >
< li > Location to render the template on the remote server.< / li >
< / ul >
< p > This module also returns md5sum information about the resultant file.< / p >
< / div >
< div class = "section" id = "yum" >
< span id = "id7" > < / span > < h2 > yum< a class = "headerlink" href = "#yum" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Will install, upgrade, remove, and list packages with the yum package manager.< / p >
< p > < em > pkg< / em > :< / p >
< ul class = "simple" >
< li > A package name or package specifier with version, like name-1.0< / li >
< / ul >
< p > < em > state< / em > :< / p >
< ul class = "simple" >
< li > Can be either ‘ installed’ , ‘ latest’ , or ‘ removed’ < / li >
< / ul >
< p > < em > list< / em > :< / p >
< ul class = "simple" >
< li > When ‘ list’ is supplied instead of ‘ state’ , the yum module can list
various configuration attributes. Values include ‘ installed’ , ‘ updates’ ,
‘ available’ , ‘ repos’ , or any package specifier.< / li >
< / ul >
< / div >
< div class = "section" id = "writing-your-own-modules" >
< h2 > Writing your own modules< a class = "headerlink" href = "#writing-your-own-modules" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > See < a class = "reference internal" href = "moduledev.html" > < em > Module Development Guide< / em > < / a > .< / p >
< div class = "admonition-see-also admonition seealso" >
< p class = "first admonition-title" > See also< / p >
< dl class = "last docutils" >
< dt > < a class = "reference internal" href = "examples.html" > < em > Command Line Examples< / em > < / a > < / dt >
< dd > Examples of using modules in /usr/bin/ansible< / dd >
< dt > < a class = "reference internal" href = "playbooks.html" > < em > Playbooks< / em > < / a > < / dt >
< dd > Examples of using modules with /usr/bin/ansible-playbook< / dd >
< dt > < a class = "reference internal" href = "moduledev.html" > < em > Module Development Guide< / em > < / a > < / dt >
< dd > How to write your own modules< / dd >
< dt > < a class = "reference internal" href = "api.html" > < em > API & Integrations< / em > < / a > < / dt >
< dd > Examples of using modules with the Python API< / dd >
< dt > < a class = "reference external" href = "http://groups.google.com/group/ansible-project" > Mailing List< / a > < / dt >
< dd > Questions? Help? Ideas? Stop by the list on Google Groups< / dd >
< dt > < a class = "reference external" href = "http://irc.freenode.net" > irc.freenode.net< / a > < / dt >
< dd > #ansible IRC chat channel< / dd >
< / dl >
< / div >
< / div >
< / div >
< / div >
< footer class = "footer" >
< div class = "container" >
< p class = "pull-right" > < a href = "#" > Back to top< / a > < / p >
< p >
© Copyright 2012 Michael DeHaan.< br / >
Last updated on Mar 21, 2012.< br / >
Created using < a href = "http://sphinx.pocoo.org/" > Sphinx< / a > 1.0.8.< br / >
< / p >
< / div >
< / footer >
< / body >
< / html >
